C# 使用 .NET Aspire 入门实践指南
2026-01-04 21:21:30 #C# #.NET #.NET Aspire #云原生

这篇文章会用通俗的方式，带你从 0 认识 .NET Aspire，并通过一个简化的示例，演示如何在 C# 项目中使用 Aspire 来构建和编排云原生应用。

一、什么是 .NET Aspire？

随着业务复杂度越来越高，很多系统都从「单体应用」演进成了「多服务 / 微服务」架构：多个 API、后台任务、前端、数据库、缓存、消息队列……
开发环境和生产环境的差异也越来越大：本地是 docker-compose，线上是 Kubernetes，加上各种连接串和配置，很容易「环境不一致」。

.NET Aspire 就是微软在 .NET 生态里给出的「云原生应用模型（App Model）」解决方案，目标是：

  • 统一描述整个应用：在一个中心项目里声明所有参与的服务（.NET 项目、容器、数据库、缓存、消息队列等）。
  • 统一管理配置和依赖关系：用 C# 代码（Fluent API）把服务之间的依赖关系描述出来，自动注入连接信息。
  • 内置可观察性：内置 Dashboard，集中查看日志、分布式追踪（Tracing）、指标（Metrics），提升调试效率。

换句话说：你可以用 C# 代码，描述并运行一个「小型云环境」。

二、核心概念快速理解

  • App Host（应用主机）
    一个专门的 .NET 项目（通常以 .AppHost 结尾），用来「编排」整个应用的所有组件。你可以把它理解成「应用级别的 Program.cs」。

  • Service（服务）
    每个 Web API、Worker Service、前端应用、数据库、Redis、消息队列等等，都可以在 Aspire 中被看作一个 Service，由 App Host 统一管理、启动和配置。

  • Resource（资源）
    像 PostgreSQL、SQL Server、Redis、RabbitMQ 等这类「基础设施」，在 Aspire 中作为资源声明，然后由 App Host 创建，并把连接信息分发给需要它的服务。

  • Orchestration（编排）
    使用 Fluent API 的方式，在 C# 代码中描述一个「拓扑图」：有哪些服务、谁依赖谁、需要哪些资源、如何绑定健康检查等。

三、准备开发环境

3.1 安装 .NET SDK

首先确保你已经安装了 .NET 8 SDK（或更新的版本），在命令行中执行：

dotnet --version

如果版本低于 8.x，可以去 .NET 官网 下载最新 SDK 并安装。

3.2 安装 .NET Aspire 模板

安装 Aspire 项目模板：

dotnet new install Aspire.ProjectTemplates

安装完成后，可以用下面的命令确认是否安装成功：

dotnet new aspire

如果能看到对应模板，说明环境已经就绪。

四、第一个 .NET Aspire 示例应用

下面通过一个「Web API + PostgreSQL 数据库」的最小示例，来演示 Aspire 的基本用法。

4.1 用模板创建项目骨架

在一个空目录下执行：

dotnet new aspire-starter -n MyAspireApp

执行完成后，通常会生成类似下面几个项目（具体名称可能略有不同，以模板实际输出为准）：

  • MyAspireApp.AppHost：应用主机，负责编排所有服务与资源。
  • MyAspireApp.ServiceDefaults：跨服务共享的一些默认配置（如日志、健康检查等）。
  • MyAspireApp.ApiService：示例 Web API 服务。

你也可以后续再自己添加新的 Web API / Worker 项目，并注册到 App Host 中。

五、在 App Host 中编排服务与资源

Aspire 的核心配置都写在 App Host 项目中，一般在 Program.cs 或类似入口文件里。

5.1 声明应用与 PostgreSQL 资源

下面这段代码展示了如何在 App Host 中声明一个应用和一个 PostgreSQL 资源，并让 Web API 依赖它：

using Aspire.Hosting;

var builder = DistributedApplication.CreateBuilder(args);

// 声明一个 PostgreSQL 数据库资源
var postgres = builder.AddPostgres("postgres")
    .WithImage("postgres", "16")          // 指定容器镜像和版本
    .WithDataVolume("pgdata")             // 持久化数据卷
    .WithEnvironment("POSTGRES_PASSWORD", "Password123!");

// 在 PostgreSQL 中创建一个逻辑数据库给 API 使用
var apiDb = postgres.AddDatabase("apidb");

// 声明一个 Web API 服务，并把数据库依赖注入进去
var apiService = builder.AddProject<Projects.MyAspireApp_ApiService>("apiservice")
    .WithReference(apiDb);                // 把 apidb 作为依赖引用给 API

builder.Build().Run();

这段代码在「描述」什么？

  • 启动一个 PostgreSQL 容器，名字叫 postgres。
  • 在里面创建一个叫 apidb 的数据库。
  • 启动一个叫 apiservice 的 Web API 项目。
  • 帮你自动把 apidb 的连接信息注入到 apiservice 中（通过配置或环境变量）。

5.2 在 API 项目中消费连接信息

在 MyAspireApp.ApiService 的 Program.cs 里，按正常方式使用配置即可获取数据库连接字符串：

var builder = WebApplication.CreateBuilder(args);

// 从配置中读取 Aspire 注入的连接字符串
var connectionString = builder.Configuration.GetConnectionString("apidb");

// 例如使用 EF Core 注册 DbContext
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(connectionString));

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

app.MapGet("/items", async (AppDbContext db) =>
    await db.Items.ToListAsync());

app.Run();

注意这里没有写死任何数据库连接串，只是在读取 ConnectionStrings:apidb。Aspire 会负责在运行时为你生成并写入正确的配置。

六、运行和观察 Aspire 应用

在 MyAspireApp.AppHost 目录下执行：

dotnet run

此时 Aspire 会自动帮你做几件事情：

  • 启动 PostgreSQL 容器（本地没有镜像会自动拉取）。
  • 启动 apiservice 这个 Web API。
  • 启动 Aspire Dashboard（一个 Web 界面）。

控制台中通常会输出 Dashboard 的访问地址，例如：

Now listening on: https://localhost:17000

你可以在浏览器中打开对应地址，体验 Aspire 的可观察性能力。

6.1 使用 Dashboard 观察应用

在 Aspire Dashboard 中，你可以看到：

  • 服务列表：每个服务的状态、启动命令、端口信息。
  • 日志（Logs）：集中查看所有服务的日志输出。
  • 追踪（Traces）：查看一个请求在不同服务之间的调用链路。
  • 指标（Metrics）：例如请求次数、耗时、错误率等。

对于本地开发和调试多服务应用来说，这个 Dashboard 非常实用。

七、继续扩展：添加更多服务和依赖

Aspire 的真正价值，在于拓扑图可以自然地扩展。当你需要增加新的服务和基础设施时，不需要「重新设计整套 docker-compose / Kubernetes 配置」，而是只要在 App Host 里继续写 C# 代码。

比如：

  • 为现有应用增加一个前端 WebApp，依赖 apiservice。
  • 增加 Redis 缓存、消息队列（RabbitMQ）、对象存储（Blob Storage）等资源。
  • 为不同服务配置不同的环境变量、健康检查路径等。

下面这个例子演示了如何在现有基础上再加一个 Redis 和一个 Worker 服务：

var builder = DistributedApplication.CreateBuilder(args);

// 之前的 postgres / apidb / apiservice 声明在此略去...

// 添加 Redis 资源
var redis = builder.AddRedis("redis")
    .WithImage("redis", "7");

// 添加一个后台 Worker 服务，并引用 Redis
var worker = builder.AddProject<Projects.MyAspireApp_WorkerService>("workerservice")
    .WithReference(redis);

builder.Build().Run();

在 WorkerService 项目中，只需要像平时一样读取配置中的 redis 连接信息（例如 ConnectionStrings:redis 或相关环境变量），就可以直接使用。

八、与 docker-compose / Kubernetes 的关系

很多同学可能会问：我已经有 docker-compose / Kubernetes 了，还需要 Aspire 吗？

可以从「开发阶段」和「部署阶段」两个角度来看：

8.1 开发阶段

在本地开发时，Aspire 更像是一个「开发体验增强版的 docker-compose」：

  • 用 C# 代码描述服务拓扑，而不是写 YAML。
  • 自动管理 .NET 项目、容器、数据库等的启动顺序和依赖。
  • 内置 Dashboard，统一查看日志、Tracing、Metrics。

如果你的项目主要是 .NET 技术栈，开发体验会比直接维护一大堆 compose / k8s 配置文件更友好。

8.2 部署阶段

Aspire 也可以帮助你生成部署相关的配置（例如 Kubernetes 清单、Azure 相关配置等），减少手写 YAML 的工作量。
同时，它并不会强行「绑死」你的 CI/CD 方案：你可以选择只在本地开发调试阶段使用 Aspire，线上仍然沿用已有的 Kubernetes 部署体系。

九、适合使用 .NET Aspire 的典型场景

比较适合：

  • 微服务 / 分布式系统开发
    多个 API、后台任务、前端、数据库、缓存、队列等需要协同开发时，Aspire 能把它们统一在一个 App Host 里管理。

  • 需要统一可观察性的团队
    希望开发阶段就能看到整体调用链、集中日志和指标，快速定位问题。

  • 多环境一致性管理
    开发 / 测试 / 预发 / 生产，希望有一个一致的服务拓扑与配置模型。

暂时不太必要：

  • 只有一个非常简单的单体 Web 项目，用普通 ASP.NET Core 就可以搞定。
  • 大部分服务都不是 .NET 技术栈，Aspire 的价值会打折。

十、实践建议与小结

最后给几个实践建议，方便你在真实项目中逐步落地：

  • 从一个小场景开始迁移
    比如只把「某个 API + 一个数据库」迁移到 Aspire 模型中，先熟悉 App Host 的编排方式。

  • 坚持在本地用 Aspire 调试全链路
    让团队习惯在 Aspire Dashboard 中看日志、Tracing、Metrics，可以极大提升问题排查效率。

  • 逐步接入更多基础设施
    随着熟练度提高，再慢慢接入 Redis、消息队列、对象存储等资源，把整个系统的拓扑搬到 Aspire 中统一描述。

总结一句话：
对于 C# / .NET 开发者来说，.NET Aspire 提供了一种「用代码描述整个应用和基础设施」的方式，让你在本地就能获得接近云端的运行体验和可观察性，是构建现代云原生应用时非常值得尝试的一套模型与工具链。

Prev
2026-01-04 21:21:30 #C# #.NET #.NET Aspire #云原生