Condividi tramite

impostazioni predefinite del servizio .NET.NET Aspire

In questo articolo vengono fornite informazioni sul progetto predefinito del servizio .NET.NET Aspire, un set di metodi di estensione che:

Le applicazioni native del cloud spesso richiedono configurazioni estese per assicurarsi che funzionino in ambienti diversi in modo affidabile e sicuro. .NET Aspire fornisce numerosi metodi e strumenti helper per semplificare la gestione delle configurazioni per OpenTelemetry, controlli di integrità, variabili di ambiente e altro ancora.

Esplorare il progetto predefinito del servizio

Quando si Enlist in .NET.NET Aspire orchestrazione o creare un nuovo progetto .NET.NET Aspire, il progetto YourAppName.ServiceDefaults.csproj viene aggiunto alla soluzione. Ad esempio, quando si compila un'API, chiamare il metodo AddServiceDefaults nel file Program.cs delle app:

builder.AddServiceDefaults();

Il metodo AddServiceDefaults gestisce le attività seguenti:

  • Configura OpenTelemetry metriche e traccia.
  • Aggiunge gli endpoint di controllo integrità predefiniti.
  • Aggiunge la funzionalità di individuazione dei servizi.
  • Configura HttpClient per l'uso dell'individuazione dei servizi.

Per altre informazioni, vedere Metodi di estensione forniti per informazioni dettagliate sul metodo AddServiceDefaults.

Importante

Il progetto predefinito del servizio .NET.NET Aspire è progettato specificamente per la condivisione del file Extensions.cs e delle relative funzionalità. Non includere altre funzionalità condivise o modelli in questo progetto. Usare un progetto di libreria di classi condiviso convenzionale per tali scopi.

Caratteristiche del progetto

Il progetto YourAppName.ServiceDefaults è una libreria 9.0 che contiene il codice XML seguente:

<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.6.0" />
    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.3.1" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.12.0" />
  </ItemGroup>

</Project>

Il modello di progetto predefinito del servizio impone una dipendenza FrameworkReference da Microsoft.AspNetCore.App.

Mancia

Se non si vuole accettare una dipendenza da Microsoft.AspNetCore.App, è possibile creare un progetto di impostazioni predefinite del servizio personalizzato. Per altre informazioni, vedere impostazioni predefinite del servizio personalizzato.

La proprietà IsAspireSharedProject è impostata su true, che indica che il progetto è un progetto condiviso. Gli strumenti .NET Aspire usano questo progetto come riferimento per altri progetti aggiunti a una soluzione .NET Aspire. Quando si integra il nuovo progetto per l'orchestrazione, fa automaticamente riferimento al progetto YourAppName.ServiceDefaults e aggiorna il file Program.cs per chiamare il metodo AddServiceDefaults.

Metodi di estensione forniti

Il progetto YourAppName.ServiceDefaults espone un singolo file Extensions.cs che contiene diversi metodi di estensione con opinioni:

  • AddServiceDefaults: aggiunge la funzionalità predefinita del servizio.
  • ConfigureOpenTelemetry: configura le metriche e la traccia OpenTelemetry.
  • AddDefaultHealthChecks: aggiunge endpoint di controllo integrità predefiniti.
  • MapDefaultEndpoints: esegue il mapping dell'endpoint dei controlli di integrità a /health e all'endpoint di attività a /alive.

Aggiungere funzionalità predefinite del servizio

Il metodo AddServiceDefaults definisce le configurazioni predefinite con le funzionalità di opinione seguenti:

public static TBuilder AddServiceDefaults<TBuilder>(this TBuilder builder) where TBuilder : IHostApplicationBuilder
{
    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;
}

Il codice precedente:

  • Configura OpenTelemetry metriche e traccia chiamando il metodo ConfigureOpenTelemetry.
  • Aggiunge gli endpoint di controllo integrità predefiniti chiamando il metodo AddDefaultHealthChecks.
  • Aggiunge funzionalità di individuazione del servizio chiamando il metodo AddServiceDiscovery.
  • Configura le impostazioni predefinite HttpClient chiamando il metodo ConfigureHttpClientDefaults, basato su Creare app HTTP resilienti: modelli di sviluppo chiave:
    • Aggiunge il gestore di resilienza HTTP standard chiamando il metodo AddStandardResilienceHandler.
    • Specifica che il IHttpClientBuilder deve usare l'individuazione del servizio chiamando il metodo UseServiceDiscovery.
  • Restituisce l'istanza di IHostApplicationBuilder per consentire il concatenamento dei metodi.

configurazione OpenTelemetry

La telemetria è una parte fondamentale di qualsiasi applicazione nativa del cloud. .NET Aspire fornisce un set di valori predefiniti di opinione per OpenTelemetry, configurati con il metodo ConfigureOpenTelemetry:

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(tracing =>
                    // Exclude health check requests from tracing
                    tracing.Filter = context =>
                        !context.Request.Path.StartsWithSegments(HealthEndpointPath)
                        && !context.Request.Path.StartsWithSegments(AlivenessEndpointPath)
                )
                // Uncomment the following line to enable gRPC instrumentation (requires the OpenTelemetry.Instrumentation.GrpcNetClient package)
                //.AddGrpcClientInstrumentation()
                .AddHttpClientInstrumentation();
        });

    builder.AddOpenTelemetryExporters();

    return builder;
}

Metodo ConfigureOpenTelemetry:

  • Aggiunge .NET.NET Aspire dati di telemetria registrazione per includere messaggi e ambiti formattati.
  • Aggiunge OpenTelemetry metriche e traccia che includono:
    • Metriche di strumentazione di runtime.
    • ASP.NET Core metriche di strumentazione.
    • Metriche di strumentazione HttpClient.
    • In un ambiente di sviluppo, il AlwaysOnSampler viene usato per visualizzare tutte le tracce.
    • Dettagli della traccia per ASP.NET Core, gRPC e strumentazione HTTP.
  • Aggiunge OpenTelemetry gli esportatori chiamando AddOpenTelemetryExporters.

Il metodo AddOpenTelemetryExporters viene definito privatamente come segue:

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

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

    // 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;
}

Il metodo AddOpenTelemetryExporters aggiunge OpenTelemetry gli esportatori in base alle condizioni seguenti:

  • Se la variabile di ambiente OTEL_EXPORTER_OTLP_ENDPOINT è impostata, viene aggiunto l'utilità di esportazione OpenTelemetry.
  • Facoltativamente, i consumer di impostazioni predefinite del servizio .NET Aspire possono rimuovere il commento da parte di codice per abilitare l'utilità di esportazione Prometheus o l'utilità di esportazione Azure Monitor.

Per altre informazioni, vedere .NET.NET Aspire telemetria.

Configurazione dei controlli di integrità

I controlli di integrità vengono usati da vari strumenti e sistemi per valutare l'idoneità dell'app. .NET .NET Aspire fornisce un set di impostazioni predefinite con parere per i controlli di integrità, configurati con il metodo AddDefaultHealthChecks:

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

    return builder;
}

Il metodo AddDefaultHealthChecks aggiunge un controllo di attività predefinito per assicurarsi che l'app sia reattiva. La chiamata a AddHealthChecks registra il HealthCheckService. Per altre informazioni, vedere .NET.NET Aspire controlli di integrità.

Configurazione dei controlli di integrità dell'app Web

Per esporre i controlli di integrità in un'app Web, .NET.NET Aspire determina automaticamente il tipo di progetto a cui si fa riferimento all'interno della soluzione e aggiunge la chiamata appropriata a MapDefaultEndpoints:

public static WebApplication MapDefaultEndpoints(this WebApplication app)
{
    // 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(HealthEndpointPath);

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

    return app;
}

Metodo MapDefaultEndpoints:

  • Consente ai consumer di rimuovere facoltativamente il commento da parte di codice per abilitare l'endpoint Prometheus.
  • Esegue il mapping dell'endpoint dei controlli di integrità a /health.
  • Esegue il mapping dell'endpoint di attività a /alive route in cui il tag di controllo integrità contiene live.

Annotazioni

.NET .NET Aspire A partire dalla versione 9.2, il modello iniziale è stato aggiornato per includere una chiamata a WithHttpsHealthCheck per ASP.NET Core i progetti. Per mantenere i log di traccia delle richieste più puliti durante lo sviluppo, le tracce per gli endpoint di integrità configurati (/health e /alive) sono ora escluse per impostazione predefinita nel modello di progetto Service Defaults .

Impostazioni predefinite del servizio personalizzato

Se la configurazione del servizio predefinita fornita dal modello di progetto non è sufficiente per le proprie esigenze, è possibile creare un progetto personalizzato per le impostazioni predefinite del servizio. Ciò è particolarmente utile quando il progetto utilizzato, ad esempio un progetto Worker o WinForms, non può o non vuole avere una dipendenza FrameworkReference da Microsoft.AspNetCore.App.

A tale scopo, creare un nuovo progetto di libreria di classi .NET 9.0 e aggiungere le dipendenze necessarie al file di progetto, considerare l'esempio seguente:

<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>

Creare quindi una classe di estensioni contenente i metodi necessari per configurare le impostazioni predefinite dell'app:

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;
    }
}

Questo è solo un esempio ed è possibile personalizzare la classe AppDefaultsExtensions per soddisfare le esigenze specifiche.

Passaggi successivi

Questo codice è derivato dal modello di applicazione iniziale .NET.NET Aspire ed è destinato a un punto di partenza. È possibile modificare questo codice, ma si ritiene necessario soddisfare le proprie esigenze. È importante sapere che le impostazioni predefinite del servizio e la relativa funzionalità vengono applicate automaticamente a tutte le risorse del progetto in una soluzione .NET.NET Aspire.