Condividi tramite

impostazioni predefinite del servizio .NET.NET Aspire

  • Articolo

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

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

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

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

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

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

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.

Per altre informazioni, vedere .NET.NET Aspire controlli di integrità.

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.