Aspire SDK 与 ServiceDefaults

更新: 2026-10-16 15:20:09   字数: 0 字   时长: 0 分钟

Aspire 的 .NET 支持由三部分组成：AppHost SDK、ServiceDefaults 项目、客户端集成包。理清这三者的职责，可以避免很多「包该装在哪里」的困惑。

三者职责

组成	作用	装在哪个项目
Aspire.AppHost.Sdk	提供 AppHost 的构建与运行支持。	AppHost 项目
ServiceDefaults	共享的运行时配置（遥测、弹性、服务发现）。	各业务服务项目
Aspire.* 客户端集成	让业务代码以强类型方式访问资源。	各业务服务项目

AppHost SDK

AppHost 项目通过 Sdk 属性引入：

<Project Sdk="Microsoft.NET.Sdk">
  <Sdk Name="Aspire.AppHost.Sdk" Version="9.0.0" />

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.0.0" />
  </ItemGroup>
</Project>

文件型 AppHost 则使用单文件指令：

#:sdk Aspire.AppHost.Sdk
#:package Aspire.Hosting.PostgreSQL

ServiceDefaults

ServiceDefaults 是一个被各服务引用的共享项目，典型内容如下：

public static class Extensions
{
    public static IHostApplicationBuilder AddServiceDefaults(this IHostApplicationBuilder builder)
    {
        builder.ConfigureOpenTelemetry();
        builder.AddDefaultHealthChecks();

        builder.Services.AddServiceDiscovery();

        builder.Services.ConfigureHttpClientDefaults(http =>
        {
            // 默认开启弹性策略
            http.AddStandardResilienceHandler();
            // 默认开启服务发现
            http.AddServiceDiscovery();
        });

        return builder;
    }

    public static IHostApplicationBuilder ConfigureOpenTelemetry(this IHostApplicationBuilder builder)
    {
        builder.Logging.AddOpenTelemetry(logging =>
        {
            logging.IncludeFormattedMessage = true;
            logging.IncludeScopes = true;
        });

        builder.Services.AddOpenTelemetry()
            .WithMetrics(metrics => metrics
                .AddAspNetCoreInstrumentation()
                .AddHttpClientInstrumentation()
                .AddRuntimeInstrumentation())
            .WithTracing(tracing => tracing
                .AddAspNetCoreInstrumentation()
                .AddHttpClientInstrumentation());

        builder.AddOpenTelemetryExporters();
        return builder;
    }

    public static IHostApplicationBuilder AddDefaultHealthChecks(this IHostApplicationBuilder builder)
    {
        builder.Services.AddHealthChecks()
            .AddCheck("self", () => HealthCheckResult.Healthy(), ["live"]);
        return builder;
    }
}

它统一解决四件事：遥测、健康检查、服务发现、HTTP 弹性。这就是为什么普通 ASP.NET Core 项目只要加一行 builder.AddServiceDefaults() 就能获得 Aspire 的能力。

客户端集成

业务代码要访问被引用的资源时，用对应的客户端集成包获得强类型 API：

builder.AddServiceDefaults();
builder.AddSqlServerDbContext<CatalogContext>("catalogdb");
builder.AddRedisClient("cache");

常见对应关系：

资源类型	客户端集成包	注册方法示例
SQL Server	Aspire.Microsoft.EntityFrameworkCore.SqlServer	AddSqlServerDbContext<T>(name)
PostgreSQL	Aspire.Npgsql.EntityFrameworkCore.PostgreSQL	AddNpgsqlDbContext<T>(name)
Redis	Aspire.StackExchange.Redis	AddRedisClient(name)
RabbitMQ	Aspire.RabbitMQ.Client	AddRabbitMQClient(name)
Azure Blob	Aspire.Azure.Storage.Blobs	AddAzureBlobClient(name)

客户端集成不写连接字符串

这些方法只接收资源名，连接信息来自 AppHost 注入的配置。这正是「同一份代码在本地与生产都能跑」的原因。

版本对齐

Aspire 相关包应当版本一致。使用 aspire update 可以自动完成对齐：

aspire update

它会：

• 检测过时的 Aspire 集成、模板与 SDK 版本。
• 按当前配置的发布渠道更新 SDK 版本与集成版本。
• 处理在代码中、aspire.config.json 中或集中式版本文件中声明的版本。

不要手工混搭版本

AppHost 包与客户端集成包的版本不一致，容易出现「运行时找不到方法」这类难以定位的问题。升级时请整体升级。

目录结构要点

MyApp.sln
├── MyApp.AppHost/          # 引入 Aspire.AppHost.Sdk + Aspire.Hosting.* 集成
├── MyApp.ServiceDefaults/  # 被各服务引用，本身不是可执行项目
├── MyApp.ApiService/       # 引用 ServiceDefaults + Aspire.* 客户端集成
└── MyApp.Web/              # 同上

ServiceDefaults 可以自定义

ServiceDefaults 不是「魔法项目」，您可以按需修改它：调整采样率、增加指标来源、追加自定义健康检查等。改动会作用于所有引用它的服务。

下一步

• 遥测与 OpenTelemetry
• 服务发现
• 集成简介