aspire-service-defaults

用途

Aspire Service Defaults 是一个用于 Aspire 分布式应用的技能，帮助创建共享的 ServiceDefaults 项目。该项目为应用中的所有服务提供统一配置，覆盖 OpenTelemetry、健康检查、弹性策略和服务发现。

主要能力

ServiceDefaults 共享项目包含以下配置：

OpenTelemetry：日志、追踪和指标的统一采集与导出
健康检查：就绪（readiness）与存活（liveness）端点
服务发现：自动解析服务名称到地址
HTTP 弹性：重试、断路器和超时等策略

每个服务引用该项目，并调用 AddServiceDefaults() 即可获得以上能力。

项目结构示例

src/
  MyApp.ServiceDefaults/
    Extensions.cs
    MyApp.ServiceDefaults.csproj
  MyApp.Api/
    Program.cs  # 调用 AddServiceDefaults()
  MyApp.Worker/
    Program.cs  # 调用 AddServiceDefaults()
  MyApp.AppHost/
    Program.cs

关键实现

ServiceDefaults 项目文件使用 Microsoft.NET.Sdk，设置 IsAspireSharedProject 为 true，并引用 Http 弹性、服务发现及 OpenTelemetry 相关包。

核心扩展类 Extensions 提供三个主要方法：

AddServiceDefaults()：依次配置 OpenTelemetry、默认健康检查、服务发现，并通过 ConfigureHttpClientDefaults 添加标准弹性处理器与服务发现。
ConfigureOpenTelemetry()：启用日志（含格式化消息与作用域）、指标（AspNetCore、HttpClient、Runtime 仪表化）与追踪（应用名、AspNetCore、HttpClient，并过滤健康检查路径）。
AddDefaultHealthChecks() / MapDefaultEndpoints()：注册自检健康检查（标签 live），并在开发环境下映射 /health 与 /alive 端点。

OTLP 导出器在配置了 OTEL_EXPORTER_OTLP_ENDPOINT 时启用。

使用方式

API 服务：

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

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

Worker 服务（同样适用于非 Web 主机）：

var builder = Host.CreateApplicationBuilder(args);
builder.AddServiceDefaults();
builder.Services.AddHostedService<MyWorker>();

var host = builder.Build();
host.Run();

可扩展自定义健康检查（如 Npgsql、Redis、自定义检查）并打上 ready 标签；也可添加自定义追踪源（如 Akka.NET 或自定义 ActivitySource）。

在 AppHost 中，通过 DistributedApplication.CreateBuilder 添加资源并引用项目，服务会自动收到 OTLP 端点，将遥测发送至 Aspire Dashboard。

适用场景

构建基于 Aspire 的分布式应用
需要跨服务一致的观测能力（日志、追踪、指标）
需要共享的健康检查配置
配置 HttpClient 弹性策略与服务发现

最佳实践与限制

保持唯一的 ServiceDefaults 项目，确保配置一致
从追踪中过滤健康检查，减少观测数据噪声
使用标签区分存活与就绪检查
使用 StandardResilienceHandler 获得内置重试、断路器与超时
为领域特定的 span 添加自定义追踪源

生产环境需注意：默认的 MapDefaultEndpoints 仅在开发环境暴露健康端点；若要在生产使用，应考虑仅内网端口、增加授权或限流，并仅返回状态而非详细信息。

技能介绍

用途