standardvärden för .NET.NET Aspire-tjänsten
I den här artikeln får du lära dig mer om standardprojektet .NET.NET Aspire tjänsten, en uppsättning tilläggsmetoder som:
- Anslut telemetri, hälsokontroller, tjänstidentifiering till din app.
- Är anpassningsbara och utökningsbara.
Molnbaserade program kräver ofta omfattande konfigurationer för att säkerställa att de fungerar i olika miljöer på ett tillförlitligt och säkert sätt. .NET Aspire innehåller många hjälpmetoder och verktyg för att effektivisera hanteringen av konfigurationer för OpenTelemetry, hälsokontroller, miljövariabler med mera.
Utforska standardprojektet för tjänsten
När du antingen Enlist i .NET.NET Aspire orchestration eller skapa ett nytt .NET.NET Aspire projektläggs YourAppName.ServiceDefaults.csproj-projektet till i din lösning. När du till exempel skapar ett API anropar du metoden AddServiceDefaults
i Program.cs-filen för dina appar:
builder.AddServiceDefaults();
Metoden AddServiceDefaults
hanterar följande uppgifter:
- Konfigurerar OpenTelemetry mått och spårning.
- Lägger till standardslutpunkter för hälsokontroll.
- Lägger till funktioner för tjänstidentifiering.
- Konfigurerar HttpClient att fungera med tjänstidentifiering.
Mer information finns i Tillhandahållna tilläggsmetoder för mer information om metoden AddServiceDefaults
.
Viktig
Standardprojektet för .NET.NET Aspire-tjänsten är särskilt utformat för att dela Extensions.cs-filen och dess funktioner. Inkludera inte andra delade funktioner eller modeller i det här projektet. Använd ett konventionellt biblioteksprojekt för delad klass för dessa ändamål.
Projektegenskaper
projektet YourAppName.ServiceDefaults är ett .NET 9.0-bibliotek som innehåller följande 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.1.0" />
<PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.0.0" />
<PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.11.1" />
<PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.11.1" />
<PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.11.0" />
<PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.11.0" />
<PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.11.0" />
</ItemGroup>
</Project>
Standardprojektmallen för tjänsten medför ett FrameworkReference
beroende av Microsoft.AspNetCore.App
.
Dricks
Om du inte vill vara beroende av Microsoft.AspNetCore.App
kan du skapa ett standardprojekt för anpassade tjänster. Mer information finns i custom service defaults.
Egenskapen IsAspireSharedProject
är inställd på true
, vilket anger att det här projektet är ett delat projekt. Verktyget .NET Aspire använder det här projektet som referens för andra projekt som lagts till i en .NET Aspire lösning. När du registrerar det nya projektet för orkestrering refererar det automatiskt till projektet YourAppName.ServiceDefaults och uppdaterar Program.cs-filen för att anropa metoden AddServiceDefaults
.
Tillhandahållna tilläggsmetoder
Projektet YourAppName.ServiceDefaults exponerar en enda Extensions.cs fil som innehåller flera metoder för åsiktstillägg:
-
AddServiceDefaults
: Lägger till standardfunktioner för tjänsten. -
ConfigureOpenTelemetry
: Konfigurerar OpenTelemetry mått och spårning. -
AddDefaultHealthChecks
: Lägger till standardslutpunkter för hälsokontroll. -
MapDefaultEndpoints
: Mappar slutpunkten för hälsokontroller till/health
och slutpunkten för liveness till/alive
.
Lägg till standardfunktioner för tjänsten
Metoden AddServiceDefaults
definierar standardkonfigurationer med följande åsiktsfunktioner:
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;
}
Föregående kod:
- Konfigurerar OpenTelemetry mått och spårning genom att anropa metoden
ConfigureOpenTelemetry
. - Lägger till standardslutpunkter för hälsokontroll genom att anropa metoden
AddDefaultHealthChecks
. - Lägger till tjänstidentifiering funktioner genom att anropa metoden
AddServiceDiscovery
. - Konfigurerar HttpClient standardvärden genom att anropa metoden
ConfigureHttpClientDefaults
– som baseras på Skapa motståndskraftiga HTTP-appar: Viktiga utvecklingsmönster:- Lägger till standardhanteraren för HTTP-motståndskraft genom att anropa metoden
AddStandardResilienceHandler
. - Anger att IHttpClientBuilder ska använda tjänstidentifiering genom att anropa metoden
UseServiceDiscovery
.
- Lägger till standardhanteraren för HTTP-motståndskraft genom att anropa metoden
- Returnerar den
IHostApplicationBuilder
instansen för att tillåta metodlänkning.
OpenTelemetry konfiguration
Telemetri är en viktig del av alla molnbaserade program.
.NET Aspire innehåller en uppsättning åsiktsstandarder för OpenTelemetry, som konfigureras med metoden 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;
}
Metoden ConfigureOpenTelemetry
:
- Lägger till .NET.NET Aspire telemetri loggning för att inkludera formaterade meddelanden och omfång.
- Lägger till OpenTelemetry mått och spårning som omfattar:
- Mått för körningsinstrumentation.
- ASP.NET Core instrumentationsmått.
- HttpClient-instrumentationsmått.
- I en utvecklingsmiljö används
AlwaysOnSampler
för att visa alla spårningar. - Spårningsinformation för ASP.NET Core, gRPC- och HTTP-instrumentation.
- Lägger till OpenTelemetry exportörer genom att anropa
AddOpenTelemetryExporters
.
Metoden AddOpenTelemetryExporters
definieras privat enligt följande:
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;
}
Metoden AddOpenTelemetryExporters
lägger till OpenTelemetry exportörer baserat på följande villkor:
- Om
OTEL_EXPORTER_OTLP_ENDPOINT
miljövariabeln anges läggs OpenTelemetry-exportören till. - Alternativt kan användare av .NET Aspire tjänststandarder avkommentera viss kod för att aktivera Prometheus-exportören eller Azure Monitor-exportören.
Mer information finns i .NET.NET Aspire telemetri.
Konfiguration av hälsokontroller
Hälsokontroller används av olika verktyg och system för att utvärdera appens beredskap.
.NET
.NET Aspire tillhandahåller en uppsättning åsiktsmässiga standardvärden för hälsokontroller som konfigureras med metoden 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;
}
Metoden AddDefaultHealthChecks
lägger till en standardkontroll för liveness för att säkerställa att appen svarar. Anropet till AddHealthChecks registrerar HealthCheckService. Mer information finns i .NET.NET Aspire hälsokontroller.
Konfiguration av hälsokontroller för webbappar
Om du vill exponera hälsokontroller i en webbapp avgör .NET.NET Aspire automatiskt vilken typ av projekt som refereras i lösningen och lägger till lämpligt anrop till 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;
}
Metoden MapDefaultEndpoints
:
- Gör att konsumenter kan avkommentera viss kod för att aktivera Prometheus-slutpunkten.
- Mappar slutpunkten för hälsokontroller till
/health
. - Mappar liveness-slutpunkten till
/alive
väg där hälsokontrolltaggen innehållerlive
.
Mer information finns i .NET.NET Aspire hälsokontroller.
Standardinställningar för anpassad tjänst
Om standardtjänstkonfigurationen som tillhandahålls av projektmallen inte räcker för dina behov kan du skapa ett eget standardprojekt för tjänsten. Detta är särskilt användbart när ditt förbrukande projekt, till exempel ett Worker-projekt eller WinForms-projekt, inte kan eller inte vill ha ett FrameworkReference
beroende av Microsoft.AspNetCore.App
.
Det gör du genom att skapa ett nytt .NET 9.0-klassbiblioteksprojekt och lägga till nödvändiga beroenden i projektfilen. Tänk på följande exempel:
<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>
Skapa sedan en tilläggsklass som innehåller de metoder som krävs för att konfigurera appens standardvärden:
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;
}
}
Det här är bara ett exempel och du kan anpassa klassen AppDefaultsExtensions
efter dina specifika behov.
Nästa steg
Den här koden härleds från mallen .NET.NET Aspire Starter-program och är avsedd som en startpunkt. Du kan ändra den här koden, men du anser att den är nödvändig för att uppfylla dina behov. Det är viktigt att veta att tjänstens standardprojekt och dess funktioner tillämpas automatiskt på alla projektresurser i en .NET.NET Aspire lösning.
.NET Aspire