Bagikan melalui

.NET .NET Aspire default layanan

  • Artikel

Dalam artikel ini, Anda mempelajari tentang proyek default layanan .NET.NET Aspire, sekumpulan metode ekstensi yang:

  • Sambungkantelemetri , pemeriksaan kesehatan, penemuan layanan ke aplikasi Anda.
  • Dapat disesuaikan dan dapat diperluas.

Aplikasi cloud-native sering kali memerlukan konfigurasi ekstensif untuk memastikannya bekerja di berbagai lingkungan dengan andal dan aman. .NET Aspire menyediakan banyak metode dan alat pembantu untuk menyederhanakan pengelolaan konfigurasi untuk OpenTelemetry, pemeriksaan kesehatan, variabel lingkungan, dan banyak lagi.

Menjelajahi proyek default layanan

Saat Anda Daftar dalam orkestrasi atau membuat proyek baru, proyek YourAppName.ServiceDefaults.csproj ditambahkan ke solusi Anda. Misalnya, saat membuat API, Anda memanggil metode AddServiceDefaults dalam file Program.cs aplikasi Anda:

builder.AddServiceDefaults();

Metode AddServiceDefaults menangani tugas-tugas berikut:

  • Mengonfigurasi metrik dan pelacakan OpenTelemetry.
  • Menambahkan titik akhir pemeriksaan kesehatan default.
  • Menambahkan fungsionalitas penemuan layanan.
  • Mengonfigurasi HttpClient untuk bekerja dengan penemuan layanan.

Untuk informasi selengkapnya, lihat metode ekstensi Disediakan untuk detail tentang metode AddServiceDefaults.

Penting

Proyek default layanan .NET.NET Aspire dirancang khusus untuk berbagi file Extensions.cs dan fungsionalitasnya. Jangan sertakan fungsionalitas atau model bersama lainnya dalam proyek ini. Gunakan proyek pustaka kelas bersama konvensional untuk tujuan tersebut.

Karakteristik proyek

Proyek YourAppName.ServiceDefaults adalah pustaka 9.0 yang berisi XML berikut:

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

Templat proyek default layanan memberlakukan dependensi FrameworkReference pada Microsoft.AspNetCore.App.

Ujung

Jika Anda tidak ingin mengambil dependensi pada Microsoft.AspNetCore.App, Anda dapat membuat proyek default layanan kustom. Untuk informasi selengkapnya, lihat default layanan kustom .

Properti IsAspireSharedProject diatur ke true, yang menunjukkan bahwa proyek ini adalah proyek bersama. Alat .NET Aspire menggunakan proyek ini sebagai referensi untuk proyek lain yang ditambahkan ke solusi .NET Aspire. Saat Anda mendaftarkan proyek baru untuk orkestrasi, proyek tersebut secara otomatis mereferensikan proyek YourAppName.ServiceDefaults dan memperbarui file untuk memanggil metode .

Metode ekstensi yang disediakan

Proyek YourAppName.ServiceDefaults mengekspos satu file Extensions.cs yang berisi beberapa metode ekstensi yang dipengaruhi:

  • AddServiceDefaults: Menambahkan fungsionalitas default layanan.
  • ConfigureOpenTelemetry: Mengonfigurasi metrik dan pelacakan OpenTelemetry.
  • AddDefaultHealthChecks: Menambahkan titik akhir pemeriksaan kesehatan default.
  • MapDefaultEndpoints: Memetakan titik akhir pemeriksaan kesehatan ke /health dan titik akhir keaktivitas ke /alive.

Menambahkan fungsionalitas default layanan

Metode AddServiceDefaults menentukan konfigurasi default dengan fungsionalitas berpendapat berikut:

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

Kode sebelumnya:

  • Mengonfigurasi metrik dan pelacakan OpenTelemetry, dengan memanggil metode ConfigureOpenTelemetry.
  • Menambahkan titik akhir pemeriksaan kesehatan default, dengan memanggil metode AddDefaultHealthChecks.
  • Menambahkan penemuan layanan fungsionalitas, dengan memanggil metode AddServiceDiscovery.
  • Mengonfigurasi default HttpClient, dengan memanggil metode ConfigureHttpClientDefaults—yang didasarkan pada Build aplikasi HTTP tangguh: Pola pengembangan utama:
    • Menambahkan handler ketahanan HTTP standar, dengan memanggil metode AddStandardResilienceHandler.
    • Menentukan bahwa IHttpClientBuilder harus menggunakan penemuan layanan, dengan memanggil metode UseServiceDiscovery.
  • Mengembalikan instans IHostApplicationBuilder untuk memungkinkan penautan metode.

konfigurasi OpenTelemetry

Telemetri adalah bagian penting dari aplikasi cloud-native apa pun. .NET Aspire menyediakan sekumpulan default berpendapat untuk OpenTelemetry, yang dikonfigurasi dengan metode 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;
}

Metode ConfigureOpenTelemetry:

  • Menambahkan .NET.NET Aspire pengelogan telemetri untuk menyertakan pesan dan cakupan yang diformat.
  • Menambahkan metrik OpenTelemetry dan pelacakan yang mencakup:
    • Metrik instrumentasi runtime.
    • ASP.NET Core metrik instrumentasi.
    • Metrik instrumentasi HttpClient.
    • Dalam lingkungan pengembangan, AlwaysOnSampler digunakan untuk melihat semua jejak.
    • Detail pelacakan untuk instrumentasi ASP.NET Core, gRPC, dan HTTP.
  • Menambahkan eksportir OpenTelemetry, dengan memanggil AddOpenTelemetryExporters.

Metode AddOpenTelemetryExporters didefinisikan secara privat sebagai berikut:

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

Metode AddOpenTelemetryExporters menambahkan pengekspor OpenTelemetry berdasarkan kondisi berikut:

  • Jika variabel lingkungan OTEL_EXPORTER_OTLP_ENDPOINT diatur, pengekspor OpenTelemetry ditambahkan.
  • Secara opsional konsumen default layanan .NET Aspire dapat membatalkan komentar beberapa kode untuk mengaktifkan pengekspor Prometheus, atau pengekspor Azure Monitor.

Untuk informasi selengkapnya, lihat .NET.NET Aspire telemetri.

Konfigurasi pemeriksaan kesehatan

Pemeriksaan kesehatan digunakan oleh berbagai alat dan sistem untuk menilai kesiapan aplikasi Anda. .NET .NET Aspire menyediakan serangkaian default berpendapat untuk pemeriksaan kesehatan, yang dikonfigurasi dengan metode 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;
}

Metode AddDefaultHealthChecks menambahkan pemeriksaan keaktifan default untuk memastikan aplikasi responsif. Panggilan ke AddHealthChecks mendaftarkan HealthCheckService. Untuk informasi selengkapnya, lihat .NET.NET Aspire pemeriksaan kesehatan.

Konfigurasi pemeriksaan kesehatan aplikasi web

Untuk mengekspos pemeriksaan kesehatan di aplikasi web, .NET.NET Aspire secara otomatis menentukan jenis proyek yang dirujuk dalam solusi, dan menambahkan panggilan yang sesuai ke 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;
}

Metode MapDefaultEndpoints:

  • Memungkinkan konsumen untuk secara opsional membatalkan komentar beberapa kode untuk mengaktifkan titik akhir Prometheus.
  • Memetakan titik akhir pemeriksaan kesehatan ke /health.
  • Memetakan titik akhir liveness ke rute /alive di mana tag pemeriksaan kesehatan berisi live.

Untuk informasi selengkapnya, lihat .NET.NET Aspire pemeriksaan kesehatan.

Default layanan kustom

Jika konfigurasi layanan default yang disediakan oleh templat proyek tidak cukup untuk kebutuhan Anda, Anda memiliki opsi untuk membuat proyek default layanan Anda sendiri. Ini sangat berguna ketika proyek konsumsi Anda, seperti proyek Pekerja atau proyek WinForms, tidak dapat atau tidak ingin memiliki dependensi FrameworkReference pada Microsoft.AspNetCore.App.

Untuk melakukan ini, buat proyek pustaka kelas .NET 9.0 baru dan tambahkan dependensi yang diperlukan ke file proyek, pertimbangkan contoh berikut:

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

Kemudian buat kelas ekstensi yang berisi metode yang diperlukan untuk mengonfigurasi default aplikasi:

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

Ini hanya contoh, dan Anda dapat menyesuaikan kelas AppDefaultsExtensions untuk memenuhi kebutuhan spesifik Anda.

Langkah berikutnya

Kode ini berasal dari templat Aplikasi Pemula .NET.NET Aspire dan dimaksudkan sebagai titik awal. Anda bebas untuk memodifikasi kode ini namun Anda dianggap perlu untuk memenuhi kebutuhan Anda. Penting untuk diketahui bahwa proyek default layanan dan fungsionalitasnya secara otomatis diterapkan ke semua sumber daya proyek dalam solusi .NET.NET Aspire.