Partager via

valeurs par défaut du service .NET.NET Aspire

  • Article

Dans cet article, vous allez découvrir le projet .NET.NET Aspire service par défaut, un ensemble de méthodes d’extension qui :

Les applications natives cloud nécessitent souvent des configurations étendues pour s’assurer qu’elles fonctionnent dans différents environnements de manière fiable et sécurisée. .NET Aspire fournit de nombreuses méthodes et outils d’assistance pour simplifier la gestion des configurations pour OpenTelemetry, les contrôles d’intégrité, les variables d’environnement, etc.

Explorer le projet par défaut du service

Lorsque vous inscrit dans .NET.NET Aspire d’orchestration ou créez un projet .NET.NET Aspire, le projet YourAppName.ServiceDefaults.csproj est ajouté à votre solution. Par exemple, lors de la création d’une API, vous appelez la méthode AddServiceDefaults dans le fichier Program.cs de vos applications :

builder.AddServiceDefaults();

La méthode AddServiceDefaults gère les tâches suivantes :

  • Configure OpenTelemetry métriques et le suivi.
  • Ajoute des points de terminaison de contrôle d’intégrité par défaut.
  • Ajoute la fonctionnalité de découverte de service.
  • Configure HttpClient pour utiliser la découverte de service.

Pour plus d’informations, consultez méthodes d’extension fournies pour plus d’informations sur la méthode AddServiceDefaults.

Important

Le projet de .NET.NET Aspire service par défaut est spécifiquement conçu pour partager le fichier Extensions.cs et ses fonctionnalités. N’incluez pas d’autres fonctionnalités ou modèles partagés dans ce projet. Utilisez un projet de bibliothèque de classes partagées conventionnelle à ces fins.

Caractéristiques du projet

Le projet YourAppName.ServiceDefaults est une bibliothèque .NET 9.0 qui contient le code XML suivant :

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

Le modèle de projet par défaut du service impose une dépendance FrameworkReference sur Microsoft.AspNetCore.App.

Pourboire

Si vous ne souhaitez pas prendre de dépendance sur Microsoft.AspNetCore.App, vous pouvez créer un projet de service personnalisé par défaut. Pour plus d’informations, consultez de service personnalisé par défaut.

La propriété IsAspireSharedProject est définie sur true, ce qui indique que ce projet est un projet partagé. L’outil .NET Aspire utilise ce projet comme référence pour d’autres projets ajoutés à une solution .NET Aspire. Lorsque vous inscrivez le nouveau projet pour l’orchestration, il référence automatiquement le projet YourAppName.ServiceDefaults et met à jour le fichier Program.cs pour appeler la méthode AddServiceDefaults.

Méthodes d’extension fournies

Le projet YourAppName.ServiceDefaults expose un fichier Extensions.cs unique qui contient plusieurs méthodes d’extension avisées :

  • AddServiceDefaults: ajoute la fonctionnalité par défaut du service.
  • ConfigureOpenTelemetry: configure les métriques et le suivi OpenTelemetry.
  • AddDefaultHealthChecks: ajoute des points de terminaison de contrôle d’intégrité par défaut.
  • MapDefaultEndpoints: mappe le point de terminaison de contrôle d’intégrité à /health et le point de terminaison liveness à /alive.

Ajouter des fonctionnalités par défaut de service

La méthode AddServiceDefaults définit les configurations par défaut avec les fonctionnalités avisées suivantes :

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

Code précédent :

  • Configure OpenTelemetry métriques et le suivi, en appelant la méthode ConfigureOpenTelemetry.
  • Ajoute des points de terminaison de contrôle d’intégrité par défaut en appelant la méthode AddDefaultHealthChecks.
  • Ajoute fonctionnalité de découverte de service en appelant la méthode AddServiceDiscovery.
  • Configure HttpClient valeurs par défaut, en appelant la méthode ConfigureHttpClientDefaults, basée sur Générer des applications HTTP résilientes : modèles de développement clés:
    • Ajoute le gestionnaire de résilience HTTP standard en appelant la méthode AddStandardResilienceHandler.
    • Spécifie que le IHttpClientBuilder doit utiliser la découverte de service en appelant la méthode UseServiceDiscovery.
  • Retourne l’instance IHostApplicationBuilder pour autoriser le chaînage de méthodes.

configuration de OpenTelemetry

La télémétrie est une partie essentielle de n’importe quelle application native cloud. .NET Aspire fournit un ensemble de valeurs par défaut avisées pour OpenTelemetry, qui sont configurées avec la méthode 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;
}

Méthode ConfigureOpenTelemetry :

  • Ajoute .NET.NET Aspire journalisation des données de télémétrie pour inclure des messages et des étendues mis en forme.
  • Ajoute OpenTelemetry métriques et le suivi qui incluent :
    • Métriques d’instrumentation du runtime.
    • ASP.NET Core métriques d’instrumentation.
    • Métriques d’instrumentation HttpClient.
    • Dans un environnement de développement, le AlwaysOnSampler est utilisé pour afficher toutes les traces.
    • Détails du suivi des ASP.NET Core, gRPC et instrumentation HTTP.
  • Ajoute OpenTelemetry exportateurs, en appelant AddOpenTelemetryExporters.

La méthode AddOpenTelemetryExporters est définie en privé comme suit :

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

La méthode AddOpenTelemetryExporters ajoute OpenTelemetry exportateurs en fonction des conditions suivantes :

  • Si la variable d’environnement OTEL_EXPORTER_OTLP_ENDPOINT est définie, l’exportateur OpenTelemetry est ajouté.
  • Si vous le souhaitez, les consommateurs de .NET Aspire service par défaut peuvent annuler les marques de commentaire pour activer l’exportateur Prometheus ou l’exportateur Azure Monitor.

Pour plus d’informations, consultez .NET.NET Aspirede télémétrie .

Configuration des contrôles d’intégrité

Les contrôles d’intégrité sont utilisés par différents outils et systèmes pour évaluer la préparation de votre application. .NET .NET Aspire fournit un ensemble de valeurs par défaut avisées pour les vérifications d’intégrité, qui sont configurées avec la méthode 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;
}

La méthode AddDefaultHealthChecks ajoute un contrôle d’intégrité dynamique par défaut pour vous assurer que l’application est réactive. L’appel à AddHealthChecks inscrit le HealthCheckService. Pour plus d’informations, consultez .NET.NET Aspire vérifications d’intégrité.

Configuration des contrôles d’intégrité de l’application web

Pour exposer les vérifications d’intégrité dans une application web, .NET.NET Aspire détermine automatiquement le type de projet référencé dans la solution et ajoute l’appel approprié à 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;
}

Méthode MapDefaultEndpoints :

  • Permet aux consommateurs de supprimer éventuellement les marques de commentaire d’un code pour activer le point de terminaison Prometheus.
  • Mappe le point de terminaison de contrôle d’intégrité à /health.
  • Mappe le point de terminaison liveness à /alive route où la balise de contrôle d’intégrité contient live.

Pour plus d’informations, consultez .NET.NET Aspire vérifications d’intégrité.

Valeurs par défaut du service personnalisé

Si la configuration de service par défaut fournie par le modèle de projet n’est pas suffisante pour vos besoins, vous avez la possibilité de créer votre propre projet de service par défaut. Cela est particulièrement utile lorsque votre projet consommateur, tel qu’un projet Worker ou un projet WinForms, ne peut pas ou ne souhaite pas avoir de dépendance FrameworkReference sur Microsoft.AspNetCore.App.

Pour ce faire, créez un projet de bibliothèque de classes .NET 9.0 et ajoutez les dépendances nécessaires au fichier projet, prenons l’exemple suivant :

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

Créez ensuite une classe d’extensions qui contient les méthodes nécessaires pour configurer les valeurs par défaut de l’application :

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

Il s’agit uniquement d’un exemple, et vous pouvez personnaliser la classe AppDefaultsExtensions pour répondre à vos besoins spécifiques.

Étapes suivantes

Ce code est dérivé du modèle d’application de démarrage .NET.NET Aspire et est conçu comme point de départ. Vous êtes libre de modifier ce code, mais vous estimez nécessaire pour répondre à vos besoins. Il est important de savoir que le projet par défaut du service et ses fonctionnalités sont automatiquement appliqués à toutes les ressources de projet dans une solution .NET.NET Aspire.