standardvärden för .NET.NET Aspire-tjänsten

I den här artikeln får du lära dig mer om standardprojektet .NET.NET Aspire 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. .NET 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 Enlist i .NET.NET Aspire orchestration eller skapa ett nytt .NET.NET Aspire projektläggs YourAppName.ServiceDefaults.csproj-projektet till i din lösning. 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.

Viktig

Standardprojektet för .NET.NET Aspire-tjänsten är särskilt utformat för att dela Extensions.cs-filen och dess funktioner. Inkludera inte andra delade funktioner eller modeller i det här projektet. Använd ett konventionellt biblioteksprojekt för delad klass för dessa ändamål.

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.2.0" />
    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.0.0" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.11.1" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.11.1" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.11.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.11.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.11.0" />
  </ItemGroup>

</Project>

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

Dricks

Om du inte vill vara beroende av Microsoft.AspNetCore.Appkan du skapa ett standardprojekt för anpassade tjänster. Mer information finns i custom service defaults.

Egenskapen IsAspireSharedProject är inställd på true, vilket anger att det här projektet är ett delat projekt. Verktyget .NET Aspire använder det här projektet som referens för andra projekt som lagts till i en .NET 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 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;
}

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. .NET Aspire innehåller en uppsättning åsiktsstandarder för OpenTelemetry, som konfigureras med metoden 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;
}

Metoden ConfigureOpenTelemetry:

• Lägger till .NET.NET Aspire telemetri loggning 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 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;
}

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 .NET Aspire tjänststandarder avkommentera viss kod för att aktivera Prometheus-exportören eller Azure Monitor-exportören.

Mer information finns i .NET.NET Aspire telemetri.

Konfiguration av hälsokontroller

Hälsokontroller används av olika verktyg och system för att utvärdera appens beredskap. .NET .NET Aspire tillhandahåller en uppsättning åsiktsmässiga standardvärden för hälsokontroller som konfigureras med metoden 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;
}

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 .NET.NET Aspire hälsokontroller.

Konfiguration av hälsokontroller för webbappar

Om du vill exponera hälsokontroller i en webbapp avgör .NET.NET Aspire 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)
{
    // 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;
}

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.

Mer information finns i .NET.NET Aspire hälsokontroller.

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 .NET.NET Aspire Starter-program 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 .NET.NET Aspire lösning.

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