standaardinstellingen voor .NET.NET Aspire-service

In dit artikel leert u meer over het .NET.NET Aspire servicestandaardproject, een set uitbreidingsmethoden die:

• Verbind telemetriegegevens, statuscontroles, servicedetectie met uw app.
• Kunnen worden aangepast en uitbreidbaar.

Cloudeigen toepassingen vereisen vaak uitgebreide configuraties om ervoor te zorgen dat ze betrouwbaar en veilig in verschillende omgevingen werken. .NET Aspire biedt veel helpermethoden en hulpprogramma's om het beheer van configuraties voor OpenTelemetry, statuscontroles, omgevingsvariabelen en meer te stroomlijnen.

Het standaardproject voor de service verkennen

Wanneer u in .NET.NET Aspire indeling indeling of een nieuw .NET.NET Aspire projectmaakt, wordt het YourAppName.ServiceDefaults.csproj project toegevoegd aan uw oplossing. Wanneer u bijvoorbeeld een API bouwt, roept u de methode AddServiceDefaults aan in het Program.cs-bestand van uw apps:

builder.AddServiceDefaults();

De methode AddServiceDefaults verwerkt de volgende taken:

• Hiermee configureert u OpenTelemetry metrische gegevens en tracering.
• Voegt standaardstatuscontrole-eindpunten toe.
• Hiermee voegt u functionaliteit voor servicedetectie toe.
• Hiermee configureert u HttpClient om te werken met servicedetectie.

Zie Opgegeven extensiemethoden voor meer informatie over de methode AddServiceDefaults.

Belangrijk

Het .NET.NET Aspire-serviceproject is speciaal ontworpen voor het delen van het Extensions.cs-bestand en de functionaliteit ervan. Neem geen andere gedeelde functionaliteit of modellen in dit project op. Gebruik een conventioneel gedeeld klassebibliotheekproject voor deze doeleinden.

Projectkenmerken

Het YourAppName.ServiceDefaults project is een .NET 9.0-bibliotheek met de volgende XML:

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

Met de standaardprojectsjabloon voor de service wordt een FrameworkReference afhankelijkheid van Microsoft.AspNetCore.Appopgelegd.

Fooi

Als u geen afhankelijkheid wilt maken van Microsoft.AspNetCore.App, kunt u een aangepast servicestandaardproject maken. Zie standaardinstellingen voor aangepaste servicesvoor meer informatie.

De eigenschap IsAspireSharedProject is ingesteld op true, wat aangeeft dat dit project een gedeeld project is. De .NET Aspire tooling gebruikt dit project als referentie voor andere projecten die zijn toegevoegd aan een .NET Aspire oplossing. Wanneer u het nieuwe project inschakelt voor indeling, verwijst het automatisch naar het YourAppName.ServiceDefaults project en wordt het Program.cs-bestand bijgewerkt om de AddServiceDefaults-methode aan te roepen.

Opgegeven extensiemethoden

In het YourAppName.ServiceDefaults project wordt één Extensions.cs-bestand met verschillende methoden voor de extensie weergegeven:

• AddServiceDefaults: hiermee voegt u de standaardfunctionaliteit van de service toe.
• ConfigureOpenTelemetry: configureert OpenTelemetry metrische gegevens en tracering.
• AddDefaultHealthChecks: voegt standaardstatuscontrole-eindpunten toe.
• MapDefaultEndpoints: wijst het eindpunt voor statuscontroles toe aan /health en het eindpunt voor de liveness aan /alive.

Standaardfunctionaliteit voor services toevoegen

De methode AddServiceDefaults definieert standaardconfiguraties met de volgende adviesfunctionaliteit:

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

De voorgaande code:

• Hiermee configureert u OpenTelemetry metrische gegevens en tracering door de ConfigureOpenTelemetry methode aan te roepen.
• Voegt standaardstatuscontrole-eindpunten toe door de methode AddDefaultHealthChecks aan te roepen.
• Voegt servicedetectie functionaliteit toe door de methode AddServiceDiscovery aan te roepen.
• Hiermee configureert u HttpClient standaardinstellingen door de ConfigureHttpClientDefaults methode aan te roepen. Deze methode is gebaseerd op Tolerante HTTP-apps bouwen: Belangrijke ontwikkelingspatronen:
  • Voegt de standaard HTTP-tolerantiehandler toe door de AddStandardResilienceHandler methode aan te roepen.
  • Hiermee geeft u op dat de IHttpClientBuilder servicedetectie moet gebruiken door de UseServiceDiscovery methode aan te roepen.
• Retourneert het IHostApplicationBuilder exemplaar om methodekoppeling mogelijk te maken.

configuratie van OpenTelemetry

Telemetrie is een essentieel onderdeel van elke cloudeigen toepassing. .NET Aspire biedt een set aanbevolen standaardwaarden voor OpenTelemetry, die zijn geconfigureerd met de methode 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;
}

De methode ConfigureOpenTelemetry:

• Voegt .NET.NET Aspire telemetrie toe logboekregistratie om opgemaakte berichten en bereiken op te nemen.
• Voegt OpenTelemetry metrische gegevens en tracering toe, waaronder:
  • Metrische gegevens voor runtime-instrumentatie.
  • ASP.NET Core metrische instrumentatiegegevens.
  • Metrische gegevens voor httpClient-instrumentatie.
  • In een ontwikkelomgeving wordt de AlwaysOnSampler gebruikt om alle traceringen weer te geven.
  • Traceringsgegevens voor ASP.NET Core, gRPC en HTTP-instrumentatie.
• Voegt OpenTelemetry exporteurs toe door AddOpenTelemetryExportersaan te roepen.

De AddOpenTelemetryExporters methode wordt als volgt privé gedefinieerd:

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

De methode AddOpenTelemetryExporters voegt OpenTelemetry exporteurs toe op basis van de volgende voorwaarden:

• Als de omgevingsvariabele OTEL_EXPORTER_OTLP_ENDPOINT is ingesteld, wordt de OpenTelemetry exporteur toegevoegd.
• Consumenten van .NET Aspire servicestandaarden kunnen eventueel opmerkingen bij code ongedaan maken om de Prometheus-exporteur of de Azure Monitor-exporteur in te schakelen.

Zie .NET.NET Aspire telemetrievoor meer informatie.

Configuratie van statuscontroles

Statuscontroles worden gebruikt door verschillende hulpprogramma's en systemen om de gereedheid van uw app te beoordelen. .NET .NET Aspire biedt een set aanbevolen standaardinstellingen voor statuscontroles, die zijn geconfigureerd met de AddDefaultHealthChecks methode:

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

De methode AddDefaultHealthChecks voegt een standaard livenesscontrole toe om ervoor te zorgen dat de app reageert. De aanroep van AddHealthChecks registreert de HealthCheckService. Zie .NET.NET Aspire statuscontrolesvoor meer informatie.

Configuratie van web-app-statuscontroles

Als u statuscontroles in een web-app beschikbaar wilt maken, bepaalt .NET.NET Aspire automatisch het type project waarnaar in de oplossing wordt verwezen en voegt u de juiste aanroep toe aan 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;
}

De methode MapDefaultEndpoints:

• Hiermee kunnen consumenten eventueel opmerkingen bij een code ongedaan maken om het Prometheus-eindpunt in te schakelen.
• Hiermee wordt het eindpunt voor statuscontroles toegewezen aan /health.
• Wijst het liveness-eindpunt toe aan /alive route waar de statuscontroletag livebevat.

Zie .NET.NET Aspire statuscontrolesvoor meer informatie.

Standaardinstellingen voor aangepaste services

Als de standaardserviceconfiguratie van de projectsjabloon niet voldoende is voor uw behoeften, hebt u de mogelijkheid om uw eigen standaardserviceproject te maken. Dit is vooral handig wanneer uw verbruikende project, zoals een Werkrolproject of WinForms-project, geen FrameworkReference afhankelijk van Microsoft.AspNetCore.Appwilt hebben.

Hiervoor maakt u een nieuw .NET 9.0-klassebibliotheekproject en voegt u de benodigde afhankelijkheden toe aan het projectbestand. Bekijk het volgende voorbeeld:

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

Maak vervolgens een uitbreidingsklasse die de benodigde methoden bevat om de standaardinstellingen voor de app te configureren:

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

Dit is slechts een voorbeeld en u kunt de AppDefaultsExtensions klasse aanpassen aan uw specifieke behoeften.

Volgende stappen

Deze code is afgeleid van de sjabloon .NET.NET Aspire Starter Application en is bedoeld als uitgangspunt. U kunt deze code wijzigen, maar u acht het noodzakelijk om aan uw behoeften te voldoen. Het is belangrijk om te weten dat het standaardproject van de service en de bijbehorende functionaliteit automatisch worden toegepast op alle projectbronnen in een .NET.NET Aspire oplossing.

• Servicedetectie in .NET.NET Aspire
• .NET .NET Aspire SDK-
• .NET .NET Aspire sjablonen
• Statuscontroles in .NET.NET Aspire
• .NET .NET Aspire telemetrie-
• Tolerante HTTP-apps bouwen: Belangrijke ontwikkelingspatronen