构建 .NET Aspire 分布式应用时，用共享…

适用于基于 .NET Aspire 的多服务应用，需要集中配置可观测性、健康检查、服务发现和 HTTP 韧性时。

适用场景

解决思路

1. 创建 src/MyApp.ServiceDefaults/ 共享项目，包含 Extensions.cs 和 MyApp.ServiceDefaults.csproj。
2. 让每个服务项目（如 MyApp.Api、MyApp.Worker）在 Program.cs 中引用该共享项目并调用 AddServiceDefaults()。
3. 在 AppHost 项目 src/MyApp.AppHost/ 中配置分布式应用宿主。
4. 在 MyApp.ServiceDefaults.csproj 中使用 Microsoft.NET.Sdk，设置 TargetFramework 为 net9.0，设置 IsAspireSharedProject 为 true。
5. 在 ServiceDefaults 项目文件中添加 FrameworkReference Include="Microsoft.AspNetCore.App"。
6. 添加 PackageReference：Microsoft.Extensions.Http.Resilience、Microsoft.Extensions.ServiceDiscovery、OpenTelemetry.Exporter.OpenTelemetryProtocol、OpenTelemetry.Extensions.Hosting、OpenTelemetry.Instrumentation.AspNetCore、OpenTelemetry.Instrumentation.Http、OpenTelemetry.Instrumentation.Runtime。
7. 在 Extensions.cs 中定义常量 HealthEndpointPath = "/health" 和 AlivenessEndpointPath = "/alive"。
8. 实现 AddServiceDefaults<TBuilder>(this TBuilder builder) where TBuilder : IHostApplicationBuilder：依次调用 builder.ConfigureOpenTelemetry()、builder.AddDefaultHealthChecks()、builder.Services.AddServiceDiscovery()。
9. 在 AddServiceDefaults 中调用 builder.Services.ConfigureHttpClientDefaults(http => { http.AddStandardResilienceHandler(); http.AddServiceDiscovery(); })，再返回 builder。
10. 在 ConfigureOpenTelemetry 中调用 builder.Logging.AddOpenTelemetry(logging => { logging.IncludeFormattedMessage = true; logging.IncludeScopes = true; })。
11. 在 ConfigureOpenTelemetry 中调用 builder.Services.AddOpenTelemetry().WithMetrics(metrics => { metrics.AddAspNetCoreInstrumentation().AddHttpClientInstrumentation().AddRuntimeInstrumentation(); })。
12. 在 ConfigureOpenTelemetry 中配置 .WithTracing：调用 tracing.AddSource(builder.Environment.ApplicationName).AddHttpClientInstrumentation()。
13. 在 .WithTracing 的 AddAspNetCoreInstrumentation 中设置 options.Filter，过滤掉以 HealthEndpointPath 或 AlivenessEndpointPath 开头的请求路径。
14. 在 ConfigureOpenTelemetry 中调用 builder.AddOpenTelemetryExporters()。
15. 实现 AddOpenTelemetryExporters：检查 builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"] 是否非空白；若配置了该端点，则调用 builder.Services.AddOpenTelemetry().UseOtlpExporter()。
16. 实现 AddDefaultHealthChecks：调用 builder.Services.AddHealthChecks().AddCheck("self", () => HealthCheckResult.Healthy(), ["live"])，再返回 builder。
17. 实现 MapDefaultEndpoints：在 UseRouting() 之后调用；在 app.Environment.IsDevelopment() 时映射 /health 和 /alive 健康检查端点。
18. 在 MapDefaultEndpoints 中映射 /health 时使用 app.MapHealthChecks(HealthEndpointPath)。
19. 在 MapDefaultEndpoints 中映射 /alive 时使用 app.MapHealthChecks(AlivenessEndpointPath, new HealthCheckOptions { Predicate = r => r.Tags.Contains("live") })。
20. 在 API 服务中使用：builder.AddServiceDefaults(); builder.Services.AddControllers(); var app = builder.Build(); app.MapDefaultEndpoints(); app.MapControllers(); app.Run();
21. 在 Worker 服务中使用：var builder = Host.CreateApplicationBuilder(args); builder.AddServiceDefaults(); builder.Services.AddHostedService<MyWorker>(); var host = builder.Build(); host.Run();
22. 自定义健康检查时，在 AddDefaultHealthChecks 的 AddHealthChecks() 链上添加 .AddNpgSql(builder.Configuration.GetConnectionString("postgres")!, name: "postgres", tags: ["ready"])。
23. 自定义健康检查时，在 AddDefaultHealthChecks 的 AddHealthChecks() 链上添加 .AddRedis(builder.Configuration.GetConnectionString("redis")!, name: "redis", tags: ["ready"])。
24. 自定义健康检查时，在 AddDefaultHealthChecks 的 AddHealthChecks() 链上添加 .AddCheck<MyCustomHealthCheck>("custom", tags: ["ready"])。
25. 自定义 Trace Source 时，在 ConfigureOpenTelemetry 的 WithTracing 中追加 .AddSource("Akka.NET")、.AddSource("MyApp.Orders")、.AddSource("MyApp.Payments") 等。
26. 生产环境健康检查：始终映射 /health 和 /alive，但使用 HealthCheckOptions.ResponseWriter 仅返回 report.Status.ToString()，Content-Type 为 text/plain。
27. 生产环境健康检查：/alive 使用 Predicate = r => r.Tags.Contains("live")，只暴露存活检查。
28. 生产环境考虑使用仅内部可访问端口、添加授权、添加限流来保护健康检查端点。
29. 在 AppHost/Program.cs 中使用 DistributedApplication.CreateBuilder(args)，通过 AddPostgres("postgres")、AddRedis("redis") 添加资源。
30. 在 AppHost 中通过 AddProject<Projects.MyApp_Api>("api").WithReference(postgres).WithReference(redis) 引用服务和资源，然后 builder.Build().Run()。
31. 依赖 AppHost 自动注入 OTEL_EXPORTER_OTLP_ENDPOINT，使服务将遥测发送到 Aspire Dashboard。
32. 最佳实践：只创建一个 ServiceDefaults 项目，供所有服务引用，保证配置一致。
33. 最佳实践：在 tracing 的 AspNetCoreInstrumentation 中过滤健康检查路径，减少可观测性数据噪声。
34. 最佳实践：为健康检查打 tags，区分 liveness 与 readiness，例如 ["live"] 和 ["ready"]。
35. 最佳实践：在 ConfigureHttpClientDefaults 中使用 http.AddStandardResilienceHandler()，获得内置重试、熔断和超时。
36. 最佳实践：通过 AddSource 添加自定义 ActivitySource 名称，以捕获领域特定 span。

适用边界 · 注意事项

• 非 .NET Aspire 项目，或无法引用 Microsoft.Extensions.ServiceDiscovery、OpenTelemetry 等 Aspire 相关包时。
• 只需要单个简单服务，且不需要统一可观测性、健康检查、服务发现和 HTTP 韧性配置时。
• 生产环境中无法保护 /health 和 /alive 端点（如内部端口、授权、限流）时，不应直接公开详细健康检查。