摘要：你是否曾被微服务架构的复杂性劝退？管理一堆相互依赖的服务、配置日志追踪、调试跨服务调用、部署到云端……这些琐碎的工作足以让一个开发者精疲力尽。别担心！微软推出的 .NET Aspire 9.4 正是为了解决这些问题而生。它不是一个高深莫测的框架，而是一套贴心的“工具箱+总指挥”，旨在让你像开发单体应用一样轻松地构建现代化的云原生应用。本教程将用最通俗的语言，带你从零开始，一步步掌握 .NET Aspire 9.4 的核心奥秘。

重要提示：本文所有内容均基于 .NET 9.0 SDK (9.0.100-preview.7+) 和 .NET Aspire 9.4。请确保你的开发环境已更新至相应预览版本。

---

引言：为什么我们需要 .NET Aspire？

想象一下，你要开一家大型连锁餐厅（你的应用）。为了高效运营，你决定将业务拆分成几个独立的部门：

• 前台点餐部（Web API）：负责接待顾客、接收订单。
• 后厨烹饪部（后台服务）：负责根据订单炒菜。
• 中央冷库（数据库）：存放所有食材。
• 调料仓库（缓存）：存放常用的油盐酱醋，加快出餐速度。

在没有 .NET Aspire 的世界里，你会怎么做？

1. 各自为政：你分别雇佣了四个经理，每人负责一个部门。他们有自己的工作手册、对讲机频道和进货渠道。
2. 沟通成本高：点餐部下了个牛肉订单，但后厨发现冷库没货了。两个经理得打电话协调，耽误上菜。
3. 问题难定位：有顾客投诉上菜太慢。你不知道是点餐系统卡了，还是后厨人手不够，还是冷库取货慢。你得挨个部门去查。
4. 扩张困难：现在你想在另一个城市开分店（部署到云上），每个经理都要重新写一遍工作手册，过程繁琐且容易出错。

结果：管理成本高，效率低下，问题频发。

.NET Aspire 9.4 就是那个全能的“餐厅总指挥”。他手里有一张全局运营蓝图，统一管理所有部门，并配备了一个智能中央监控室，让你对整个餐厅的运营状况了如指掌。这就是 .NET Aspire 的核心价值：简化复杂，赋能开发者。

---

第一章：初识 .NET Aspire 9.4 —— 你的“总指挥”

1.1 .NET Aspire 9.4 到底是什么？

.NET Aspire 9.4 是微软官方推出的应用堆栈（App Stack）。它不是一个你需要学习新语法的编程框架，而是一套精心打包的工具、模板和最佳实践。它的目标只有一个：让开发、测试和部署由多个服务组成的现代应用变得前所未有的简单。

它主要由三部分组成：

• AppHost（应用主机）：这就是我们的“总指挥”。它定义了你的应用由哪些服务（点餐部、后厨等）组成，以及它们之间如何连接。
• ServiceDefaults（服务默认项）：这是“总指挥”发给每个部门经理的标准化工作手册。里面规定了统一的汇报格式（日志）、健康检查方式、以及如何接入中央监控系统。
• Dashboard（仪表盘）：这就是“智能中央监控室”。在开发阶段，你可以在这里实时看到所有部门的运行状态、处理的订单（请求）、遇到的问题（错误）等。

1.2 准备你的“工地”

要开始使用 .NET Aspire 9.4，你需要准备以下工具：

1. .NET 9.0 SDK (9.0.100-preview.7 或更高版本)：这是基础建筑材料。
   • 你可以通过命令 dotnet --list-sdks 来检查已安装的版本。
   • 如果尚未安装，可以从 .NET 9 Preview 下载页面 获取。
2. Visual Studio 2022 (17.12 Preview 或更高版本) 或 VS Code + C# Dev Kit：这是你的设计和施工工具。
3. Docker Desktop (4.30.0 或更高版本)：用于在本地模拟“冷库”、“仓库”等外部依赖。

安装 .NET Aspire 9.4 工作负载：
打开终端，运行以下命令以确保安装了最新的 Aspire 9.4 模板：

dotnet workload install aspire --from-rollback-file https://aka.ms/dotnet/aspire/9.4.0/rollback.json

注意：由于 Aspire 9.4 是预览版，我们使用了特定的回滚文件来确保安装正确的版本。

安装完成后，重启你的终端或 IDE。

---

第二章：Hello, Aspire! —— 第一个应用

2.1 创建你的“餐厅蓝图”

在终端中执行以下命令：

# 创建一个名为 "MyRestaurant" 的 Aspire 9.4 解决方案
dotnet new aspire -o MyRestaurant

这个命令会为你生成一个完整的解决方案，结构如下：

MyRestaurant/
├── MyRestaurant.AppHost/        # 总指挥办公室 (AppHost)
├── MyRestaurant.ServiceDefaults/ # 标准化工作手册 (ServiceDefaults)
└── MyRestaurant.Web/            # 前台点餐部 (一个示例 Web API)

2.2 关键变化：AppHost.cs 而非 Program.cs

进入 MyRestaurant.AppHost 目录，你会发现里面没有 Program.cs，而是有一个 AppHost.cs 文件。这就是 .NET Aspire 9.4 的核心入口。

打开 AppHost.cs，你会看到：

// AppHost.cs - 这就是你的“总指挥”的工作台！
var builder = DistributedApplication.CreateBuilder(args);

// 添加一个名为 "webapp" 的部门（即 MyRestaurant.Web 项目）
var webApp = builder.AddProject<Projects.MyRestaurant_Web>("webapp");

// 构建并启动整个餐厅
builder.Build().Run();

2.3 启动你的“智能餐厅”

1. 在 MyRestaurant.AppHost 目录下，执行 dotnet run。
2. 你会看到控制台输出启动日志，最后会显示两个地址：

   Dashboard running on: http://localhost:15000  # 智能监控室入口
   Web app running on: http://localhost:5000     # 前台点餐部入口
   

现在，打开浏览器：

• 访问 http://localhost:5000，你会看到一个简单的 Weather Forecast 页面（这就是你的点餐菜单）。
• 访问 http://localhost:15000，你会进入 .NET Aspire Dashboard！

在这个 Dashboard 里，你可以看到：

• 概览：你的“点餐部”（webapp）正在健康运行。
• 日志：实时滚动着点餐部的内部日志。
• 追踪：每次你刷新 :5000 页面，这里就会记录下一次完整的“点单-处理”流程。

恭喜！你已经成功启动了你的第一个由 .NET Aspire 9.4 管理的应用。

---

第三章：AppHost —— “总指挥”的工作台 (AppHost.cs)

AppHost.cs 是整个 Aspire 应用的核心，它决定了你的应用长什么样。

3.1 定义你的“部门”

在 AppHost.cs 中，AddProject<T> 方法就是“总指挥”在蓝图上画下一个部门。

• <Projects.MyRestaurant_Web>：这是一个源生成器（Source Generator） 自动创建的类型，代表了 MyRestaurant.Web 项目。
• "webapp"：这是你为这个服务起的逻辑名称，将在整个 Aspire 生态中使用。

3.2 添加“中央冷库”和“调料仓库”

真实的餐厅离不开冷库和仓库。在软件世界里，它们就是数据库和缓存。

修改 AppHost.cs:

var builder = DistributedApplication.CreateBuilder(args);

// 1. 添加 Redis 作为“调料仓库”
var cache = builder.AddRedis("cache")
                   .WithDataVolume(); // 持久化数据，重启不丢

// 2. 添加 PostgreSQL 作为“中央冷库”
var db = builder.AddPostgres("db")
                .WithDataVolume()
                .WithPgAdmin(); // 加一个冷库管理界面

// 3. 让“点餐部”依赖于这两个资源
var webApp = builder.AddProject<Projects.MyRestaurant_Web>("webapp")
                    .WithReference(cache) // 告诉点餐部：“调料仓库在这！”
                    .WithReference(db);   // 告诉点餐部：“中央冷库在这！”

builder.Build().Run();

在“点餐部”使用它们:

Aspire 9.4 会自动将连接信息注入到 webapp 服务中。在 MyRestaurant.Web/Program.cs 中读取：

var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();

// 从配置中获取连接字符串
var dbConnectionString = builder.Configuration.GetConnectionString("db");
// ... 使用 connectionString

var app = builder.Build();
app.MapDefaultEndpoints();
app.Run();

神奇之处：当你再次运行 dotnet run 时，Aspire 9.4 会自动：

1. 在 Docker 里启动 Redis 和 PostgreSQL 容器。
2. 自动建立网络连接。
3. 在 Dashboard 的 Resources 页面，清晰地展示出依赖关系图。

---

第四章：ServiceDefaults —— 统一的“工作手册”

为了让所有部门都能被“中央监控室”统一管理，.NET Aspire 9.4 提供了 ServiceDefaults 这个共享库。

4.1 如何使用“工作手册”？

在你的任何一个服务（比如 MyRestaurant.Web）的 Program.cs 中，只需两行代码：

var builder = WebApplication.CreateBuilder(args);

// 1. 应用“标准化工作手册”
builder.AddServiceDefaults();

var app = builder.Build();

// 2. 暴露标准端点（健康检查、指标等）
app.MapDefaultEndpoints();

app.Run();

就是这么简单！从此以后，你的服务就拥有了“被监控”的能力。

---

第五章：服务间通信 —— 部门间的协作

当你的餐厅规模扩大，可能需要增加一个“外卖调度部”（OrderService），它需要向“点餐部”（ProductService）查询菜品信息。

在 AppHost.cs 中建立依赖:

var productService = builder.AddProject<Projects.ProductService>("productservice");
var orderService = builder.AddProject<Projects.OrderService>("orderservice")
                         .WithReference(productService); // 关键！

在 OrderService 中注册客户端:

builder.Services.AddHttpClient<IProductService, ProductServiceClient>(
    client => client.BaseAddress = new("http://productservice"));

发生了什么？

• Aspire 9.4 知道 orderservice 需要调用 productservice。
• 在本地开发时，它会自动将 http://productservice 解析为正确的 localhost:port。
• 你不需要写任何服务发现的代码！

---

第六章：Dashboard —— 你的“中央监控室”

Dashboard 是 .NET Aspire 9.4 在开发阶段最强大的武器。

6.1 实战：定位一个“上菜慢”的问题

假设用户反馈“外卖下单后很久才收到确认”。

1. 打开 Dashboard (http://localhost:15000)。
2. 切换到 Traces（追踪）页面。
3. 找到最近的一次 POST /orders 请求。
4. 点击展开，你会看到一条完整的时间线。
5. 发现问题：你发现数据库查询耗时 2 秒！
6. 深入查看：点击这个 Span，Dashboard 能显示出具体的 SQL 查询语句。

结论：问题出在数据库查询慢。你可以立刻去优化。

---

第七章：部署到云端 —— 开设“分店”

7.1 一键发布

1. 确保已安装 Azure CLI 并登录 (az login)。
2. 在 AppHost 项目目录下，运行发布命令：

# .NET Aspire 9.4 使用新的发布配置文件
dotnet publish -p:PublishProfile=apphost-publish
azd up

幕后发生了什么？

• Aspire 9.4 分析你的 AppHost.cs 蓝图。
• 自动生成 Bicep 模板。
• 自动创建 Azure 资源。
• 自动配置一切。

---

第八章：Aspire 9.4 新特性与最佳实践

8.1 弹性设计

为 HttpClient 添加重试策略：

// .NET 9 内置了强大的弹性处理器
builder.Services.AddHttpClient<IProductService, ProductServiceClient>()
    .AddStandardResilienceHandler(); 

8.2 测试策略

使用 DistributedApplicationTestingBuilder 进行端到端测试：

[Fact]
public async Task OrderService_CanPlaceOrder()
{
    using var app = await DistributedApplicationTestingBuilder
        .CreateAsync<Projects.MyRestaurant_AppHost>();
    await app.StartAsync();

    var httpClient = app.CreateHttpClient("orderservice");
    var response = await httpClient.PostAsJsonAsync("/orders", new { ... });
    response.IsSuccessStatusCode.Should().BeTrue();
}

---

结语

.NET Aspire 9.4 是微软献给 .NET 开发者的一份厚礼。它将云原生开发的最佳实践封装在一个简洁、高效的模型中，极大地降低了微服务架构的入门门槛。通过本教程的学习，你已经掌握了其核心精髓。现在，就用 .NET Aspire 9.4 去构建你的下一个云原生杰作吧！