Поделиться через

.NET .NET Aspire службы по умолчанию

  • Статья

В этой статье вы узнаете о проекте по умолчанию службы .NET.NET Aspire набор методов расширения, которые:

  • Подключите телеметриипроверки работоспособностиобнаружения служб к приложению.
  • Настраиваемая и расширяемая.

Облачные приложения часто требуют обширных конфигураций, чтобы обеспечить их работу в разных средах надежно и безопасно. .NET Aspire предоставляет множество вспомогательных методов и средств для упрощения управления конфигурациями для OpenTelemetry, проверок работоспособности, переменных среды и т. д.

Изучение проекта по умолчанию службы

При перечислении в .NET.NET Aspire оркестрации или созданияпроекта .NET.NET Aspire в решение добавляется проект YourAppName.ServiceDefaults.csproj. Например, при создании API вызывается метод AddServiceDefaults в файле Program.cs приложений:

builder.AddServiceDefaults();

Метод AddServiceDefaults обрабатывает следующие задачи:

  • Настраивает OpenTelemetry метрики и трассировку.
  • Добавляет конечные точки проверки работоспособности по умолчанию.
  • Добавляет функции обнаружения служб.
  • Настраивает HttpClient для работы с обнаружением служб.

Дополнительные сведения см. в разделе Предоставленные методы расширения подробные сведения о методе AddServiceDefaults.

Важный

Проект службы .NET.NET Aspire по умолчанию предназначен специально для совместного использования файла Extensions.cs и его функциональных возможностей. Не включайте в этот проект другие общие функции или модели. Используйте обычный проект библиотеки общих классов для этих целей.

Характеристики проекта

Проект YourAppName.ServiceDefaults — это библиотека 9.0, содержащая следующий 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>

Шаблон проекта по умолчанию службы накладывает FrameworkReference зависимость от Microsoft.AspNetCore.App.

Кончик

Если вы не хотите использовать зависимость от Microsoft.AspNetCore.App, можно создать проект по умолчанию для пользовательской службы. Дополнительные сведения см. в разделе Пользовательские службы по умолчанию.

Свойство IsAspireSharedProject имеет значение true, указывающее, что этот проект является общим проектом. Средство .NET Aspire использует этот проект в качестве ссылки для других проектов, добавленных в решение .NET Aspire. При включении нового проекта для оркестрации он автоматически ссылается на проект YourAppName.ServiceDefaults и обновляет файл Program.cs для вызова метода AddServiceDefaults.

Предоставленные методы расширения

Проект YourAppName.ServiceDefaults предоставляет один файл Extensions.cs, содержащий несколько методов расширения с мнением:

  • AddServiceDefaults: добавляет функции по умолчанию службы.
  • ConfigureOpenTelemetry: настраивает метрики и трассировку OpenTelemetry.
  • AddDefaultHealthChecks: добавляет конечные точки проверки работоспособности по умолчанию.
  • MapDefaultEndpoints: сопоставляет конечную точку проверки работоспособности /health и конечную точку активности с /alive.

Добавление функций службы по умолчанию

Метод AddServiceDefaults определяет конфигурации по умолчанию со следующими функциональными возможностями:

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

Предыдущий код:

  • Настраивает OpenTelemetry метрики и трассировку, вызывая метод ConfigureOpenTelemetry.
  • Добавляет конечные точки проверки работоспособности по умолчанию, вызвав метод AddDefaultHealthChecks.
  • Добавляет функции обнаружения службы путем вызова метода AddServiceDiscovery.
  • Настраивает HttpClient по умолчанию путем вызова метода ConfigureHttpClientDefaults, основанного на сборке устойчивых HTTP-приложений: ключевые шаблоны разработки:
    • Добавляет стандартный обработчик устойчивости HTTP, вызвав метод AddStandardResilienceHandler.
    • Указывает, что IHttpClientBuilder должен использовать обнаружение служб, вызвав метод UseServiceDiscovery.
  • Возвращает экземпляр IHostApplicationBuilder, чтобы разрешить цепочку методов.

конфигурация OpenTelemetry

Телеметрия является важной частью любого облачного приложения. .NET Aspire предоставляет набор значений по умолчанию для OpenTelemetry, настроенных с помощью метода 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;
}

Метод ConfigureOpenTelemetry:

  • Добавляет .NET.NET Aspire журнал телеметрии для включения форматированных сообщений и областей.
  • Добавляет OpenTelemetry метрики и трассировку, которые включают:
    • Метрики инструментирования среды выполнения.
    • ASP.NET Core метрики инструментирования.
    • Метрики инструментирования HttpClient.
    • В среде разработки AlwaysOnSampler используется для просмотра всех трассировок.
    • Сведения о трассировке для ASP.NET Core, инструментирования gRPC и HTTP.
  • Добавляет OpenTelemetry экспортеров, вызывая AddOpenTelemetryExporters.

Метод AddOpenTelemetryExporters определяется в частном порядке следующим образом:

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

Метод AddOpenTelemetryExporters добавляет OpenTelemetry экспортеров на основе следующих условий:

  • Если задана переменная среды OTEL_EXPORTER_OTLP_ENDPOINT, добавляется экспортер OpenTelemetry.
  • При необходимости потребители служб .NET Aspire по умолчанию могут раскомментировать некоторый код, чтобы включить экспортер Prometheus или экспортер Azure Monitor.

Дополнительные сведения см. в .NET.NET Aspireтелеметрии.

Конфигурация проверки работоспособности

Проверки работоспособности используются различными средствами и системами для оценки готовности приложения. .NET .NET Aspire предоставляет набор по умолчанию для проверок работоспособности, настроенных с помощью метода 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;
}

Метод AddDefaultHealthChecks добавляет проверку активности по умолчанию, чтобы убедиться, что приложение реагирует. Вызов AddHealthChecks регистрирует HealthCheckService. Дополнительные сведения см. в разделе .NET.NET Aspire проверки работоспособности.

Конфигурация проверки работоспособности веб-приложения

Чтобы предоставить проверку работоспособности в веб-приложении, .NET.NET Aspire автоматически определяет тип проекта, на который ссылается решение, и добавляет соответствующий вызов к 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;
}

Метод MapDefaultEndpoints:

  • Позволяет потребителям дополнительно раскомментировать некоторый код, чтобы включить конечную точку Prometheus.
  • Сопоставляет конечную точку проверки работоспособности с /health.
  • Сопоставляет конечную точку liveness с /alive маршрутом, где тег проверки работоспособности содержит live.

Дополнительные сведения см. в разделе .NET.NET Aspire проверки работоспособности.

Пользовательские службы по умолчанию

Если для ваших потребностей недостаточно конфигурации службы по умолчанию, предоставленной шаблоном проекта, можно создать собственный проект по умолчанию службы. Это особенно полезно, если используемый проект, например рабочий проект или проект WinForms, не может или не хочет иметь FrameworkReference зависимости от Microsoft.AspNetCore.App.

Для этого создайте проект библиотеки классов .NET 9.0 и добавьте необходимые зависимости в файл проекта, рассмотрим следующий пример:

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

Затем создайте класс расширений, содержащий необходимые методы для настройки приложений по умолчанию:

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

Это только пример, и вы можете настроить класс AppDefaultsExtensions в соответствии с конкретными потребностями.

Дальнейшие действия

Этот код является производным от шаблона начального приложения .NET.NET Aspire и предназначен в качестве отправной точки. Вы можете изменить этот код, однако вы считаете необходимым для удовлетворения ваших потребностей. Важно знать, что проект по умолчанию службы и ее функциональные возможности автоматически применяются ко всем ресурсам проекта в решении .NET.NET Aspire.