Sdílet prostřednictvím

výchozí hodnoty služby .NET.NET Aspire

  • Článek

V tomto článku se dozvíte o výchozím projektu služby .NET.NET Aspire, což je sada metod rozšíření, které:

  • Připojte telemetrii, kontroly stavu, zjišťování služby .
  • Jsou přizpůsobitelné a rozšiřitelné.

Aplikace nativní pro cloud často vyžadují rozsáhlé konfigurace, aby se zajistilo, že budou spolehlivě a bezpečně fungovat v různých prostředích. .NET Aspire poskytuje mnoho pomocných metod a nástrojů, které zjednodušují správu konfigurací pro OpenTelemetry, kontroly stavu, proměnné prostředí a další.

Prozkoumání výchozího projektu služby

Když zařazení do orchestrace .NET.NET Aspire nebo vytvoříte nový projekt .NET.NET Aspire, přidá se do vašeho řešení projekt YourAppName.ServiceDefaults.csproj. Například při vytváření rozhraní API voláte metodu AddServiceDefaults v souboru Program.cs vašich aplikací:

builder.AddServiceDefaults();

Metoda AddServiceDefaults zpracovává následující úlohy:

  • Konfiguruje metriky a trasování OpenTelemetry.
  • Přidá výchozí koncové body kontroly stavu.
  • Přidá funkci zjišťování služeb.
  • Konfiguruje HttpClient pro práci se zjišťováním služeb.

Další informace najdete v tématu Poskytnuté rozšiřující metody podrobnosti o metodě AddServiceDefaults.

Důležitý

Výchozí projekt služby .NET.NET Aspire je určený speciálně pro sdílení souboru Extensions.cs a jeho funkcí. Do tohoto projektu nezahrnujte další sdílené funkce ani modely. Pro tyto účely použijte běžný projekt knihovny sdílených tříd.

Charakteristiky projektu

Projekt YourAppName.ServiceDefaults je knihovna .NET 9.0, která obsahuje následující kód 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.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>

Výchozí šablona projektu služby ukládá FrameworkReference závislost na Microsoft.AspNetCore.App.

Spropitné

Pokud nechcete využívat závislost na Microsoft.AspNetCore.App, můžete vytvořit vlastní projekt výchozích služeb. Další informace najdete v tématu Výchozí nastavení vlastní služby.

Vlastnost IsAspireSharedProject je nastavena na true, což označuje, že tento projekt je sdílený projekt. Nástroje .NET Aspire tento projekt používají jako referenci pro jiné projekty přidané do .NET Aspire řešení. Když přidáte nový projekt pro orchestraci, automaticky odkazuje na YourAppName.ServiceDefaults projektu a aktualizuje Program.cs soubor tak, aby volal metodu AddServiceDefaults.

Poskytované rozšiřující metody

Projekt YourAppName.ServiceDefaults zpřístupňuje jeden soubor Extensions.cs, který obsahuje několik metod rozšíření se stanoviskem:

  • AddServiceDefaults: Přidá výchozí funkce služby.
  • ConfigureOpenTelemetry: Konfiguruje metriky a trasování OpenTelemetry.
  • AddDefaultHealthChecks: Přidá výchozí koncové body kontroly stavu.
  • MapDefaultEndpoints: Mapuje koncový bod kontroly stavu na /health a koncový bod aktivity na /alive.

Přidání výchozích funkcí služby

Metoda AddServiceDefaults definuje výchozí konfigurace s následujícími názornými funkcemi:

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

Předchozí kód:

  • Nakonfiguruje OpenTelemetry metriky a trasování voláním metody ConfigureOpenTelemetry.
  • Přidá výchozí koncové body kontroly stavu voláním metody AddDefaultHealthChecks.
  • Přidá funkci zjišťování služby voláním metody AddServiceDiscovery.
  • Konfiguruje výchozí nastavení HttpClient voláním metody ConfigureHttpClientDefaults , která je založená na Vytváření odolných aplikací HTTP: Klíčové vývojové vzory:
    • Přidá standardní obslužnou rutinu odolnosti PROTOKOLU HTTP voláním metody AddStandardResilienceHandler.
    • Určuje, že IHttpClientBuilder by měla používat zjišťování služby voláním metody UseServiceDiscovery.
  • Vrátí instanci IHostApplicationBuilder, která umožňuje řetězení metod.

konfigurace OpenTelemetry

Telemetrie je důležitou součástí jakékoli aplikace nativní pro cloud. .NET Aspire poskytuje sadu výchozích hodnot pro OpenTelemetry, které jsou nakonfigurované pomocí metody 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;
}

Metoda ConfigureOpenTelemetry:

  • Přidá .NET.NET Aspire telemetrii protokolování, aby zahrnovalo formátované zprávy a obory.
  • Přidá metriky OpenTelemetry a trasování, které zahrnují:
    • Metriky instrumentace modulu runtime
    • metriky instrumentace ASP.NET Core.
    • Metriky instrumentace HttpClient
    • Ve vývojovém prostředí se AlwaysOnSampler používá k zobrazení všech trasování.
    • Podrobnosti o trasování pro ASP.NET Core, gRPC a instrumentaci HTTP
  • Přidává OpenTelemetry vývozci voláním AddOpenTelemetryExporters.

Metoda AddOpenTelemetryExporters je definována soukromě následujícím způsobem:

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

Metoda AddOpenTelemetryExporters přidává OpenTelemetry vývozce na základě následujících podmínek:

  • Pokud je nastavena proměnná prostředí OTEL_EXPORTER_OTLP_ENDPOINT, přidá se OpenTelemetry vývozce.
  • Volitelně můžou spotřebitelé výchozích hodnot služby .NET Aspire zrušit komentář, aby umožnili vývozci prometheus nebo vývozce služby Azure Monitor.

Další informace najdete v tématu .NET.NET Aspire telemetrie.

Konfigurace kontrol stavu

Kontroly stavu používají různé nástroje a systémy k posouzení připravenosti vaší aplikace. .NET .NET Aspire poskytuje sadu výchozích hodnot pro kontroly stavu, které jsou nakonfigurované metodou 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;
}

Metoda AddDefaultHealthChecks přidá výchozí kontrolu aktivity, která zajistí, že aplikace reaguje. Volání AddHealthChecks zaregistruje HealthCheckService. Další informace najdete v tématu .NET.NET Aspire kontroly stavu.

Konfigurace kontrol stavu webové aplikace

Pokud chcete zveřejnit kontroly stavu ve webové aplikaci, .NET.NET Aspire automaticky určí typ projektu, na který se odkazuje v rámci řešení, a přidá příslušné volání 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;
}

Metoda MapDefaultEndpoints:

  • Umožňuje uživatelům volitelně zrušit komentář k určitému kódu, aby povolili koncový bod Prometheus.
  • Mapuje koncový bod kontroly stavu na /health.
  • Mapuje koncový bod aktivity na /alive trasu, kde značka kontroly stavu obsahuje live.

Další informace najdete v tématu .NET.NET Aspire kontroly stavu.

Výchozí hodnoty vlastních služeb

Pokud výchozí konfigurace služby poskytovaná šablonou projektu nestačí pro vaše potřeby, máte možnost vytvořit vlastní projekt výchozích služeb. To je užitečné zejména v případě, že váš projekt využívající pracovní proces nebo projekt WinForms nemůže nebo nechce mít FrameworkReference závislost na Microsoft.AspNetCore.App.

Uděláte to tak, že vytvoříte nový projekt knihovny tříd .NET 9.0 a přidáte do souboru projektu potřebné závislosti, zvažte následující příklad:

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

Pak vytvořte třídu rozšíření, která obsahuje nezbytné metody konfigurace výchozích hodnot aplikace:

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

Toto je pouze příklad a můžete přizpůsobit AppDefaultsExtensions třídu tak, aby vyhovovala vašim konkrétním potřebám.

Další kroky

Tento kód je odvozen ze šablony .NET.NET Aspire Starter Application a je určen jako výchozí bod. Tento kód můžete upravit, ale považujete to za nezbytné pro splnění vašich potřeb. Je důležité vědět, že výchozí projekt služby a jeho funkce se automaticky použijí na všechny prostředky projektu v řešení .NET.NET Aspire.