.NET .NET Aspire 서비스 기본값

아티클
12/14/2024

이 문서에서는 .NET.NET Aspire 서비스 기본 프로젝트인 확장 메서드 집합에 대해 알아봅니다.

원격 분석, 상태 검사, 서비스 검색 앱에 연결합니다.
사용자 지정 가능하고 확장할 수 있습니다.

클라우드 네이티브 애플리케이션은 여러 환경에서 안정적이고 안전하게 작동하도록 하기 위해 광범위한 구성이 필요한 경우가 많습니다. .NET Aspire OpenTelemetry, 상태 검사, 환경 변수 등에 대한 구성 관리를 간소화하는 많은 도우미 메서드와 도구를 제공합니다.

서비스 기본 프로젝트 탐색

오케스트레이션 참여하거나 새 프로젝트만들 경우 YourAppName.ServiceDefaults.csproj 프로젝트가 솔루션에 추가됩니다. 예를 들어 API를 빌드할 때 앱의 Program.cs 파일에서 AddServiceDefaults 메서드를 호출합니다.

builder.AddServiceDefaults();

AddServiceDefaults 메서드는 다음 작업을 처리합니다.

OpenTelemetry 메트릭 및 추적을 구성합니다.
기본 상태 검사 엔드포인트를 추가합니다.
서비스 검색 기능을 추가합니다.
서비스 검색을 사용하도록 HttpClient 구성합니다.

자세한 내용은 AddServiceDefaults 메서드에 대한 자세한 내용은 제공된 확장 메서드를 참조하세요.

중요하다

.NET .NET Aspire 서비스 기본 프로젝트는 Extensions.cs 파일 및 해당 기능을 공유하도록 특별히 설계되었습니다. 이 프로젝트에 다른 공유 기능이나 모델을 포함하지 마세요. 이러한 용도로 기존 공유 클래스 라이브러리 프로젝트를 사용합니다.

프로젝트 특성

YourAppName.ServiceDefaults 프로젝트는 다음 XML을 포함하는 .NET 9.0 라이브러리입니다.

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

서비스 기본값 프로젝트 템플릿은 Microsoft.AspNetCore.AppFrameworkReference 종속성을 적용합니다.

팁

Microsoft.AspNetCore.App종속성을 사용하지 않으려면 사용자 지정 서비스 기본 프로젝트를 만들 수 있습니다. 자세한 내용은 사용자 지정 서비스 기본값참조하세요.

IsAspireSharedProject 속성은 이 프로젝트가 공유 프로젝트임을 나타내는 true설정됩니다. .NET Aspire 도구는 이 프로젝트를 .NET Aspire 솔루션에 추가된 다른 프로젝트에 대한 참조로 사용합니다. 오케스트레이션을 위해 새 프로젝트를 등록하면 YourAppName.ServiceDefaults 프로젝트를 자동으로 참조하고 AddServiceDefaults 메서드를 호출하도록 Program.cs 파일을 업데이트합니다.

제공된 확장 메서드

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

앞의 코드는 다음과 같습니다.

ConfigureOpenTelemetry 메서드를 호출하여 OpenTelemetry 메트릭 및 추적을 구성합니다.
AddDefaultHealthChecks 메서드를 호출하여 기본 상태 검사 엔드포인트를 추가합니다.
AddServiceDiscovery 메서드를 호출하여 서비스 검색 기능을 추가합니다.
빌드 복원력 HTTP 앱을 기반으로 하는 ConfigureHttpClientDefaults 메서드를 호출하여 HttpClient 기본값을 구성합니다.주요 개발 패턴은 다음과 같습니다.
- AddStandardResilienceHandler 메서드를 호출하여 표준 HTTP 복원력 처리기를 추가합니다.
- IHttpClientBuilder UseServiceDiscovery 메서드를 호출하여 서비스 검색을 사용하도록 지정합니다.
메서드 체인을 허용하는 IHostApplicationBuilder 인스턴스를 반환합니다.

OpenTelemetry 구성

원격 분석은 클라우드 네이티브 애플리케이션의 중요한 부분입니다. .NET Aspire ConfigureOpenTelemetry 메서드로 구성된 OpenTelemetry대한 의견 있는 기본값 집합을 제공합니다.

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 계측에 대한 추적 세부 정보입니다.
AddOpenTelemetryExporters호출하여 OpenTelemetry 내보내기를 추가합니다.

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 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매핑합니다.
상태 검사 태그에 live포함된 /alive 경로에 활동성 엔드포인트를 매핑합니다.

자세한 내용은 .NET.NET Aspire 상태 검사참조하세요.

사용자 지정 서비스 기본값

프로젝트 템플릿에서 제공하는 기본 서비스 구성이 요구 사항에 충분하지 않은 경우 사용자 고유의 서비스 기본 프로젝트 만들기 옵션이 있습니다. 이는 작업자 프로젝트 또는 WinForms 프로젝트와 같은 소비 프로젝트가 Microsoft.AspNetCore.App대한 FrameworkReference 종속성을 가질 수 없거나 사용하지 않으려는 경우에 특히 유용합니다.

이렇게 하려면 새 .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 솔루션의 모든 프로젝트 리소스에 자동으로 적용된다는 것을 알아야 합니다.

서비스 검색
.NET .NET Aspire SDK
템플릿
상태 검사
.NET .NET Aspire 원격 분석
복원력 있는 HTTP 앱 빌드 : 주요 개발 패턴

다음을 통해 공유