Aracılığıyla paylaş

hizmet varsayılanlarını .NET.NET Aspire

  • Makale

Bu makalede, aşağıdaki uzantı yöntemleri kümesi olan .NET.NET Aspire hizmeti varsayılanları projesi hakkında bilgi ediniyorsunuz:

  • telemetribağlayın sistem durumu denetimleri hizmet bulma uygulamanıza.
  • Özelleştirilebilir ve genişletilebilir.

Buluta özel uygulamalar genellikle farklı ortamlarda güvenilir ve güvenli bir şekilde çalıştıklarından emin olmak için kapsamlı yapılandırmalar gerektirir. .NET Aspire, OpenTelemetry, sistem durumu denetimleri, ortam değişkenleri ve daha fazlası için yapılandırmaların yönetimini kolaylaştırmak için birçok yardımcı yöntem ve araç sağlar.

Hizmet varsayılanları projesini keşfetme

düzenleme Listele'yi veya yeni bir projesi oluşturduğunuzda çözümünüzde YourAppName.ServiceDefaults.csproj projesi eklenir. Örneğin, BIR API oluştururken, uygulamalarınızın AddServiceDefaults dosyasında Program.cs yöntemini çağırırsınız:

builder.AddServiceDefaults();

AddServiceDefaults yöntemi aşağıdaki görevleri işler:

  • OpenTelemetry ölçümlerini ve izlemeyi yapılandırıyor.
  • Varsayılan sistem durumu denetimi uç noktalarını ekler.
  • Hizmet bulma işlevselliği ekler.
  • HttpClient hizmet bulma ile çalışacak şekilde yapılandırılır.

Daha fazla bilgi için yöntemiyle ilgili ayrıntılar için bkz. AddServiceDefaults.

Önemli

.NET .NET Aspire hizmeti varsayılanları projesi, Extensions.cs dosyasını ve işlevselliğini paylaşmak için özel olarak tasarlanmıştır. Bu projeye diğer paylaşılan işlevleri veya modelleri eklemeyin. Bu amaçlar için geleneksel bir paylaşılan sınıf kitaplığı projesi kullanın.

Proje özellikleri

YourAppName.ServiceDefaults projesi , aşağıdaki XML'yi içeren bir 9.0 kitaplığıdır:

<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.3.0" />
    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.1.0" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.11.2" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.11.2" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.11.1" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.11.1" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.11.1" />
  </ItemGroup>

</Project>

Hizmet, proje şablonunu varsayılan olarak FrameworkReferenceMicrosoft.AspNetCore.App bağımlılığı uygular.

Bahşiş

Microsoft.AspNetCore.Appbağımlılığını almak istemiyorsanız, özel hizmet varsayılanları projesi oluşturabilirsiniz. Daha fazla bilgi için bkz. Özel hizmet varsayılanları.

IsAspireSharedProject özelliği, bu projenin paylaşılan bir proje olduğunu gösteren trueolarak ayarlanır. .NET Aspire araçları, bir .NET Aspire çözümüne eklenen diğer projeler için başvuru olarak bu projeyi kullanır. Yeni projeyi düzenleme için kaydettiğinizde, proje otomatik olarak YourAppName.ServiceDefaults başvurur ve dosyasını yöntemini çağıracak şekilde güncelleştirir.

Sağlanan uzantı yöntemleri

YourAppName.ServiceDefaults projesinin çeşitli fikirli uzantı yöntemleri içeren tek bir Extensions.cs dosyası kullanıma sunar:

  • AddServiceDefaults: Hizmet varsayılanları işlevselliğini ekler.
  • ConfigureOpenTelemetry: OpenTelemetry ölçümleri ve izlemeyi yapılandırılır.
  • AddDefaultHealthChecks: Varsayılan sistem durumu denetimi uç noktalarını ekler.
  • MapDefaultEndpoints: Sistem durumu denetimleri uç noktasını /health ve canlılık uç noktasını /aliveile eşler.

Hizmet varsayılanları işlevselliği ekleme

AddServiceDefaults yöntemi, varsayılan yapılandırmaları aşağıdaki düşünceli işlevlerle tanımlar:

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

Önceki kod:

  • OpenTelemetry yöntemini çağırarak ConfigureOpenTelemetry ölçümleri ve izlemeyi yapılandırılır.
  • AddDefaultHealthChecks yöntemini çağırarak varsayılan sistem durumu denetimi uç noktalarını ekler.
  • yöntemini çağırarak AddServiceDiscovery işlevselliğini ekler.
  • HttpClient yöntemini çağırarak ConfigureHttpClientDefaults varsayılanlarını yapılandıran Dayanıklı HTTP uygulamaları oluşturma: Temel geliştirme desenleri: :
    • AddStandardResilienceHandler yöntemini çağırarak standart HTTP dayanıklılığı işleyicisini ekler.
    • IHttpClientBuilder yöntemini çağırarak UseServiceDiscovery hizmet bulma kullanması gerektiğini belirtir.
  • Yöntem zincirine izin vermek için IHostApplicationBuilder örneğini döndürür.

OpenTelemetry yapılandırması

Telemetri, buluta özel tüm uygulamaların kritik bir parçasıdır. .NET Aspire, OpenTelemetry yöntemiyle yapılandırılan ConfigureOpenTelemetryiçin bir dizi varsayılan değer sağlar:

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 yöntemi:

  • Biçimlendirilmiş iletileri ve kapsamları içerecek şekilde .NET.NET Aspire telemetri günlüğe kaydeder.
  • Aşağıdakileri içeren OpenTelemetry ölçümler ve izleme ekler:
    • Çalışma zamanı izleme ölçümleri.
    • İzleme ölçümlerini ASP.NET Core.
    • HttpClient izleme ölçümleri.
    • Geliştirme ortamında, tüm izlemeleri görüntülemek için AlwaysOnSampler kullanılır.
    • ASP.NET Core, gRPC ve HTTP izleme için izleme ayrıntıları.
  • OpenTelemetryçağırarak AddOpenTelemetryExporters verenleri ekler.

AddOpenTelemetryExporters yöntemi aşağıdaki gibi özel olarak tanımlanır:

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 yöntemi, aşağıdaki koşullara göre OpenTelemetry verenleri ekler:

  • OTEL_EXPORTER_OTLP_ENDPOINT ortam değişkeni ayarlanırsa, OpenTelemetry veren eklenir.
  • İsteğe bağlı olarak, .NET Aspire hizmet varsayılanlarının tüketicileri Prometheus ihracatçısını veya Azure İzleyici vermecisini etkinleştirmek için bazı kodların açıklamasını açabilir.

Daha fazla bilgi için bkz. telemetri.

Sistem durumu denetimleri yapılandırması

Sistem durumu denetimleri, uygulamanızın hazır olma durumunu değerlendirmek için çeşitli araçlar ve sistemler tarafından kullanılır. .NET .NET Aspire, sistem durumu denetimleri için AddDefaultHealthChecks yöntemiyle yapılandırılan bir dizi fikirli varsayılan sağlar:

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 yöntemi, uygulamanın duyarlı olduğundan emin olmak için varsayılan bir canlılık denetimi ekler. AddHealthChecks çağrısı HealthCheckServicekaydeder. Daha fazla bilgi için bkz. sistem durumu denetimleri.

Web uygulaması sistem durumu denetimleri yapılandırması

Bir web uygulamasında sistem durumu denetimlerini kullanıma açmak için .NET.NET Aspire çözüm içinde başvurulmakta olan projenin türünü otomatik olarak belirler ve MapDefaultEndpointsuygun çağrıyı ekler:

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 yöntemi:

  • Tüketicilerin Prometheus uç noktasını etkinleştirmek için isteğe bağlı olarak bazı kodları açıklamadan kaldırmasına olanak tanır.
  • Sistem durumu denetimleri uç noktasını /healthile eşler.
  • Canlılık uç noktasını, sistem durumu denetimi etiketinin /aliveiçerdiği live rotaya eşler.

Daha fazla bilgi için bkz. sistem durumu denetimleri.

Özel hizmet varsayılanları

Proje şablonu tarafından sağlanan varsayılan hizmet yapılandırması gereksinimleriniz için yeterli değilse, kendi hizmet varsayılanları projenizi oluşturma seçeneğiniz vardır. Bu, özellikle çalışan projesi veya WinForms projesi gibi tüketen projeniz FrameworkReferenceMicrosoft.AspNetCore.App bağımlılığına sahip olamaz veya istemezse yararlıdır.

Bunu yapmak için yeni bir .NET 9.0 sınıf kitaplığı projesi oluşturun ve proje dosyasına gerekli bağımlılıkları ekleyin, aşağıdaki örneği göz önünde bulundurun:

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

Ardından uygulama varsayılanlarını yapılandırmak için gerekli yöntemleri içeren bir uzantı sınıfı oluşturun:

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

Bu yalnızca bir örnektir ve AppDefaultsExtensions sınıfını özel gereksinimlerinizi karşılayacak şekilde özelleştirebilirsiniz.

Sonraki adımlar

Bu kod, .NET.NET Aspire Starter Uygulaması şablonundan türetilir ve başlangıç noktası olarak tasarlanmıştır. Gereksinimlerinizi karşılamak için gerekli olduğunu kabul ettiğiniz şekilde bu kodu değiştirebilirsiniz. Hizmet varsayılanlarının proje ve işlevselliğinin bir .NET.NET Aspire çözümündeki tüm proje kaynaklarına otomatik olarak uygulandığını bilmek önemlidir.