Udostępnij za pośrednictwem

ustawienia domyślne usługi .NET.NET Aspire

  • Artykuł

W tym artykule dowiesz się więcej o projekcie domyślnym usługi .NET.NET Aspire, czyli zestawie metod rozszerzeń, które:

Aplikacje natywne dla chmury często wymagają rozbudowanych konfiguracji, aby zapewnić niezawodne i bezpieczne działanie w różnych środowiskach. .NET Aspire udostępnia wiele metod i narzędzi pomocników, które usprawniają zarządzanie konfiguracjami OpenTelemetry, kontroli kondycji, zmiennych środowiskowych i innych.

Eksplorowanie projektu ustawień domyślnych usługi

Gdy enlist in .NET.NET Aspire orchestration lub utworzyć nowy projekt .NET.NET Aspire, do rozwiązania zostanie dodany projekt YourAppName.ServiceDefaults.csproj. Na przykład podczas tworzenia interfejsu API wywołujesz metodę AddServiceDefaults w pliku Program.cs aplikacji:

builder.AddServiceDefaults();

Metoda AddServiceDefaults obsługuje następujące zadania:

  • Konfiguruje OpenTelemetry metryki i śledzenie.
  • Dodaje domyślne punkty końcowe sprawdzania kondycji.
  • Dodaje funkcje odnajdywania usług.
  • Konfiguruje HttpClient do pracy z odnajdywaniem usług.

Aby uzyskać więcej informacji, zobacz Dostarczone metody rozszerzenia, aby uzyskać szczegółowe informacje na temat metody AddServiceDefaults.

Ważny

Projekt domyślny usługi .NET.NET Aspire jest przeznaczony specjalnie do udostępniania pliku Extensions.cs i jego funkcji. Nie dołączaj innych funkcji udostępnionych ani modeli w tym projekcie. W tych celach należy użyć konwencjonalnego projektu biblioteki klas udostępnionych.

Charakterystyka projektu

Projekt YourAppName.ServiceDefaults to biblioteka .NET 9.0 zawierająca następujący kod 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>

Szablon projektu domyślnego usługi nakłada zależność FrameworkReference od Microsoft.AspNetCore.App.

Napiwek

Jeśli nie chcesz stosować zależności od Microsoft.AspNetCore.App, możesz utworzyć projekt domyślnych usług niestandardowych. Aby uzyskać więcej informacji, zobacz ustawienia domyślne usługi niestandardowej.

Właściwość IsAspireSharedProject jest ustawiona na true, która wskazuje, że ten projekt jest projektem udostępnionym. Narzędzia .NET Aspire używają tego projektu jako odwołania do innych projektów dodanych do rozwiązania .NET Aspire. Po zarejestrowaniu nowego projektu do orkiestracji program automatycznie odwołuje się do projektu YourAppName.ServiceDefaults i aktualizuje plik Program.cs w celu wywołania metody AddServiceDefaults.

Udostępnione metody rozszerzenia

Projekt YourAppName.ServiceDefaults uwidacznia jeden plik Extensions.cs zawierający kilka metod rozszerzenia opinii:

  • AddServiceDefaults: dodaje funkcję domyślną usługi.
  • ConfigureOpenTelemetry: konfiguruje metryki i śledzenie OpenTelemetry.
  • AddDefaultHealthChecks: dodaje domyślne punkty końcowe sprawdzania kondycji.
  • MapDefaultEndpoints: mapuje punkt końcowy kontroli kondycji na /health i punkt końcowy aktualności, aby /alive.

Dodawanie funkcji domyślnych usługi

Metoda AddServiceDefaults definiuje konfiguracje domyślne z następującymi funkcjami opinii:

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

Powyższy kod:

  • Konfiguruje OpenTelemetry metryki i śledzenie, wywołując metodę ConfigureOpenTelemetry.
  • Dodaje domyślne punkty końcowe sprawdzania kondycji przez wywołanie metody AddDefaultHealthChecks.
  • Dodaje funkcje odnajdywania usługi przez wywołanie metody AddServiceDiscovery.
  • Konfiguruje domyślne HttpClient przez wywołanie metody ConfigureHttpClientDefaults — która jest oparta na Tworzenie odpornych aplikacji HTTP: Kluczowe wzorce programistyczne:
    • Dodaje standardową procedurę obsługi odporności HTTP przez wywołanie metody AddStandardResilienceHandler.
    • Określa, że IHttpClientBuilder powinien używać odnajdywania usług, wywołując metodę UseServiceDiscovery.
  • Zwraca wystąpienie IHostApplicationBuilder, aby umożliwić łączenie metod.

konfiguracja OpenTelemetry

Telemetria jest krytyczną częścią każdej aplikacji natywnej dla chmury. .NET Aspire zawiera zestaw wartości domyślnych dla OpenTelemetry, które są skonfigurowane przy użyciu 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:

  • Dodaje .NET.NET Aspire dane telemetryczne rejestrowania w celu uwzględnienia sformatowanych komunikatów i zakresów.
  • Dodaje OpenTelemetry metryki i śledzenie, które obejmują:
    • Metryki instrumentacji środowiska uruchomieniowego.
    • ASP.NET Core metryki instrumentacji.
    • Metryki instrumentacji HttpClient.
    • W środowisku projektowym AlwaysOnSampler służy do wyświetlania wszystkich śladów.
    • Szczegóły śledzenia ASP.NET Core, gRPC i instrumentacji HTTP.
  • Dodaje eksporterów OpenTelemetry, wywołując AddOpenTelemetryExporters.

Metoda AddOpenTelemetryExporters jest definiowana prywatnie w następujący sposób:

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 dodaje eksporterów OpenTelemetry na podstawie następujących warunków:

  • Jeśli zmienna środowiskowa OTEL_EXPORTER_OTLP_ENDPOINT jest ustawiona, dodawany jest eksporter OpenTelemetry.
  • Opcjonalnie użytkownicy domyślnych .NET Aspire usług mogą usunąć znaczniki komentarza, aby włączyć eksportera Prometheus lub eksportera monitora Azure.

Aby uzyskać więcej informacji, zobacz .NET.NET Aspire telemetrii.

Konfiguracja kontroli kondycji

Testy kondycji są używane przez różne narzędzia i systemy do oceny gotowości aplikacji. .NET .NET Aspire zawiera zestaw wartości domyślnych opinii dla kontroli kondycji, które są skonfigurowane przy użyciu metody 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 dodaje domyślne sprawdzanie dostępności, aby upewnić się, że aplikacja reaguje. Wywołanie AddHealthChecks rejestruje HealthCheckService. Aby uzyskać więcej informacji, zobacz .NET.NET Aspire kontroli kondycji.

Konfiguracja kontroli kondycji aplikacji internetowej

Aby uwidocznić kontrole kondycji w aplikacji internetowej, .NET.NET Aspire automatycznie określa typ przywoływanego projektu w rozwiązaniu i dodaje odpowiednie wywołanie 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żliwia użytkownikom opcjonalne anulowanie komentarza kodu w celu włączenia punktu końcowego Prometheus.
  • Mapuje punkt końcowy kontroli kondycji na /health.
  • Mapuje punkt końcowy aktualności na /alive trasę, w której tag sprawdzania kondycji zawiera live.

Aby uzyskać więcej informacji, zobacz .NET.NET Aspire kontroli kondycji.

Ustawienia domyślne usługi niestandardowej

Jeśli domyślna konfiguracja usługi dostarczona przez szablon projektu nie jest wystarczająca dla Twoich potrzeb, możesz utworzyć własny projekt domyślny usługi. Jest to szczególnie przydatne, gdy projekt zużywany, taki jak projekt Roboczy lub projekt WinForms, nie może lub nie chce mieć zależności FrameworkReference od Microsoft.AspNetCore.App.

W tym celu utwórz nowy projekt biblioteki klas .NET 9.0 i dodaj niezbędne zależności do pliku projektu, rozważmy następujący przykład:

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

Następnie utwórz klasę rozszerzeń zawierającą niezbędne metody konfigurowania ustawień domyślnych aplikacji:

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

Jest to tylko przykład i można dostosować klasę AppDefaultsExtensions w celu spełnienia określonych potrzeb.

Następne kroki

Ten kod pochodzi z szablonu aplikacji początkowej .NET.NET Aspire i jest przeznaczony jako punkt początkowy. Możesz zmodyfikować ten kod, jednak uważasz, że jest to konieczne do spełnienia Twoich potrzeb. Ważne jest, aby wiedzieć, że projekt domyślny usługi i jego funkcjonalność są automatycznie stosowane do wszystkich zasobów projektu w rozwiązaniu .NET.NET Aspire.