aspire-service-defaults

Aspire Service Defaults

Quando Usar Esta Habilidade

Use esta habilidade quando:

• Estiver construindo aplicações distribuídas baseadas em Aspire
• Precisar de observabilidade consistente (logging, tracing, métricas) entre serviços
• Quiser configuração de health checks compartilhada
• Estiver configurando resiliência de HttpClient e descoberta de serviços

---

O que é ServiceDefaults?

ServiceDefaults é um projeto compartilhado que fornece configuração comum para todos os serviços em uma aplicação Aspire:

• OpenTelemetry - Logging, tracing e métricas
• Health Checks - Endpoints de prontidão e atividade
• Descoberta de Serviços - Resolução automática de serviços
• Resiliência HTTP - Políticas de retry e circuit breaker

Cada serviço referencia este projeto e chama AddServiceDefaults().

---

Estrutura do Projeto

src/
  MyApp.ServiceDefaults/
    Extensions.cs
    MyApp.ServiceDefaults.csproj
  MyApp.Api/
    Program.cs  # Chama AddServiceDefaults()
  MyApp.Worker/
    Program.cs  # Chama AddServiceDefaults()
  MyApp.AppHost/
    Program.cs

---

Projeto ServiceDefaults

Arquivo do Projeto

<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>
    /// Adiciona serviços Aspire comuns: OpenTelemetry, health checks,
    /// descoberta de serviços e resiliência HTTP.
    /// </summary>
    public static TBuilder AddServiceDefaults<TBuilder>(this TBuilder builder)
        where TBuilder : IHostApplicationBuilder
    {
        builder.ConfigureOpenTelemetry();
        builder.AddDefaultHealthChecks();

        builder.Services.AddServiceDiscovery();

        builder.Services.ConfigureHttpClientDefaults(http =>
        {
            // Resiliência: retries, circuit breaker, timeouts
            http.AddStandardResilienceHandler();

            // Descoberta de serviços: resolve nomes de serviços para endereços
            http.AddServiceDiscovery();
        });

        return builder;
    }

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

        builder.Services.AddOpenTelemetry()
            // Métricas
            .WithMetrics(metrics =>
            {
                metrics
                    .AddAspNetCoreInstrumentation()
                    .AddHttpClientInstrumentation()
                    .AddRuntimeInstrumentation();
            })
            // Tracing
            .WithTracing(tracing =>
            {
                tracing
                    .AddSource(builder.Environment.ApplicationName)
                    .AddAspNetCoreInstrumentation(options =>
                        // Exclui health checks dos traces
                        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
    {
        // Usa o exportador OTLP se o endpoint estiver configurado (Aspire Dashboard, Jaeger, etc.)
        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>
    /// Mapeia endpoints de health check. Chamar após UseRouting().
    /// </summary>
    public static WebApplication MapDefaultEndpoints(this WebApplication app)
    {
        // Expõe apenas em desenvolvimento - veja nota de segurança abaixo
        if (app.Environment.IsDevelopment())
        {
            // Prontidão: todos os health checks devem passar
            app.MapHealthChecks(HealthEndpointPath);

            // Atividade: apenas checks marcados com "live"
            app.MapHealthChecks(AlivenessEndpointPath, new HealthCheckOptions
            {
                Predicate = r => r.Tags.Contains("live")
            });
        }

        return app;
    }
}

---

Uso nos Serviços

Serviço de API

var builder = WebApplication.CreateBuilder(args);

// Adiciona todos os defaults do serviço
builder.AddServiceDefaults();

// Adiciona seus serviços
builder.Services.AddControllers();

var app = builder.Build();

// Mapeia endpoints de health
app.MapDefaultEndpoints();

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

Serviço Worker

var builder = Host.CreateApplicationBuilder(args);

// Funciona também para hosts não-web
builder.AddServiceDefaults();

builder.Services.AddHostedService<MyWorker>();

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

---

Adicionando Health Checks Personalizados

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

        // Prontidão do banco de dados
        .AddNpgSql(
            builder.Configuration.GetConnectionString("postgres")!,
            name: "postgres",
            tags: ["ready"])

        // Prontidão do Redis
        .AddRedis(
            builder.Configuration.GetConnectionString("redis")!,
            name: "redis",
            tags: ["ready"])

        // Check personalizado
        .AddCheck<MyCustomHealthCheck>("custom", tags: ["ready"]);

    return builder;
}

---

Adicionando Fontes de Trace Personalizadas

Para Akka.NET ou ActivitySources personalizados:

public static TBuilder ConfigureOpenTelemetry<TBuilder>(this TBuilder builder)
    where TBuilder : IHostApplicationBuilder
{
    builder.Services.AddOpenTelemetry()
        .WithTracing(tracing =>
        {
            tracing
                .AddSource(builder.Environment.ApplicationName)
                // Tracing do Akka.NET
                .AddSource("Akka.NET")
                // Fontes personalizadas
                .AddSource("MyApp.Orders")
                .AddSource("MyApp.Payments")
                .AddAspNetCoreInstrumentation()
                .AddHttpClientInstrumentation();
        });

    return builder;
}

---

Health Checks em Produção

Para produção, proteja os endpoints de health ou use caminhos diferentes:

public static WebApplication MapDefaultEndpoints(this WebApplication app)
{
    // Sempre mapear para probes do Kubernetes, mas considere:
    // - Usar portas apenas internas
    // - Adicionar autorização
    // - Limitação de taxa

    app.MapHealthChecks("/health", new HealthCheckOptions
    {
        // Retorna apenas status, não detalhes
        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;
}

---

Integração com AppHost

O AppHost configura automaticamente os endpoints 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();

Os serviços recebem OTEL_EXPORTER_OTLP_ENDPOINT automaticamente, enviando telemetria para o Aspire Dashboard.

---

Melhores Práticas

Prática	Motivo
Um único projeto ServiceDefaults	Configuração consistente em todos os serviços
Filtrar health checks dos traces	Reduz ruído nos dados de observabilidade
Taggear health checks	Separar atividade de prontidão
Usar StandardResilienceHandler	Retry, circuit breaker e timeout embutidos
Adicionar fontes de trace personalizadas	Capturar spans específicos do domínio

---

Recursos

• Aspire Service Defaults: https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/service-defaults
• OpenTelemetry .NET: https://opentelemetry.io/docs/languages/net/
• Health Checks: https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/health-checks