.NET .NET Aspire szolgáltatás alapértelmezései

Ebben a cikkben megismerheti az alapértelmezett .NET.NET Aspire szolgáltatásprojektet, amely a következő bővítménymetelyek készletét tartalmazza:

• Csatlakoztassa telemetriai, állapotellenőrzési, szolgáltatásfelderítési az alkalmazáshoz.
• Testreszabhatók és bővíthetőek.

A natív felhőalkalmazások gyakran igényelnek széles körű konfigurációkat, hogy megbízhatóan és biztonságosan működjenek a különböző környezetekben. .NET Aspire számos segítő módszert és eszközt kínál a OpenTelemetry, állapotellenőrzések, környezeti változók és egyebek konfigurációinak felügyeletének egyszerűsítéséhez.

A szolgáltatás alapértelmezett projektjének megismerése

Ha .NET.NET Aspire vezénylési vagy létrehoz egy új .NET.NET Aspire projekt, a megoldáshoz hozzáadja a YourAppName.ServiceDefaults.csproj projektet. Api létrehozásakor például az alkalmazások AddServiceDefaults fájljában a Program.cs metódust kell meghívni:

builder.AddServiceDefaults();

A AddServiceDefaults metódus a következő feladatokat kezeli:

• OpenTelemetry metrikákat és nyomkövetést konfigurál.
• Alapértelmezett állapot-ellenőrzési végpontokat ad hozzá.
• Szolgáltatásfelderítési funkciókat ad hozzá.
• A szolgáltatásfelderítési HttpClient konfigurálja.

További információ: Megadott bővítménymetódusok a AddServiceDefaults metódussal kapcsolatos részletekért.

Projektjellemzők

A YourAppName.ServiceDefaults projekt egy 9.0-s kódtár, amely a következő XML-t tartalmazza:

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

</Project>

A szolgáltatás alapértelmezés szerint a projektsablon FrameworkReference függőséget alkalmaz a Microsoft.AspNetCore.App.

A IsAspireSharedProject tulajdonság értéke true, ami azt jelzi, hogy ez a projekt egy megosztott projekt. A .NET Aspire eszközkészlet ezt a projektet használja a .NET Aspire megoldáshoz hozzáadott egyéb projektek referenciájaként. Amikor bevonja az új projektet vezénylésre, az automatikusan hivatkozik a YourAppName.ServiceDefaults projektre, és frissíti a Program.cs fájlt, hogy meghívja a AddServiceDefaults metódust.

Megadott bővítménymetelyek

A YourAppName.ServiceDefaults projekt egyetlen Extensions.cs fájlt tesz elérhetővé, amely több véleményezett bővítménymetódust tartalmaz:

• AddServiceDefaults: A szolgáltatás alapértelmezett funkcióinak hozzáadása.
• ConfigureOpenTelemetry: OpenTelemetry metrikákat és nyomkövetést konfigurál.
• AddDefaultHealthChecks: Alapértelmezett állapot-ellenőrzési végpontokat ad hozzá.
• MapDefaultEndpoints: Az állapot-ellenőrzési végpontot /health, az élőségi végpontot pedig /alive.

Szolgáltatás alapértelmezett funkcióinak hozzáadása

A AddServiceDefaults metódus az alapértelmezett konfigurációkat a következő véleményezett funkciókkal határozza meg:

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

Az előző kód:

• A OpenTelemetry metódus meghívásával konfigurálja ConfigureOpenTelemetry metrikákat és nyomkövetést.
• Az alapértelmezett állapot-ellenőrzési végpontokat a AddDefaultHealthChecks metódus meghívásával adja hozzá.
• A metódus meghívásával AddServiceDiscovery funkciót ad hozzá.
• Az alapértelmezett HttpClient konfigurálja a ConfigureHttpClientDefaults metódus meghívásával, amely Rugalmas HTTP-alkalmazások létrehozása: Kulcsfejlesztési minták:
  • Hozzáadja a szabványos HTTP-rugalmasságkezelőt a AddStandardResilienceHandler metódus meghívásával.
  • Megadja, hogy a IHttpClientBuilder szolgáltatásfelderítést használjon a UseServiceDiscovery metódus meghívásával.
• A metódusláncolás engedélyezéséhez a IHostApplicationBuilder példányt adja vissza.

OpenTelemetry konfigurációja

A telemetria minden natív felhőbeli alkalmazás kritikus része. .NET Aspire a OpenTelemetry metódussal konfigurált ConfigureOpenTelemetryvéleményezett alapértelmezett beállításainak halmazát biztosítja:

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

A ConfigureOpenTelemetry módszer:

• Hozzáadja .NET.NET Aspire telemetriai naplózást, hogy formázott üzeneteket és hatóköröket tartalmazzon.
• OpenTelemetry metrikákat és nyomkövetést ad hozzá, amelyek a következőket tartalmazzák:
  • Futtatókörnyezeti rendszerállapot-metrikák.
  • ASP.NET Core rendszerállapot-metrikákat.
  • HttpClient-rendszerállapot-metrikák.
  • Fejlesztési környezetben a AlwaysOnSampler az összes nyomkövetés megtekintésére szolgál.
  • A ASP.NET Core, a gRPC és a HTTP-rendszerállapot nyomkövetési adatai.
• OpenTelemetry exportőröket ad hozzá a AddOpenTelemetryExportersmeghívásával .

A AddOpenTelemetryExporters metódus a következőképpen van definiálva:

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

A AddOpenTelemetryExporters módszer OpenTelemetry exportőröket ad hozzá a következő feltételek alapján:

• Ha a OTEL_EXPORTER_OTLP_ENDPOINT környezeti változó be van állítva, a OpenTelemetry exportőr lesz hozzáadva.
• Igény szerint a .NET Aspire szolgáltatás alapértelmezett felhasználói feloldhatnak néhány kódot, hogy engedélyezhessék a Prometheus-exportőrt vagy a Azure Monitor-exportőrt.

További információ: .NET.NET Aspire telemetriai.

Állapot-ellenőrzési konfiguráció

Az állapot-ellenőrzéseket különböző eszközök és rendszerek használják az alkalmazás felkészültségének felméréséhez. .NET .NET Aspire az állapot-ellenőrzésekhez a véleményezett alapértelmezett értékeket biztosítja, amelyek a AddDefaultHealthChecks metódussal vannak konfigurálva:

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

A AddDefaultHealthChecks metódus hozzáad egy alapértelmezett élőképesség-ellenőrzést az alkalmazás válaszkészségének biztosítása érdekében. A AddHealthChecks hívása regisztrálja a HealthCheckService. További információ: .NET.NET Aspire állapot-ellenőrzések.

Webalkalmazás állapot-ellenőrzési konfigurációja

Ha egy webalkalmazás állapotellenőrzéseit szeretné elérhetővé tenni, .NET.NET Aspire automatikusan meghatározza a megoldáson belül hivatkozott projekt típusát, és hozzáadja a megfelelő hívást 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;
}

A MapDefaultEndpoints módszer:

• A prometheus-végpont engedélyezéséhez a felhasználók opcionálisan feloldanak bizonyos kódokat.
• Leképozza az állapot-ellenőrzési végpontot /health.
• Az élőség végpontjának leképezése /alive útvonalra, ahol az állapot-ellenőrző címke livetartalmaz.

További információ: .NET.NET Aspire állapot-ellenőrzések.

Az egyéni szolgáltatás alapértelmezései

Ha a projektsablon által biztosított alapértelmezett szolgáltatáskonfiguráció nem elegendő az Igényeinek, lehetősége van saját alapértelmezett szolgáltatásprojekt létrehozására. Ez különösen akkor hasznos, ha a felhasználó projekt , például a Feldolgozó vagy a WinForms projekt nem tud vagy nem szeretne FrameworkReference függőséget Microsoft.AspNetCore.App.

Ehhez hozzon létre egy új .NET 9.0-s osztálytárprojektet, és adja hozzá a szükséges függőségeket a projektfájlhoz, vegye figyelembe az alábbi példát:

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

Ezután hozzon létre egy bővítményosztályt, amely tartalmazza az alkalmazás alapértelmezéseinek konfigurálásához szükséges módszereket:

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

Ez csak egy példa, és testre szabhatja a AppDefaultsExtensions osztályt az igényeinek megfelelően.

Következő lépések

Ez a kód a kezdőalkalmazás .NET.NET Aspire sablonjából származik, és kiindulópontként szolgál. Szabadon módosíthatja ezt a kódot, azonban úgy véli, hogy az igényeinek megfelelően szükséges. Fontos tudni, hogy a szolgáltatás alapértelmezés szerint a projektet és annak funkcióit automatikusan alkalmazza a .NET.NET Aspire megoldás összes projekterőforrására.

• szolgáltatásfelderítés a .NET.NET Aspire
• .NET .NET Aspire SDK
• .NET .NET Aspire sablonok
• állapot-ellenőrzések .NET.NET Aspire
• .NET .NET Aspire telemetriai
• Rugalmas HTTP-alkalmazások létrehozása: Kulcsfontosságú fejlesztési minták