.NET .NET Aspire サービスの既定値

[アーティクル]
12/15/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 プロジェクトが自動的に参照され、AddServiceDefaults メソッドを呼び出す Program.cs ファイルが更新されます。

指定された拡張メソッド

YourAppName.ServiceDefaults プロジェクトでは、いくつかの意見が示された拡張メソッドを含む 1 つの 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 では、ConfigureOpenTelemetry メソッドを使用して構成される、OpenTelemetryの一連の既定の設定が提供されます。

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 では、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が登録されます。詳細については、正常性チェックを参照してください。

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 に、ライブネスエンドポイントをマップします。

詳細については、正常性チェックを参照してください。

カスタムサービスの既定値

プロジェクトテンプレートによって提供される既定のサービス構成がニーズに十分でない場合は、独自のサービスの既定のプロジェクトを作成するオプションがあります。これは、ワーカープロジェクトや WinForms プロジェクトなど、使用しているプロジェクトが Microsoft.AspNetCore.Appに FrameworkReference 依存関係を持つことができない場合や望まない場合に特に便利です。

これを行うには、新しい .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 テンプレート
での正常性チェックの
テレメトリをする
回復性のある HTTP アプリの構築: 主要な開発パターン

次の方法で共有

.NET .NET Aspire サービスの既定値

サービスの既定のプロジェクトを調べる

プロジェクトの特性

指定された拡張メソッド

サービスの既定の機能を追加する

OpenTelemetry 構成

正常性チェックの構成

Web アプリの正常性チェックの構成

カスタムサービスの既定値

次の手順

その他のリソース

次の方法で共有

.NET .NET Aspire サービスの既定値

サービスの既定のプロジェクトを調べる

プロジェクトの特性

指定された拡張メソッド

サービスの既定の機能を追加する

OpenTelemetry 構成

正常性チェックの構成

Web アプリの正常性チェックの構成

カスタム サービスの既定値

次の手順

その他のリソース

カスタムサービスの既定値