Aspire standardinställningar för tjänsten

I den Aspire här artikeln får du lära dig mer om standardprojektet för tjänsten, en uppsättning tilläggsmetoder som:

• Anslut telemetri, hälsokontroller, tjänstidentifiering till din app.
• Är anpassningsbara och utökningsbara.

Molnbaserade program kräver ofta omfattande konfigurationer för att säkerställa att de fungerar i olika miljöer på ett tillförlitligt och säkert sätt. Aspire innehåller många hjälpmetoder och verktyg för att effektivisera hanteringen av konfigurationer för OpenTelemetry, hälsokontroller, miljövariabler med mera.

Utforska standardprojektet för tjänsten

När du antingen registrerar dig i orkestrering eller skapar ett nytt projekt läggs projektet YourAppName.ServiceDefaults.csproj till i Aspire din lösning.Aspire När du till exempel skapar ett API anropar du metoden AddServiceDefaults i Program.cs-filen för dina appar:

builder.AddServiceDefaults();

Metoden AddServiceDefaults hanterar följande uppgifter:

• Konfigurerar OpenTelemetry mått och spårning.
• Lägger till standardslutpunkter för hälsokontroll.
• Lägger till funktioner för tjänstidentifiering.
• Konfigurerar HttpClient att fungera med tjänstidentifiering.

Mer information finns i Tillhandahållna tilläggsmetoder för mer information om metoden AddServiceDefaults.

Projektegenskaper

projektet YourAppName.ServiceDefaults är ett .NET 9.0-bibliotek som innehåller följande 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.9.0" />
    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.5.2" />
    <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>

Standardprojektmallen för tjänsten medför ett FrameworkReference beroende av Microsoft.AspNetCore.App.

Egenskapen IsAspireSharedProject är inställd på true, vilket anger att det här projektet är ett delat projekt. Verktygen Aspire använder det här projektet som referens för andra projekt som lagts till i en Aspire lösning. När du registrerar det nya projektet för orkestrering refererar det automatiskt till projektet YourAppName.ServiceDefaults och uppdaterar Program.cs-filen för att anropa metoden AddServiceDefaults.

Tillhandahållna tilläggsmetoder

Projektet YourAppName.ServiceDefaults exponerar en enda Extensions.cs fil som innehåller flera metoder för åsiktstillägg:

• AddServiceDefaults: Lägger till standardfunktioner för tjänsten.
• ConfigureOpenTelemetry: Konfigurerar OpenTelemetry mått och spårning.
• AddDefaultHealthChecks: Lägger till standardslutpunkter för hälsokontroll.
• MapDefaultEndpoints: Mappar slutpunkten för hälsokontroller till /health och slutpunkten för liveness till /alive.

Lägg till standardfunktioner för tjänsten

Metoden AddServiceDefaults definierar standardkonfigurationer med följande åsiktsfunktioner:

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

Föregående kod:

• Konfigurerar OpenTelemetry mått och spårning genom att anropa metoden ConfigureOpenTelemetry.
• Lägger till standardslutpunkter för hälsokontroll genom att anropa metoden AddDefaultHealthChecks.
• Lägger till tjänstidentifiering funktioner genom att anropa metoden AddServiceDiscovery.
• Konfigurerar HttpClient standardvärden genom att anropa metoden ConfigureHttpClientDefaults – som baseras på Skapa motståndskraftiga HTTP-appar: Viktiga utvecklingsmönster:
  • Lägger till standardhanteraren för HTTP-motståndskraft genom att anropa metoden AddStandardResilienceHandler.
  • Anger att IHttpClientBuilder ska använda tjänstidentifiering genom att anropa metoden UseServiceDiscovery.
• Returnerar den IHostApplicationBuilder instansen för att tillåta metodlänkning.

OpenTelemetry konfiguration

Telemetri är en viktig del av alla molnbaserade program. Aspire innehåller en uppsättning åsiktsstandarder för OpenTelemetry, som konfigureras med metoden 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;
}

Metoden ConfigureOpenTelemetry:

• Lägger till Aspire telemetriloggning för att inkludera formaterade meddelanden och omfång.
• Lägger till OpenTelemetry mått och spårning som omfattar:
  • Mått för körningsinstrumentation.
  • ASP.NET Core instrumentationsmått.
  • HttpClient-instrumentationsmått.
  • I en utvecklingsmiljö används AlwaysOnSampler för att visa alla spårningar.
  • Spårningsinformation för ASP.NET Core, gRPC- och HTTP-instrumentation.
• Lägger till OpenTelemetry exportörer genom att anropa AddOpenTelemetryExporters.

Metoden AddOpenTelemetryExporters definieras privat enligt följande:

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

Metoden AddOpenTelemetryExporters lägger till OpenTelemetry exportörer baserat på följande villkor:

• Om OTEL_EXPORTER_OTLP_ENDPOINT miljövariabeln anges läggs OpenTelemetry-exportören till.
• Alternativt kan användare av Aspire tjänststandarder avkommentera viss kod för att aktivera Prometheus-exportören eller Azure Monitor-exportören.

Mer information finns i Aspire telemetri.

Konfiguration av hälsokontroller

Hälsokontroller används av olika verktyg och system för att utvärdera appens beredskap. Aspire innehåller en uppsättning av åsiktsmässiga standardvärden för hälsokontroller, som är konfigurerade med AddDefaultHealthChecks metoden:

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

Metoden AddDefaultHealthChecks lägger till en standardkontroll för liveness för att säkerställa att appen svarar. Anropet till AddHealthChecks registrerar HealthCheckService. Mer information finns i Aspire Hälsokontroller.

Konfiguration av hälsokontroller för webbappar

Om du vill exponera hälsokontroller i en webbapp Aspire avgör du automatiskt vilken typ av projekt som refereras i lösningen och lägger till lämpligt anrop till 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;
}

Metoden MapDefaultEndpoints:

• Gör att konsumenter kan avkommentera viss kod för att aktivera Prometheus-slutpunkten.
• Mappar slutpunkten för hälsokontroller till /health.
• Mappar liveness-slutpunkten till /alive väg där hälsokontrolltaggen innehåller live.

Standardinställningar för anpassad tjänst

Om standardtjänstkonfigurationen som tillhandahålls av projektmallen inte räcker för dina behov kan du skapa ett eget standardprojekt för tjänsten. Detta är särskilt användbart när ditt förbrukande projekt, till exempel ett Worker-projekt eller WinForms-projekt, inte kan eller inte vill ha ett FrameworkReference beroende av Microsoft.AspNetCore.App.

Det gör du genom att skapa ett nytt .NET 9.0-klassbiblioteksprojekt och lägga till nödvändiga beroenden i projektfilen. Tänk på följande exempel:

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

Skapa sedan en tilläggsklass som innehåller de metoder som krävs för att konfigurera appens standardvärden:

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

Det här är bara ett exempel och du kan anpassa klassen AppDefaultsExtensions efter dina specifika behov.

Nästa steg

Den här koden härleds från mallen Aspire Startprogram och är avsedd som en startpunkt. Du kan ändra den här koden, men du anser att den är nödvändig för att uppfylla dina behov. Det är viktigt att veta att tjänstens standardprojekt och dess funktioner tillämpas automatiskt på alla projektresurser i en Aspire lösning.

• Tjänstidentifiering i Aspire
• Aspire SDK
• Aspire Mallar
• Hälsokontroller i Aspire
• Aspire telemetri
• Skapa motståndskraftiga HTTP-appar: Viktiga utvecklingsmönster