aspire-service-defaults

Aspire Service Defaults

このスキルを使用するタイミング

以下の場合にこのスキルを使用します：

• Aspireベースの分散アプリケーションを構築する場合
• サービス全体で一貫した可観測性（ログ、トレース、メトリクス）が必要な場合
• 共有のヘルスチェック構成が必要な場合
• HttpClientのレジリエンスとサービスディスカバリを構成する場合

---

ServiceDefaultsとは

ServiceDefaultsは、Aspireアプリケーション内のすべてのサービスに共通の設定を提供する共有プロジェクトです：

• OpenTelemetry - ログ、トレース、メトリクス
• ヘルスチェック - 死活監視（liveness）と準備態勢確認（readiness）エンドポイント
• サービスディスカバリ - 自動サービス解決
• 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プロジェクト

プロジェクトファイル

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <IsAspireSharedProject>true</IsAspireSharedProject>
  </PropertyGroup>

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

Extensions.cs

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Diagnostics.HealthChecks;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Diagnostics.HealthChecks;
using Microsoft.Extensions.Logging;
using OpenTelemetry;
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;

namespace Microsoft.Extensions.Hosting;

public static class Extensions
{
    private const string HealthEndpointPath = "/health";
    private const string AlivenessEndpointPath = "/alive";

    /// <summary>
    /// 共通のAspireサービス（OpenTelemetry、ヘルスチェック、
    /// サービスディスカバリ、HTTPレジリエンス）を追加します。
    /// </summary>
    public static TBuilder AddServiceDefaults<TBuilder>(this TBuilder builder)
        where TBuilder : IHostApplicationBuilder
    {
        builder.ConfigureOpenTelemetry();
        builder.AddDefaultHealthChecks();

        builder.Services.AddServiceDiscovery();

        builder.Services.ConfigureHttpClientDefaults(http =>
        {
            // レジリエンス：リトライ、サーキットブレーカー、タイムアウト
            http.AddStandardResilienceHandler();

            // サービスディスカバリ：サービス名をアドレスに解決
            http.AddServiceDiscovery();
        });

        return builder;
    }

    public static TBuilder ConfigureOpenTelemetry<TBuilder>(this TBuilder builder)
        where TBuilder : IHostApplicationBuilder
    {
        // ログ
        builder.Logging.AddOpenTelemetry(logging =>
        {
            logging.IncludeFormattedMessage = true;
            logging.IncludeScopes = true;
        });

        builder.Services.AddOpenTelemetry()
            // メトリクス
            .WithMetrics(metrics =>
            {
                metrics
                    .AddAspNetCoreInstrumentation()
                    .AddHttpClientInstrumentation()
                    .AddRuntimeInstrumentation();
            })
            // トレース
            .WithTracing(tracing =>
            {
                tracing
                    .AddSource(builder.Environment.ApplicationName)
                    .AddAspNetCoreInstrumentation(options =>
                        // ヘルスチェックをトレースから除外
                        options.Filter = context =>
                            !context.Request.Path.StartsWithSegments(HealthEndpointPath) &&
                            !context.Request.Path.StartsWithSegments(AlivenessEndpointPath))
                    .AddHttpClientInstrumentation();
            });

        builder.AddOpenTelemetryExporters();

        return builder;
    }

    private static TBuilder AddOpenTelemetryExporters<TBuilder>(this TBuilder builder)
        where TBuilder : IHostApplicationBuilder
    {
        // OTLPエンドポイントが設定されている場合、OTLPエクスポーターを使用（Aspire Dashboard、Jaegerなど）
        var useOtlp = !string.IsNullOrWhiteSpace(
            builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"]);

        if (useOtlp)
        {
            builder.Services.AddOpenTelemetry().UseOtlpExporter();
        }

        return builder;
    }

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

        return builder;
    }

    /// <summary>
    /// ヘルスチェックエンドポイントをマッピングします。UseRouting()の後に呼び出します。
    /// </summary>
    public static WebApplication MapDefaultEndpoints(this WebApplication app)
    {
        // 開発環境でのみ公開（セキュリティ注意事項を参照）
        if (app.Environment.IsDevelopment())
        {
            // 準備態勢確認：すべてのヘルスチェックが合格する必要がある
            app.MapHealthChecks(HealthEndpointPath);

            // 死活監視："live"タグが付いたチェックのみ
            app.MapHealthChecks(AlivenessEndpointPath, new HealthCheckOptions
            {
                Predicate = r => r.Tags.Contains("live")
            });
        }

        return app;
    }
}

---

サービスでの使用方法

APIサービス

var builder = WebApplication.CreateBuilder(args);

// すべてのサービスのデフォルト設定を追加
builder.AddServiceDefaults();

// 独自のサービスを追加
builder.Services.AddControllers();

var app = builder.Build();

// ヘルスエンドポイントをマッピング
app.MapDefaultEndpoints();

app.MapControllers();
app.Run();

Workerサービス

var builder = Host.CreateApplicationBuilder(args);

// 非Webホストでも動作
builder.AddServiceDefaults();

builder.Services.AddHostedService<MyWorker>();

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

---

カスタムヘルスチェックの追加

public static TBuilder AddDefaultHealthChecks<TBuilder>(this TBuilder builder)
    where TBuilder : IHostApplicationBuilder
{
    builder.Services.AddHealthChecks()
        // 基本の死活監視
        .AddCheck("self", () => HealthCheckResult.Healthy(), ["live"])

        // データベースの準備態勢確認
        .AddNpgSql(
            builder.Configuration.GetConnectionString("postgres")!,
            name: "postgres",
            tags: ["ready"])

        // Redisの準備態勢確認
        .AddRedis(
            builder.Configuration.GetConnectionString("redis")!,
            name: "redis",
            tags: ["ready"])

        // カスタムチェック
        .AddCheck<MyCustomHealthCheck>("custom", tags: ["ready"]);

    return builder;
}

---

カスタムトレースソースの追加

Akka.NETまたはカスタムのActivitySourcesの場合：

public static TBuilder ConfigureOpenTelemetry<TBuilder>(this TBuilder builder)
    where TBuilder : IHostApplicationBuilder
{
    builder.Services.AddOpenTelemetry()
        .WithTracing(tracing =>
        {
            tracing
                .AddSource(builder.Environment.ApplicationName)
                // Akka.NETトレース
                .AddSource("Akka.NET")
                // カスタムソース
                .AddSource("MyApp.Orders")
                .AddSource("MyApp.Payments")
                .AddAspNetCoreInstrumentation()
                .AddHttpClientInstrumentation();
        });

    return builder;
}

---

本番環境のヘルスチェック

本番環境では、ヘルスチェックエンドポイントを保護するか、異なるパスを使用します：

public static WebApplication MapDefaultEndpoints(this WebApplication app)
{
    // Kubernetesプローブのために常にマッピングするが、以下を検討：
    // - 内部専用ポートの使用
    // - 認可の追加
    // - レート制限

    app.MapHealthChecks("/health", new HealthCheckOptions
    {
        // ステータスのみ返し、詳細は返さない
        ResponseWriter = (context, report) =>
        {
            context.Response.ContentType = "text/plain";
            return context.Response.WriteAsync(report.Status.ToString());
        }
    });

    app.MapHealthChecks("/alive", new HealthCheckOptions
    {
        Predicate = r => r.Tags.Contains("live"),
        ResponseWriter = (context, report) =>
        {
            context.Response.ContentType = "text/plain";
            return context.Response.WriteAsync(report.Status.ToString());
        }
    });

    return app;
}

---

AppHostとの統合

AppHostは自動的にOTLPエンドポイントを構成します：

// AppHost/Program.cs
var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres");
var redis = builder.AddRedis("redis");

var api = builder.AddProject<Projects.MyApp_Api>("api")
    .WithReference(postgres)
    .WithReference(redis);

builder.Build().Run();

サービスは自動的にOTEL_EXPORTER_OTLP_ENDPOINTを受け取り、テレメトリをAspire Dashboardに送信します。

---

ベストプラクティス

プラクティス	理由
ServiceDefaultsプロジェクトは1つ	全サービスで一貫した設定
ヘルスチェックをトレースからフィルタリング	可観測性データのノイズを削減
ヘルスチェックにタグを付ける	死活監視と準備態勢確認を分離
StandardResilienceHandlerを使用	組み込みのリトライ、サーキットブレーカー、タイムアウト
カスタムトレースソースを追加	ドメイン固有のスパンをキャプチャ

---

リソース

• Aspire Service Defaults: https://learn.microsoft.com/ja-jp/dotnet/aspire/fundamentals/service-defaults
• OpenTelemetry .NET: https://opentelemetry.io/docs/languages/net/
• ヘルスチェック: https://learn.microsoft.com/ja-jp/aspnet/core/host-and-deploy/health-checks