.NET .NET Aspire 服務預設值

發行項
12/12/2024

在本文中，您將瞭解 .NET.NET Aspire 服務預設專案，這是一組擴充方法：

將遙測、健康情況檢查、服務探索連線到您的應用程式。
可自定義且可延伸。

雲端原生應用程式通常需要大量設定，以確保它們能可靠地且安全地跨不同環境運作。 .NET Aspire 提供許多協助程式方法和工具，以簡化 OpenTelemetry、健康情況檢查、環境變數等設定的管理。

探索服務預設值專案

當您在協調流程中登記，或建立新的專案時，YourAppName.ServiceDefaults.csproj 專案會新增至您的方案。例如，建置 API 時，您會在應用程式的 Program.cs 檔案中呼叫 AddServiceDefaults 方法：

builder.AddServiceDefaults();

AddServiceDefaults 方法會處理下列工作：

設定 OpenTelemetry 計量和追蹤。
新增預設健康情況檢查端點。
新增服務探索功能。
設定 HttpClient 來處理服務探索。

如需詳細資訊，請參閱提供的擴充方法，以取得 AddServiceDefaults 方法的詳細數據。

重要

.NET .NET Aspire 服務預設專案專為共用 Extensions.cs 檔案及其功能而設計。請勿在此專案中包含其他共用功能或模型。請針對這些目的使用傳統的共享類別庫專案。

專案特性

YourAppName.ServiceDefaults 專案是包含下列 XML 的 .NET 9.0 連結庫：

<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 相依性。

提示

如果您不想相依於 Microsoft.AspNetCore.App，您可以建立自訂服務預設專案。如需詳細資訊，請參閱自定義服務預設值。

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 監視器匯出工具。

如需詳細資訊，請參閱 .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 健康情況檢查。

自訂服務預設值

如果項目範本所提供的預設服務組態不足以滿足您的需求，您可以選擇建立自己的服務預設值專案。當您的取用專案，例如 Worker 專案或 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 解決方案中的所有項目資源。

共用方式為