# .NET Aspire 集成技能此技能有助于将 .NET Aspire 添加到现有 .NET 解决方案或创建新的支持 Aspire 的分布式应用程序。它为编排、服务发现、组件集成、配置管理和部署提供模块化指导。 ## 什么是 .NET Aspire？ .NET Aspire 是一个固执己见的、云就绪的堆栈，用于构建可观察的、生产就绪的分布式应用程序。它提供： * **服务编排** \- 通过依赖管理协调多个项目和服务 * **服务发现** \- 服务之间的自动发现和连接 * **遥测和可观测性** \- 内置日志记录、指标和分布式跟踪 * **配置管理** \- 具有强类型和机密性的集中配置 * **资源配置** \- 与数据库、缓存、消息传递和云服务集成 * **开发者仪表板** \- 本地监控和调试界面 ## 何时使用此技能在以下情况下使用此技能： * 将 Aspire 添加到具有多种服务的现有 .NET 解决方案中 * 使用 Aspire 创建新的分布式应用程序 * 现代化微服务或分布式系统以进行云部署 * 设置服务编排以进行本地开发和部署 * 集成云原生可观测性和配置模式 ## 我需要什么组件/功能？需要|资源 |描述 ---|---|--- **总体结构** |概述与设置 |从分析到运行分步实施 **数据库、缓存、消息传递** | `资源/组件.md` |所有可用的 Aspire 组件包及示例 **服务间通信** | `资源/服务通信.md` |服务发现、HttpClient 模式、弹性 **配置和秘密** | `资源/配置管理.md` |环境设置、秘密、功能标志 **本地发展** | `resources/local-development.md` |仪表板、调试、测试、健康检查 **生产部署** | `资源/部署.md` | Azure 容器应用程序、Kubernetes、Docker Compose ## 概述和设置 ### 核心理念 .NET Aspire 使用两个关键项目： * **AppHost** \- 协调服务和资源；提供开发者仪表板 * **ServiceDefaults** \- 所有服务的共享配置（OpenTelemetry、运行状况检查、服务发现） ### 先决条件 # 安装 .NET Aspire 工作负载 dotnet 工作负载安装 aspire # 验证安装 dotnet 工作负载列表 # 应显示“aspire” # Docker Desktop（用于容器资源） # 在启动 AppHost 之前确保它正在运行 ### 基本实现流程 **1\.分析解决方案** * 识别服务（API、Web 应用程序、工作人员） * 列出外部依赖（数据库、Redis、消息队列） * 确定服务通信模式 **2\.创建 Aspire 项目** dotnet new aspire-apphost -n MyApp.AppHost dotnet new aspire-servicedefaults -n MyApp.ServiceDefaults dotnet sln 添加 MyApp.AppHost/MyApp.AppHost.csproj dotnet sln 添加 MyApp.ServiceDefaults/MyApp.ServiceDefaults.csproj **3\.配置服务** * 为每个服务添加ServiceDefaults引用 * 在Program.cs中调用`builder.AddServiceDefaults()` * 为 ASP.NET Core 服务调用 `app.MapDefaultEndpoints()` **4\.在 AppHost 中编排** var builder = DistributedApplication.CreateBuilder(args); var cache = builder.AddRedis(“缓存”); var database = builder.AddPostgres("postgres").AddDatabase("appdb"); var api = builder.AddProject("api") .WithReference(数据库) .WithReference(缓存); var web = builder.AddProject("web") .WithReference(api) .WithExternalHttpEndpoints(); 构建器.Build().Run(); **5\.更新服务通讯** * 用服务名称替换硬编码的 URL * 使用`builder.AddServiceDefaults()`模式匹配 **6\.运行并验证** dotnet run --project MyApp.AppHost # 在 https://localhost:15001 打开仪表板 ## 关键决策 **AppHost项目命名：** * 约定：`[解决方案名称].AppHost` * 示例：对于解决方案“ECommerceSystem”，创建“ECommerceSystem.AppHost” **服务资源名称：** * 在 AppHost 中使用简短的描述性名称 * 示例：“api”、“web”、“worker”、“缓存”、“数据库” * 这些名称用于服务发现 URL **资源管理：** * **本地开发** ：使用 Aspire 管理的容器（PostgreSQL、Redis、RabbitMQ） * **生产** ：由 `azd` 自动配置或手动配置的 Azure 资源 * **连接字符串** ：自动注入；很少需要硬编码 **服务发现设置：** * HttpClient URL 使用服务名称：`http://api` 而不是 `https://localhost:7001` * Aspire 处理服务之间的路由和身份验证 * 外部服务使用显式端点配置 ## 通用架构 ### Web API + 前端 var api = builder.AddProject("api") .WithReference(数据库) .WithExternalHttpEndpoints(); var web = builder.AddProject("web") .WithReference(api) .WithExternalHttpEndpoints(); ### 带有消息队列的微服务 var messages = builder.AddRabbitMQ("messaging"); var orderService = builder.AddProject("orders") .WithReference(消息传递); var inventoryService = builder.AddProject("库存") .WithReference(消息传递); ### 多数据库系统 var postgres = builder.AddPostgres("postgres") .AddDatabase("用户") .AddDatabase("产品"); var mongo = builder.AddMongoDB("mongo") .AddDatabase("订单"); var userApi = builder.AddProject("userapi") .WithReference(postgres); var orderApi = builder.AddProject("orderapi") .WithReference(mongo); ## 资源索引详细实施指导请参见： * **Components** \- 组件包和集成模式： `resources/components.md` * **服务通信** \- 服务发现和服务间调用：`resources/service-communication.md` * **配置管理** \- 秘密、环境变量、设置： `resources/configuration-management.md` * **本地开发** \- 仪表板功能、调试、运行状况检查：`resources/local-development.md` * **部署** \- Azure 容器应用程序、Kubernetes、Docker Compose：`resources/deployment.md` ## 最佳实践 ### 服务组织 * 让AppHost专注于组合，而不是业务逻辑 * 使用 ServiceDefaults 解决跨领域问题（可观察性、健康检查） * 通过后备配置确保每个服务独立运行 ### 资源管理 * 使用 Aspire 管理的资源来实现本地开发的一致性 * 通过`.WithReference()`在AppHost中定义显式依赖 * 为数据库添加数据持久化：`.WithDataVolume()` ### 配置模式 * 开发：使用 `appsettings.Development.json` 和 `.WithEnvironment()` * 生产：使用 Azure Key Vault 或托管机密 * 避免源代码控制中的秘密；在本地使用用户机密 ### 可观察服务 * 通过 ServiceDefaults 启用 OpenTelemetry（自动） * 使用开发者仪表板进行本地调试 * 将遥测数据导出到 Application Insights 或生产中的类似产品 ## 常见问题及解决方案 **服务无法通信** * 验证AppHost中的服务名称与HttpClient URL匹配 * 确保在所有服务中调用 `AddServiceDefaults()` * 检查 ASP.NET 服务是否调用“MapDefaultEndpoints()” **连接字符串未注入** * 使用 `builder.AddNpgsqlDbContext<>()` 代替手动配置 * 验证AppHost和服务之间的数据库/资源名称匹配 * 确认项目文件中存在 ServiceDefaults 引用 **仪表板无法启动** * 确保 Docker Desktop 正在运行 * 检查端口冲突（默认：15001） * 验证AppHost项目运行，而不是单个服务 **健康检查失败** * 在仪表板中查看资源启动日志 * 检查本地机器上的端口可用性 * 验证Docker有足够的资源 ## 入门清单 * 安装.NET Aspire工作负载并验证 * 分析解决方案结构并识别服务 * 创建AppHost和ServiceDefaults项目 * 为每个服务添加ServiceDefaults引用 * 使用 `AddServiceDefaults()` 和 `MapDefaultEndpoints()` 更新服务 Program.cs * 使用服务和资源配置AppHost编排 * 更新服务 HttpClient URL 以使用服务发现名称 * 使用“dotnet run --project AppHost”进行本地测试 * 验证仪表板显示所有正在运行的服务 * 配置部署目标（Azure、Kubernetes等） ## 后续步骤 1. **有关组件详细信息** → 请参阅`resources/components.md` 2. **对于服务通信** → 请参阅 `resources/service-communication.md` 3. **配置** → 请参阅 `resources/configuration-management.md` 4. **对于本地开发** → 请参阅 `resources/local-development.md` 5. **用于部署** → 请参阅 `resources/deployment.md` ** ** **记住**：从单个服务开始，验证通信是否有效，然后增加复杂性。在部署到生产环境之前，使用仪表板在本地调试问题。 1. 哪些项目应该被编排为服务？ 2. 需要哪些外部资源（数据库、Redis、存储等）？ 3. 应该使用最小的 Aspire 设置还是包含其他组件？ 4. 是否有现有的 Docker 或编排配置？ ### 2\.澄清问题实施前，与用户确认： **服务标识：** * “我已经在您的解决方案中确定了 [X] 项服务：[列表]。所有这些服务都应该包含在 Aspire 编排中吗？” *“是否需要添加任何额外的服务或项目？” **基础设施要求：** *“我看到对[数据库/Redis/等]的引用。Aspire 应该管理这些资源吗？” * “您想使用容器资源还是连接字符串配置？” **渴望结构：** * “我应该创建一个名为“[SolutionName].AppHost”的新 AppHost 项目和一个名为“[SolutionName].ServiceDefaults”的 ServiceDefaults 项目吗？” *“您喜欢特定的命名约定吗？” **依赖关系：** *“哪些服务相互依赖？（这有助于设置服务发现）” * “有启动订购要求吗？” ### 3\.实施步骤 #### 第 1 步：创建 Aspire 项目 **创建AppHost项目：** dotnet new aspire-apphost -n [解决方案名称].AppHost AppHost项目： * 协调所有服务和资源 * 定义服务依赖和配置 * 提供开发者仪表板用于本地开发 * 包含包含应用程序组成的“Program.cs” **创建ServiceDefaults项目：** dotnet new aspire-servicedefaults -n [解决方案名称].ServiceDefaults 服务默认项目： * 提供共享服务配置 * 配置 OpenTelemetry、健康检查和服务发现 * 应用于所有服务以获得一致的行为 **将项目添加到解决方案：** dotnet sln add [解决方案名称].AppHost/[解决方案名称].AppHost.csproj dotnet sln add [解决方案名称].ServiceDefaults/[解决方案名称].ServiceDefaults.csproj #### 步骤 2：配置服务项目 **对于每个服务项目**（API、Web 应用程序、Worker）： 1. **添加ServiceDefaults参考：** dotnet 添加 [ServiceProject] 引用 [SolutionName].ServiceDefaults/[SolutionName].ServiceDefaults.csproj 2. **更新 Program.cs** 以注册服务默认值： // 在 Program.cs 的顶部，创建构建器之后 var builder = WebApplication.CreateBuilder(args); // 添加这一行生成器.AddServiceDefaults(); // ...其余服务配置... var app = builder.Build(); // 在app.Run()之前添加这一行 app.MapDefaultEndpoints(); 应用程序.运行(); 3. **对于 Worker Services** ，模式类似： var builder = Host.CreateApplicationBuilder(args); 生成器.AddServiceDefaults(); // ... 服务配置 ... var host = builder.Build(); 主机.运行(); #### 步骤 3：配置 AppHost **在AppHost中添加项目引用**： dotnet 添加 [SolutionName].AppHost 引用 [ServiceProject1]/[ServiceProject1].csproj dotnet 添加 [SolutionName].AppHost 引用 [ServiceProject2]/[ServiceProject2].csproj **更新AppHost Program.cs**以编排服务： var builder = DistributedApplication.CreateBuilder(args); // 添加基础设施资源 var cache = builder.AddRedis(“缓存”); var postgres = builder.AddPostgres("postgres") .AddDatabase("appdb"); // 添加有依赖的服务 var apiService = builder.AddProject("apiservice") .WithReference(postgres) .WithReference(缓存); var webApp = builder.AddProject("webapp") .WithReference(apiService) .WithExternalHttpEndpoints(); 构建器.Build().Run(); **常用资源方法：** * `.AddRedis("name")` \- Redis 缓存 * `.AddPostgres("name").AddDatabase("dbname")` \- PostgreSQL * `.AddSqlServer("name").AddDatabase("dbname")` \- SQL Server * `.AddRabbitMQ("name")` \- RabbitMQ 消息传递 * `.AddMongoDB("name").AddDatabase("dbname")` \- MongoDB * `.AddAzureStorage("name")` \- Azure 存储 **服务配置方法：** * `.WithReference(resource)` \- 添加依赖项并注入连接信息 * `.WithExternalHttpEndpoints()` \- 使服务可从外部访问 * `.WithReplicas(count)` \- 运行多个实例 * `.WithEnvironment("KEY", "value")` \- 添加环境变量 * `.WithHttpsEndpoint(port: 7001)` \- 指定 HTTPS 端口 #### 步骤 4：添加所需的 NuGet 包 Aspire 包由模板自动添加，但请验证： **AppHost项目：** * `Aspire.Hosting.AppHost`（通常通过工作负载包含） * 额外的资源托管包（例如“Aspire.Hosting.PostgreSQL”） **服务默认项目：** * `Microsoft.Extensions.Http.Resilience` * `Microsoft.Extensions.ServiceDiscovery` * `OpenTelemetry.Exporter.OpenTelemetryProtocol` * `OpenTelemetry.Extensions.Hosting` * `OpenTelemetry.Instrumentation.AspNetCore` * `OpenTelemetry.Instrumentation.Http` * `OpenTelemetry.Instrumentation.Runtime` **服务项目：** * `Aspire.Npgsql.EntityFrameworkCore.PostgreSQL`（如果使用 PostgreSQL） * `Aspire.StackExchange.Redis`（如果使用 Redis） * 数据库、消息传递等所需的组件包。 **安装包：** dotnet 添加 [项目] 包 [包名称] #### 步骤 5：更新服务通信 **对于调用其他服务的服务**，使用服务发现： **之前（硬编码 URL）：** builder.Services.AddHttpClient("apiservice", 客户端 => { client.BaseAddress = new Uri("https://localhost:7001"); }); **之后（服务发现）：** builder.Services.AddHttpClient("apiservice", 客户端 => { client.BaseAddress = new Uri("http://apiservice"); }); 服务名称与 AppHost 的“AddProject<>()”调用中的名称相匹配。 **对于类型化的 HttpClient：** builder.Services.AddHttpClient(客户端 => { client.BaseAddress = new Uri("http://apiservice"); }); #### 步骤 6：配置和连接字符串 **资源连接字符串**会自动注入。更新服务配置： **之前：** builder.Services.AddDbContext(选项 => options.UseNpgsql(builder.Configuration.GetConnectionString("DefaultConnection"))); **之后：** builder.AddNpgsqlDbContext("appdb"); 连接名称（“appdb”）与 AppHost 中的数据库名称匹配。 **对于 Redis：** builder.AddRedisClient(“缓存”); #### 步骤 7：验证和测试 **运行AppHost项目：** dotnet run --project [解决方案名称].AppHost 这将启动： * Aspire 仪表板（通常位于） * 所有配置的服务 * 任何资源容器（Redis、PostgreSQL等） **验证：** 1.仪表板显示所有正在运行的服务 2. 服务可以通过服务发现进行通信 3. 遥测数据出现在仪表板中 4. 资源连接正常 ### 4\.高级配置 #### 外部服务对于不在解决方案中的服务： var externalApi = builder.AddProject("external-api") .WithHttpsEndpoint(端口：8001); #### 容器资源在容器中运行服务： var myApi = builder.AddContainer("myapi", "myapiimage") .WithHttpEndpoint(端口: 8000, targetPort: 80); #### Azure 资源对于 Azure 托管的资源： var storage = builder.AddAzureStorage("存储") .AddBlobs("斑点"); var keyVault = builder.AddAzureKeyVault("keyvault"); #### 自定义资源使用自定义资源扩展 Aspire： var customResource = builder.AddResource(new CustomResource("名称")) .WithEndpoint("http", 端点 => 端点.端口 = 9000); ## 最佳实践 ### 1\.服务机构 * 让AppHost专注于编排，而不是业务逻辑 * 使用 ServiceDefaults 解决跨领域问题 * 确保每个服务都可以独立运行（使用后备配置） ### 2\.资源管理 * 使用 Aspire 管理的资源促进本地发展 * 使用连接字符串进行生产部署 * 为数据库配置资源持久化（避免数据丢失） ### 3\.配置 * 使用“appsettings.Development.json”进行本地覆盖 * 将敏感数据保存在用户机密或密钥库中 * 使用特定于环境的配置 ### 4\.依赖关系 * 在AppHost中定义显式的服务依赖 * 使用`.WithReference()`注入连接信息 * 考虑数据库迁移的启动顺序 ### 5\.可观测性 * 利用内置 OpenTelemetry 进行分布式跟踪 * 使用仪表板进行本地调试 *为每个服务配置适当的日志级别 ## 常见模式 ### API网关模式 var apiGateway = builder.AddProject("网关") .WithExternalHttpEndpoints(); var serviceA = builder.AddProject("servicea"); var serviceB = builder.AddProject("serviceb"); apiGateway.WithReference(serviceA).WithReference(serviceB); ### 使用消息队列的 Worker var messages = builder.AddRabbitMQ("messaging"); var worker = builder.AddProject("worker") .WithReference(消息传递); var api = builder.AddProject("api") .WithReference(消息传递); ### 带有后端 API 的 Web 应用程序 var cache = builder.AddRedis(“缓存”); var database = builder.AddPostgres("postgres").AddDatabase("appdb"); var api = builder.AddProject("api") .WithReference(数据库) .WithReference(缓存); var web = builder.AddProject("web") .WithReference(api) .WithExternalHttpEndpoints(); ## 故障排除 ### 服务发现不起作用 * 确保在服务 Program.cs 中调用 `builder.AddServiceDefaults()` * 验证 HttpClient 中的服务名称与 AppHost AddProject 名称匹配 * 检查 ASP.NET 服务是否调用了“app.MapDefaultEndpoints()” ### 连接字符串未注入 * 确认AppHost和服务配置中的资源名称匹配 * 使用 `builder.AddNpgsqlDbContext<>()` 而不是手动 AddDbContext * 验证ServiceDefaults引用是否存在 ### 仪表板无法访问 * 检查AppHost是否正在运行（不是单个服务） * 验证端口未被阻止（默认：15001） * 在 AppHost 控制台输出中查找仪表板 URL ### 资源未启动 * 确保 Docker Desktop 正在运行（针对容器资源） * 检查端口与现有服务是否冲突 * 检查 AppHost 控制台是否存在启动错误 ## 要修改的文件将 Aspire 添加到现有解决方案时，需要修改： 1. **解决方案文件(.sln)** \- 添加AppHost和ServiceDefaults项目 2. **每个服务的Program.cs** \-添加服务默认注册 3. **每个服务的.csproj** \- 添加ServiceDefaults引用 4. **AppHost/Program.cs** \- 定义编排和资源 5. **服务配置** \- 用服务发现替换硬编码的 URL 6. **数据库配置** \- 使用Aspire组件方法 ## 先决条件确保安装了以下内容： * .NET 8.0 SDK 或更高版本 * .NET Aspire 工作负载：`dotnet 工作负载安装 aspire` * Docker Desktop（用于容器资源）验证安装： dotnet 工作负载列表应在已安装的工作负载中显示“aspire”。 ## 摘要清单实施 Aspire 后，验证： * AppHost项目创建并添加到解决方案中 * ServiceDefaults 项目已创建并添加到解决方案中 * 所有服务项目均引用ServiceDefaults * Service Program.cs 文件调用 `AddServiceDefaults()` 和 `MapDefaultEndpoints()` * AppHost Program.cs 编排具有适当依赖关系的所有服务 * 服务到服务的通信使用服务发现（不是硬编码的 URL） * 数据库和缓存连接使用Aspire组件方法 * AppHost成功运行并启动仪表板 * 所有服务都出现在仪表板中并显示健康状态 * 针对跨服务的请求显示遥测数据 ## 其他资源有关特定组件和模式的详细信息，请参阅： * `resources/components.md` \- Aspire 组件包和配置 * `resources/deployment.md` \- 将 Aspire 应用程序部署到生产环境 ## 输出示例完成后，解决方案结构应如下所示：我的解决方案/ ├── MySolution.sln ├── MySolution.AppHost/ │ ├── Program.cs # 编排配置 │ ├── MySolution.AppHost.csproj │ └── appsettings.json ├── MySolution.ServiceDefaults/ │ ├── Extensions.cs # 服务默认实现 │ └── MySolution.ServiceDefaults.csproj ├── MySolution.Api/ │ ├── Program.cs # 调用AddServiceDefaults() │ └── MySolution.Api.csproj # 参考ServiceDefaults ├── MySolution.Web/ │ ├── Program.cs # 调用AddServiceDefaults() │ └── MySolution.Web.csproj # 参考ServiceDefaults └── MySolution.Worker/ ├── Program.cs # 调用AddServiceDefaults() └── MySolution.Worker.csproj # 参考ServiceDefaults 运行“dotnet run --project MySolution.AppHost”启动所有服务并打开仪表板以监视和调试分布式应用程序。

点网渴望

包含技能