.NET .NET Aspire default layanan
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 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
<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
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
.
- Menambahkan handler ketahanan HTTP standar, dengan memanggil metode
- 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 berisilive
.
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.
- penemuan Layanan di .NET.NET Aspire
- SDK
- templat
- Pemeriksaan kesehatan di .NET.NET Aspire
- telemetri
- Membangun aplikasi HTTP tangguh: Pola pengembangan utama
.NET Aspire