.NET .NET Aspire 服务默认值

在本文中，你将了解 .NET.NET Aspire 服务默认项目，这是一组扩展方法：

• 将 遥测、运行状况检查、服务发现 连接到应用。
• 可自定义且可扩展。

云原生应用程序通常需要大量配置，以确保它们能够可靠地安全地跨不同的环境工作。 .NET Aspire 提供了许多帮助程序方法和工具，用于简化 OpenTelemetry、运行状况检查、环境变量等的配置管理。

浏览服务默认项目

在 业务流程 中 登记或 创建新的 项目时，YourAppName.ServiceDefaults.csproj 项目将添加到解决方案中。 例如，生成 API 时，请在应用的 Program.cs 文件中调用 AddServiceDefaults 方法：

builder.AddServiceDefaults();

AddServiceDefaults 方法处理以下任务：

• 配置 OpenTelemetry 指标和跟踪。
• 添加默认运行状况检查终结点。
• 添加服务发现功能。
• 配置 HttpClient 以使用服务发现。

有关详细信息，请参阅 提供的扩展方法，了解有关 AddServiceDefaults 方法的详细信息。

项目特征

YourAppName.ServiceDefaults 项目是一个 .NET 9.0 库，其中包含以下 XML：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireSharedProject>true</IsAspireSharedProject>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />

    <PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="9.0.0" />
    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.0.0" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.10.0" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.10.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.10.1" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.10.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.10.0" />
  </ItemGroup>

</Project>

服务默认项目模板对 Microsoft.AspNetCore.App施加 FrameworkReference 依赖项。

IsAspireSharedProject 属性设置为 true，指示此项目是共享项目。 .NET Aspire 工具将此项目用作添加到 .NET Aspire 解决方案的其他项目的参考。 登记新项目进行业务流程时，它会自动引用 yourAppName.ServiceDefaults 项目 ，并更新 文件以调用 方法。

提供的扩展方法

YourAppName.ServiceDefaults 项目公开了包含多个有意见扩展方法的单个 Extensions.cs 文件：

• AddServiceDefaults：添加服务默认值功能。
• ConfigureOpenTelemetry：配置 OpenTelemetry 指标和跟踪。
• AddDefaultHealthChecks：添加默认运行状况检查终结点。
• MapDefaultEndpoints：将运行状况检查终结点映射到 /health，将实时终结点映射到 /alive。

添加服务默认值功能

AddServiceDefaults 方法定义具有以下有意见功能的默认配置：

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

    builder.AddDefaultHealthChecks();

    builder.Services.AddServiceDiscovery();

    builder.Services.ConfigureHttpClientDefaults(http =>
    {
        // Turn on resilience by default
        http.AddStandardResilienceHandler();

        // Turn on service discovery by default
        http.AddServiceDiscovery();
    });

    // Uncomment the following to restrict the allowed schemes for service discovery.
    // builder.Services.Configure<ServiceDiscoveryOptions>(options =>
    // {
    //     options.AllowedSchemes = ["https"];
    // });

    return builder;
}

前面的代码：

• 通过调用 ConfigureOpenTelemetry 方法配置 OpenTelemetry 指标和跟踪。
• 通过调用 AddDefaultHealthChecks 方法添加默认运行状况检查终结点。
• 通过调用 AddServiceDiscovery 方法，添加 服务发现 功能。
• 通过调用 ConfigureHttpClientDefaults 方法配置 HttpClient 默认值，该方法基于 生成可复原 HTTP 应用：关键开发模式：
  • 通过调用 AddStandardResilienceHandler 方法添加标准 HTTP 复原处理程序。
  • 通过调用 UseServiceDiscovery 方法，指定 IHttpClientBuilder 应使用服务发现。
• 返回允许方法链接的 IHostApplicationBuilder 实例。

OpenTelemetry 配置

遥测是任何云原生应用程序的关键部分。 .NET Aspire 为 OpenTelemetry提供了一组有意见的默认值，这些默认值使用 ConfigureOpenTelemetry 方法进行配置：

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 =>
        {
            if (builder.Environment.IsDevelopment())
            {
                // We want to view all traces in development
                tracing.SetSampler(new AlwaysOnSampler());
            }

            tracing.AddAspNetCoreInstrumentation()
                // Uncomment the following line to enable gRPC instrumentation 
                // (requires the OpenTelemetry.Instrumentation.GrpcNetClient package)
                //.AddGrpcClientInstrumentation()
                .AddHttpClientInstrumentation();
        });

    builder.AddOpenTelemetryExporters();

    return builder;
}

ConfigureOpenTelemetry 方法：

• 添加 .NET.NET Aspire 遥测 日志记录，以包括格式化的消息和范围。
• 添加 OpenTelemetry 指标和跟踪，其中包括：
  • 运行时检测指标。
  • ASP.NET Core 检测指标。
  • HttpClient 检测指标。
  • 在开发环境中，AlwaysOnSampler 用于查看所有跟踪。
  • ASP.NET Core、gRPC 和 HTTP 检测的跟踪详细信息。
• 通过调用 AddOpenTelemetryExporters来添加 OpenTelemetry 导出程序。

AddOpenTelemetryExporters 方法按如下方式私下定义：

private static IHostApplicationBuilder AddOpenTelemetryExporters(
    this IHostApplicationBuilder builder)
{
    var useOtlpExporter = !string.IsNullOrWhiteSpace(
        builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"]);

    if (useOtlpExporter)
    {
        builder.Services.Configure<OpenTelemetryLoggerOptions>(
            logging => logging.AddOtlpExporter());
        builder.Services.ConfigureOpenTelemetryMeterProvider(
            metrics => metrics.AddOtlpExporter());
        builder.Services.ConfigureOpenTelemetryTracerProvider(
            tracing => tracing.AddOtlpExporter());
    }

    // Uncomment the following lines to enable the Prometheus exporter
    // (requires the OpenTelemetry.Exporter.Prometheus.AspNetCore package)
    // builder.Services.AddOpenTelemetry()
    //    .WithMetrics(metrics => metrics.AddPrometheusExporter());

    // Uncomment the following lines to enable the Azure Monitor exporter 
    // (requires the Azure.Monitor.OpenTelemetry.AspNetCore package)
    //if (!string.IsNullOrEmpty(
    //    builder.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"]))
    //{
    //    builder.Services.AddOpenTelemetry()
    //       .UseAzureMonitor();
    //}

    return builder;
}

AddOpenTelemetryExporters 方法根据以下条件添加 OpenTelemetry 导出程序：

• 如果设置了 OTEL_EXPORTER_OTLP_ENDPOINT 环境变量，则会添加 OpenTelemetry 导出程序。
• （可选）.NET Aspire 服务默认值的使用者可以取消注释某些代码以启用 Prometheus 导出程序或 Azure Monitor 导出程序。

有关详细信息，请参阅 .NET.NET Aspire 遥测。

运行状况检查配置

各种工具和系统都使用运行状况检查来评估应用的就绪情况。 .NET .NET Aspire 为运行状况检查提供了一组有意见的默认值，这些默认设置使用 AddDefaultHealthChecks 方法进行配置：

public static IHostApplicationBuilder AddDefaultHealthChecks(
    this IHostApplicationBuilder builder)
{
    builder.Services.AddHealthChecks()
        // Add a default liveness check to ensure app is responsive
        .AddCheck("self", () => HealthCheckResult.Healthy(), ["live"]);

    return builder;
}

AddDefaultHealthChecks 方法添加了默认的实时性检查，以确保应用响应迅速。 调用 AddHealthChecks 注册 HealthCheckService。 有关详细信息，请参阅 .NET.NET Aspire 运行状况检查。

Web 应用运行状况检查配置

若要在 Web 应用中公开运行状况检查，.NET.NET Aspire 会自动确定解决方案中引用的项目类型，并将相应的调用添加到 MapDefaultEndpoints：

public static WebApplication MapDefaultEndpoints(this WebApplication app)
{
    // Uncomment the following line to enable the Prometheus endpoint 
    // (requires the OpenTelemetry.Exporter.Prometheus.AspNetCore package)
    // app.MapPrometheusScrapingEndpoint();

    // Adding health checks endpoints to applications in non-development 
    // environments has security implications.
    // See https://aka.ms/dotnet/aspire/healthchecks for details before 
    // enabling these endpoints in non-development environments.
    if (app.Environment.IsDevelopment())
    {
        // All health checks must pass for app to be considered ready to 
        // accept traffic after starting
        app.MapHealthChecks("/health");

        // Only health checks tagged with the "live" tag must pass for 
        // app to be considered alive
        app.MapHealthChecks("/alive", new HealthCheckOptions
        {
            Predicate = r => r.Tags.Contains("live")
        });
    }

    return app;
}

MapDefaultEndpoints 方法：

• 允许使用者选择取消注释某些代码以启用 Prometheus 终结点。
• 将运行状况检查终结点映射到 /health。
• 将实时终结点映射到运行状况检查标记包含 live的 /alive 路由。

有关详细信息，请参阅 .NET.NET Aspire 运行状况检查。

自定义服务默认值

如果项目模板提供的默认服务配置不足以满足你的需求，则可以选择创建自己的服务默认项目。 当使用的项目（如辅助角色项目或 WinForms 项目）不能或不希望 FrameworkReference 依赖 Microsoft.AspNetCore.App时，这特别有用。

为此，请创建一个新的 .NET 9.0 类库项目，并将必要的依赖项添加到项目文件，请考虑以下示例：

<Project Sdk="Microsoft.NET.Sdk">

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

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Hosting" />
    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" />
    <PackageReference Include="Microsoft.Extensions.Http.Resilience" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" />
  </ItemGroup>
</Project>

然后创建一个扩展类，其中包含配置应用默认值所需的方法：

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;

namespace Microsoft.Extensions.Hosting;

public static class AppDefaultsExtensions
{
    public static IHostApplicationBuilder AddAppDefaults(
        this IHostApplicationBuilder builder)
    {
        builder.ConfigureAppOpenTelemetry();

        builder.Services.AddServiceDiscovery();

        builder.Services.ConfigureHttpClientDefaults(http =>
        {
            // Turn on resilience by default
            http.AddStandardResilienceHandler();

            // Turn on service discovery by default
            http.AddServiceDiscovery();
        });

        return builder;
    }

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

        builder.Services.AddOpenTelemetry()
            .WithMetrics(static metrics =>
            {
                metrics.AddRuntimeInstrumentation();
            })
            .WithTracing(tracing =>
            {
                if (builder.Environment.IsDevelopment())
                {
                    // We want to view all traces in development
                    tracing.SetSampler(new AlwaysOnSampler());
                }

                tracing.AddGrpcClientInstrumentation()
                       .AddHttpClientInstrumentation();
            });

        builder.AddOpenTelemetryExporters();

        return builder;
    }

    private static IHostApplicationBuilder AddOpenTelemetryExporters(
        this IHostApplicationBuilder builder)
    {
        var useOtlpExporter =
            !string.IsNullOrWhiteSpace(
                builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"]);

        if (useOtlpExporter)
        {
            builder.Services.Configure<OpenTelemetryLoggerOptions>(
                logging => logging.AddOtlpExporter());
            builder.Services.ConfigureOpenTelemetryMeterProvider(
                metrics => metrics.AddOtlpExporter());
            builder.Services.ConfigureOpenTelemetryTracerProvider(
                tracing => tracing.AddOtlpExporter());
        }

        return builder;
    }
}

这只是一个示例，你可以自定义 AppDefaultsExtensions 类以满足你的特定需求。

后续步骤

此代码派生自 .NET.NET Aspire 初学者应用程序模板，用作起点。 你可以随意修改此代码，但你认为有必要满足你的需求。 请务必知道，服务默认项目及其功能会自动应用于 .NET.NET Aspire 解决方案中的所有项目资源。

• 在 中 服务发现
• .NET .NET Aspire SDK
• .NET .NET Aspire 模板
• 在 中 运行状况检查
• .NET .NET Aspire 遥测
• 构建可复原 HTTP 应用：关键开发模式