Freigeben über

Standardeinstellungen für .NET.NET Aspire-Dienst

  • Artikel

In diesem Artikel erfahren Sie mehr über das .NET.NET Aspire Dienststandardprojekt, eine Reihe von Erweiterungsmethoden, die:

Cloud-native Anwendungen erfordern häufig umfangreiche Konfigurationen, um sicherzustellen, dass sie zuverlässig und sicher in verschiedenen Umgebungen funktionieren. .NET Aspire bietet viele Hilfsmethoden und Tools, um die Verwaltung von Konfigurationen für OpenTelemetry, Integritätsprüfungen, Umgebungsvariablen und vieles mehr zu optimieren.

Erkunden des Dienststandardprojekts

Wenn Sie entweder Enlist in .NET.NET Aspire Orchestrierung oder ein neues .NET.NET Aspire Projekterstellen, wird der Projektmappe das YourAppName.ServiceDefaults.csproj Projekt hinzugefügt. Wenn Sie beispielsweise eine API erstellen, rufen Sie die AddServiceDefaults-Methode in der Program.cs Datei Ihrer Apps auf:

builder.AddServiceDefaults();

Die AddServiceDefaults-Methode behandelt die folgenden Aufgaben:

  • Konfiguriert OpenTelemetry Metriken und Ablaufverfolgung.
  • Fügt Standardmäßige Integritätsprüfungsendpunkte hinzu.
  • Fügt Dienstermittlungsfunktionen hinzu.
  • Konfiguriert HttpClient für die Arbeit mit der Dienstermittlung.

Weitere Informationen finden Sie unter Bereitgestellte Erweiterungsmethoden ausführliche Informationen zur AddServiceDefaults Methode.

Wichtig

Das .NET.NET Aspire Dienststandardprojekt wurde speziell für die Freigabe der Extensions.cs Datei und deren Funktionalität entwickelt. Fügen Sie in diesem Projekt keine anderen freigegebenen Funktionen oder Modelle hinzu. Verwenden Sie für diese Zwecke ein herkömmliches freigegebenes Klassenbibliotheksprojekt.

Projektmerkmale

Das YourAppName.ServiceDefaults Projekt ist eine .NET 9.0-Bibliothek, die die folgende XML-Datei enthält:

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

Die Projektvorlage des Dienststandardprojekts stellt eine FrameworkReference Abhängigkeit von Microsoft.AspNetCore.Appauf.

Trinkgeld

Wenn Sie keine Abhängigkeit von Microsoft.AspNetCore.Appübernehmen möchten, können Sie ein benutzerdefiniertes Dienststandardprojekt erstellen. Weitere Informationen finden Sie unter Benutzerdefinierten Dienst standardmäßig.

Die IsAspireSharedProject-Eigenschaft ist auf truefestgelegt, was angibt, dass es sich bei diesem Projekt um ein freigegebenes Projekt handelt. Das .NET Aspire Tooling verwendet dieses Projekt als Referenz für andere Projekte, die einer .NET Aspire Lösung hinzugefügt wurden. Wenn Sie das neue Projekt für die Orchestrierung auflisten, verweist es automatisch auf die YourAppName.ServiceDefaults Projekt und aktualisiert die Program.cs Datei, um die AddServiceDefaults Methode aufzurufen.

Bereitgestellte Erweiterungsmethoden

Das YourAppName.ServiceDefaults--Projekt macht eine einzelne Extensions.cs Datei verfügbar, die mehrere meinungsierte Erweiterungsmethoden enthält:

  • AddServiceDefaults: Fügt die Standardfunktionen des Diensts hinzu.
  • ConfigureOpenTelemetry: Konfiguriert OpenTelemetry Metriken und Ablaufverfolgung.
  • AddDefaultHealthChecks: Fügt Endpunkte für die Standardintegritätsprüfung hinzu.
  • MapDefaultEndpoints: Ordnet den Endpunkt für Integritätsprüfungen /health und dem Livenessendpunkt /alivezu.

Hinzufügen von Dienststandardfunktionen

Die AddServiceDefaults-Methode definiert Standardkonfigurationen mit der folgenden Meinungsfunktion:

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

Der vorangehende Code:

  • Konfiguriert OpenTelemetry Metriken und Ablaufverfolgung durch Aufrufen der ConfigureOpenTelemetry-Methode.
  • Fügt Standardmäßige Integritätsprüfungsendpunkte hinzu, indem die AddDefaultHealthChecks-Methode aufgerufen wird.
  • Fügt Funktionalität Dienstermittlung hinzu, indem die -Methode aufgerufen wird.
  • Konfiguriert HttpClient Standardwerte, indem die ConfigureHttpClientDefaults-Methode aufgerufen wird, die auf Erstellen widerstandsfähiger HTTP-Apps basiert: Wichtige Entwicklungsmuster:
    • Fügt den standardmäßigen HTTP-Resilienzhandler hinzu, indem die AddStandardResilienceHandler-Methode aufgerufen wird.
    • Gibt an, dass der IHttpClientBuilder die Dienstermittlung verwenden soll, indem die UseServiceDiscovery-Methode aufgerufen wird.
  • Gibt die IHostApplicationBuilder Instanz zurück, die die Methodenkette zulassen soll.

OpenTelemetry Konfiguration

Telemetrie ist ein wichtiger Bestandteil jeder cloudeigenen Anwendung. .NET Aspire stellt eine Reihe von Meinungsstandardeinstellungen für OpenTelemetrybereit, die mit der ConfigureOpenTelemetry-Methode konfiguriert sind:

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

Die ConfigureOpenTelemetry-Methode:

  • Fügt .NET.NET Aspire Telemetrie Protokollierung hinzu, um formatierte Nachrichten und Bereiche einzuschließen.
  • Fügt OpenTelemetry Metriken und Ablaufverfolgung hinzu, die Folgendes umfassen:
    • Metriken der Laufzeitinstrumentation.
    • ASP.NET Core Metriken der Instrumentierung.
    • HttpClient-Instrumentierungsmetriken.
    • In einer Entwicklungsumgebung wird die AlwaysOnSampler verwendet, um alle Ablaufverfolgungen anzuzeigen.
    • Ablaufverfolgungsdetails für ASP.NET Core, gRPC und HTTP-Instrumentierung.
  • Fügt OpenTelemetry Exporter hinzu, indem AddOpenTelemetryExportersaufgerufen wird.

Die AddOpenTelemetryExporters-Methode wird privat wie folgt definiert:

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

Die AddOpenTelemetryExporters-Methode fügt OpenTelemetry Exporter basierend auf den folgenden Bedingungen hinzu:

  • Wenn die OTEL_EXPORTER_OTLP_ENDPOINT Umgebungsvariable festgelegt ist, wird der OpenTelemetry Exporter hinzugefügt.
  • Optional können Consumer von .NET Aspire Dienststandard die Kommentare aufheben, um den Prometheus-Exporter oder den Azure Monitor-Exporter zu aktivieren.

Weitere Informationen finden Sie unter .NET.NET Aspire Telemetrie-.

Konfiguration der Integritätsprüfungen

Integritätsprüfungen werden von verschiedenen Tools und Systemen verwendet, um die Bereitschaft Ihrer App zu bewerten. .NET .NET Aspire stellt eine Reihe von meinungsvermerkten Standardwerten für Integritätsprüfungen bereit, die mit der AddDefaultHealthChecks-Methode konfiguriert sind:

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

Die AddDefaultHealthChecks-Methode fügt eine Standardmäßige Liveness-Prüfung hinzu, um sicherzustellen, dass die App reaktionsfähig ist. Der Aufruf von AddHealthChecks registriert die HealthCheckService. Weitere Informationen finden Sie unter .NET.NET Aspire Integritätsprüfungen.

Konfiguration der Web App-Integritätsprüfungen

Um Integritätsprüfungen in einer Web-App verfügbar zu machen, bestimmt .NET.NET Aspire automatisch den Typ des Projekts, auf das innerhalb der Lösung verwiesen wird, und fügt den entsprechenden Aufruf zu MapDefaultEndpointshinzu:

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

Die MapDefaultEndpoints-Methode:

  • Ermöglicht es Consumern, die Kommentare optional aufzuheben, um den Prometheus-Endpunkt zu aktivieren.
  • Ordnet den Endpunkt für Integritätsprüfungen /healthzu.
  • Ordnet den Livenessendpunkt /alive Route zu, auf der das Integritätsprüfungstag liveenthält.

Weitere Informationen finden Sie unter .NET.NET Aspire Integritätsprüfungen.

Standardeinstellungen für benutzerdefinierte Dienste

Wenn die von der Projektvorlage bereitgestellte Standarddienstkonfiguration für Ihre Anforderungen nicht ausreicht, haben Sie die Möglichkeit, Ihr eigenes Dienststandardprojekt zu erstellen. Dies ist besonders nützlich, wenn Ihr Projekt, z. B. ein Worker-Projekt oder winForms-Projekt, keine FrameworkReference Abhängigkeit von Microsoft.AspNetCore.Apphaben soll.

Erstellen Sie hierzu ein neues .NET 9.0-Klassenbibliotheksprojekt, und fügen Sie der Projektdatei die erforderlichen Abhängigkeiten hinzu, beachten Sie das folgende Beispiel:

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

Erstellen Sie dann eine Erweiterungsklasse, die die erforderlichen Methoden zum Konfigurieren der App-Standardwerte enthält:

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

Dies ist nur ein Beispiel, und Sie können die AppDefaultsExtensions Klasse an Ihre spezifischen Anforderungen anpassen.

Nächste Schritte

Dieser Code wird von der Vorlage .NET.NET Aspire Startanwendung abgeleitet und ist als Ausgangspunkt vorgesehen. Sie können diesen Code frei ändern, aber Sie sind für notwendig, um Ihre Anforderungen zu erfüllen. Es ist wichtig zu wissen, dass das Standardprojekt des Diensts und seine Funktionalität automatisch auf alle Projektressourcen in einer .NET.NET Aspire Lösung angewendet werden.