Compartir a través de

valores predeterminados del servicio .NET.NET Aspire

  • Artículo

En este artículo, obtendrá información sobre el proyecto predeterminado del servicio .NET.NET Aspire, un conjunto de métodos de extensión que:

  • Conecte de telemetría , comprobaciones de estado, de detección de servicios a la aplicación.
  • Son personalizables y extensibles.

Las aplicaciones nativas de la nube suelen requerir configuraciones extensas para asegurarse de que funcionan en distintos entornos de forma confiable y segura. .NET Aspire proporciona muchos métodos auxiliares y herramientas para simplificar la administración de configuraciones para OpenTelemetry, comprobaciones de estado, variables de entorno, etc.

Exploración del proyecto predeterminado del servicio

Al inscribirse en de orquestación o crear un nuevo proyecto de , se agrega el proyecto YourAppName.ServiceDefaults.csproj a la solución. Por ejemplo, al compilar una API, se llama al método AddServiceDefaults en el archivo Program.cs de las aplicaciones:

builder.AddServiceDefaults();

El método AddServiceDefaults controla las siguientes tareas:

  • Configura OpenTelemetry métricas y seguimiento.
  • Agrega puntos de conexión de comprobación de estado predeterminados.
  • Agrega la funcionalidad de detección de servicios.
  • Configura HttpClient para trabajar con la detección de servicios.

Para obtener más información, consulte Métodos de extensión proporcionados para obtener más información sobre el método AddServiceDefaults.

Importante

El proyecto predeterminado del servicio .NET.NET Aspire está diseñado específicamente para compartir el archivo Extensions.cs y su funcionalidad. No incluya otras funciones o modelos compartidos en este proyecto. Use un proyecto de biblioteca de clases compartida convencional para esos fines.

Características del proyecto

El proyecto YourAppName.ServiceDefaults es una biblioteca de .NET 9.0 que contiene el siguiente 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>

La plantilla de proyecto predeterminada del servicio impone una dependencia de FrameworkReference en Microsoft.AspNetCore.App.

Propina

Si no desea tomar una dependencia de Microsoft.AspNetCore.App, puede crear un proyecto predeterminado de servicio personalizado. Para obtener más información, consulte valores predeterminados del servicio personalizado.

La propiedad IsAspireSharedProject se establece en true, lo que indica que este proyecto es un proyecto compartido. Las herramientas de .NET Aspire usan este proyecto como referencia para otros proyectos agregados a una solución de .NET Aspire. Al inscribir el nuevo proyecto para la orquestación, hace referencia automáticamente al proyecto YourAppName.ServiceDefaults y actualiza el archivo Program.cs para llamar al método AddServiceDefaults.

Métodos de extensión proporcionados

El proyecto YourAppName.ServiceDefaults expone un único archivo Extensions.cs que contiene varios métodos de extensión con opiniones:

  • AddServiceDefaults: agrega la funcionalidad predeterminada del servicio.
  • ConfigureOpenTelemetry: configura las métricas y el seguimiento de OpenTelemetry.
  • AddDefaultHealthChecks: agrega puntos de conexión de comprobación de estado predeterminados.
  • MapDefaultEndpoints: asigna el punto de conexión de comprobaciones de estado a /health y el punto de conexión de ejecución a /alive.

Adición de la funcionalidad predeterminada del servicio

El método AddServiceDefaults define configuraciones predeterminadas con la siguiente funcionalidad con opiniones:

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

El código anterior:

  • Configura OpenTelemetry métricas y seguimiento mediante una llamada al método ConfigureOpenTelemetry.
  • Agrega puntos de conexión de comprobación de estado predeterminados mediante una llamada al método AddDefaultHealthChecks.
  • Agrega funcionalidad de de detección de servicios mediante una llamada al método AddServiceDiscovery.
  • Configura HttpClient valores predeterminados mediante una llamada al método ConfigureHttpClientDefaults , que se basa en Crear aplicaciones HTTP resistentes: patrones de desarrollo de claves:
    • Agrega el controlador de resistencia HTTP estándar mediante una llamada al método AddStandardResilienceHandler.
    • Especifica que el IHttpClientBuilder debe usar la detección de servicios mediante una llamada al método UseServiceDiscovery.
  • Devuelve la instancia de IHostApplicationBuilder para permitir el encadenamiento de métodos.

configuración de OpenTelemetry

La telemetría es una parte fundamental de cualquier aplicación nativa de la nube. .NET Aspire proporciona un conjunto de valores predeterminados con opiniones para OpenTelemetry, que se configuran con el método 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étodo ConfigureOpenTelemetry:

  • Agrega .NET.NET Aspire registro de telemetría para incluir los ámbitos y los mensajes con formato.
  • Agrega OpenTelemetry métricas y seguimiento que incluyen:
    • Métricas de instrumentación en tiempo de ejecución.
    • ASP.NET Core métricas de instrumentación.
    • Métricas de instrumentación httpClient.
    • En un entorno de desarrollo, el AlwaysOnSampler se usa para ver todos los seguimientos.
    • Detalles de seguimiento de ASP.NET Core, gRPC e instrumentación HTTP.
  • Agrega OpenTelemetry exportadores mediante una llamada a AddOpenTelemetryExporters.

El método AddOpenTelemetryExporters se define de forma privada de la siguiente manera:

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

El método AddOpenTelemetryExporters agrega OpenTelemetry exportadores en función de las condiciones siguientes:

  • Si se establece la variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT, se agrega el OpenTelemetry exportador.
  • Opcionalmente, los consumidores de los valores predeterminados del servicio .NET Aspire pueden quitar la marca de comentario de código para habilitar el exportador de Prometheus o el exportador de Azure Monitor.

Para obtener más información, consulte .NET.NET Aspire telemetría.

Configuración de comprobaciones de estado

Las comprobaciones de estado las usan varias herramientas y sistemas para evaluar la preparación de la aplicación. .NET .NET Aspire proporciona un conjunto de valores predeterminados con opiniones para las comprobaciones de estado, que se configuran con el método 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;
}

El método AddDefaultHealthChecks agrega una comprobación de ejecución predeterminada para asegurarse de que la aplicación responde. La llamada a AddHealthChecks registra el HealthCheckService. Para obtener más información, consulte .NET.NET Aspire comprobaciones de estado.

Configuración de comprobaciones de estado de aplicaciones web

Para exponer comprobaciones de estado en una aplicación web, .NET.NET Aspire determina automáticamente el tipo de proyecto al que se hace referencia dentro de la solución y agrega la llamada adecuada a 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étodo MapDefaultEndpoints:

  • Permite a los consumidores quitar la marca de comentario opcional de código para habilitar el punto de conexión de Prometheus.
  • Asigna el punto de conexión de comprobaciones de estado a /health.
  • Asigna el punto de conexión de ejecución a /alive ruta donde la etiqueta de comprobación de estado contiene live.

Para obtener más información, consulte .NET.NET Aspire comprobaciones de estado.

Valores predeterminados del servicio personalizado

Si la configuración de servicio predeterminada proporcionada por la plantilla de proyecto no es suficiente para sus necesidades, tiene la opción de crear su propio proyecto de valores predeterminados de servicio. Esto resulta especialmente útil cuando el proyecto de consumo, como un proyecto de trabajo o un proyecto de WinForms, no puede o no desea tener una dependencia de FrameworkReference en Microsoft.AspNetCore.App.

Para ello, cree un nuevo proyecto de biblioteca de clases de .NET 9.0 y agregue las dependencias necesarias al archivo de proyecto, considere el ejemplo siguiente:

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

A continuación, cree una clase de extensiones que contenga los métodos necesarios para configurar los valores predeterminados de la aplicación:

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

Este es solo un ejemplo y puede personalizar la clase AppDefaultsExtensions para satisfacer sus necesidades específicas.

Pasos siguientes

Este código se deriva de la plantilla aplicación de inicio de .NET.NET Aspire y está pensada como punto de partida. Sin embargo, tiene la libertad de modificar este código para satisfacer sus necesidades. Es importante saber que el proyecto predeterminado del servicio y su funcionalidad se aplican automáticamente a todos los recursos del proyecto en una solución de .NET.NET Aspire.