Programmets omgivande metadata

Microsoft.Extensions.AmbientMetadata.Application NuGet-paketet innehåller funktioner för att samla in och flöda omgivande metadata på programnivå i hela programmet. Dessa metadata innehåller information som programnamn, version, distributionsmiljö och distributionsring, vilket är värdefullt för att berika telemetri, felsökning och analys.

Varför använda applikationsmetadata

Programmetadata ger en viktig kontext om ditt program som körs och som kan förbättra observerbarheten:

  • Telemetriberikning: Lägg automatiskt till programinformation i loggar, mått och spårningar.
  • Felsökning: Identifiera snabbt vilken version av programmet som har problem.
  • Miljöidentifiering: Skilja mellan olika miljöer i telemetrin.
  • Distributionsspårning: Spåra problem i olika distributionsringar eller regioner.
  • Konsekventa metadata: Se till att alla komponenter i programmet använder samma metadatavärden.

Installera paketet

Kom igång genom att 📦 installera NuGet-paketet Microsoft.Extensions.AmbientMetadata.Application :

dotnet add package Microsoft.Extensions.AmbientMetadata.Application

Eller om du använder .NET 10+ SDK:

dotnet package add Microsoft.Extensions.AmbientMetadata.Application

Konfigurera applikationsmetadata

Programmetadata kan konfigureras via programmets konfigurationssystem. Paketet söker efter metadata under konfigurationsavsnittet ambientmetadata:application som standard.

Konfigurera med appsettings.json

Lägg till applikationsmetadata i appsettings.json-filen:

{
  "ambientmetadata": {
    "application": {
      "ApplicationName": "MyWebApi",
      "BuildVersion": "1.0.0",
      "DeploymentRing": "Production",
      "EnvironmentName": "Production"
    }
  }
}

Konfigurera med IHostBuilder

Använd UseApplicationMetadata-tilläggsmetoden för att registrera programmetadata, som automatiskt fyller i ApplicationName och EnvironmentName-värden från IHostEnvironment. Du kan också ange värden för BuildVersion och DeploymentRing via appsettings.json filen.

I följande tabell visas de metadata som tillhandahålls av providern via IConfiguration:

Key Krävs? Var värdet kommer ifrån Värdeexempel Description
ambientmetadata:application:applicationname yes automatiskt från IHostEnvironment myApp Ansökningsnamnet.
ambientmetadata:application:environmentname yes automatiskt från IHostEnvironment Production, Development Miljön som programmet distribueras till.
ambientmetadata:application:buildversion no konfigurera den i IConfiguration 1.0.0-rc1 Programmets byggversion.
ambientmetadata:application:deploymentring no konfigurera den i IConfiguration r0, public Distributionsringen från vilken programmet körs. 
var builder = Host.CreateDefaultBuilder(args)
    // ApplicationName and EnvironmentName will be imported from `IHostEnvironment`.
    // BuildVersion and DeploymentRing will be imported from the "appsettings.json" file.
builder.UseApplicationMetadata();

var host = builder.Build();
await host.StartAsync();

var metadataOptions = host.Services.GetRequiredService<IOptions<ApplicationMetadata>>();
var buildVersion = metadataOptions.Value.BuildVersion;

Du kan också uppnå samma resultat som ovan genom att göra följande:

var builder = Host.CreateApplicationBuilder()
    .ConfigureAppConfiguration(static (context, builder) =>
        builder.AddApplicationMetadata(context.HostingEnvironment));
builder.Services.AddApplicationMetadata(
    builder.Configuration.GetSection("ambientmetadata:application")));
var host = builder.Build();

var metadataOptions = host.Services.GetRequiredService<IOptions<ApplicationMetadata>>();
var buildVersion = metadataOptions.Value.BuildVersion;

Ditt appsettings.json kan ha ett avsnitt som följer:

"AmbientMetadata": {
    "Application": {
        "DeploymentRing": "testring",
        "BuildVersion": "1.2.3"
    }
}

Konfigurera med IHostApplicationBuilder

För program som använder IHostApplicationBuilder:

var builder = Host.CreateApplicationBuilder(args)
    // ApplicationName and EnvironmentName will be imported from `IHostEnvironment`.
    // BuildVersion and DeploymentRing will be imported from the "appsettings.json" file.
builder.UseApplicationMetadata();

var host = builder.Build();
await host.StartAsync();

var metadataOptions = host.Services.GetRequiredService<IOptions<ApplicationMetadata>>();
var buildVersion = metadataOptions.Value.BuildVersion;

Ditt appsettings.json kan ha ett avsnitt som följer:

"AmbientMetadata": {
    "Application": {
        "DeploymentRing": "testring",
        "BuildVersion": "1.2.3"
    }
}

Komma åt programmetadata

När du har konfigurerat kan du mata in och använda typen ApplicationMetadata :

using Microsoft.Extensions.AmbientMetadata;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Options;

var builder = Host.CreateApplicationBuilder(args);
builder.UseApplicationMetadata();

var host = builder.Build();

var metadata = host.Services.GetRequiredService<IOptions<ApplicationMetadata>>().Value;
Console.WriteLine($"Application: {metadata.ApplicationName}");
Console.WriteLine($"Version: {metadata.BuildVersion}");
Console.WriteLine($"Environment: {metadata.EnvironmentName}");
Console.WriteLine($"Deployment Ring: {metadata.DeploymentRing}");
await host.RunAsync();

ApplicationMetadata-egenskaper

Klassen ApplicationMetadata innehåller följande egenskaper:

Fastighet Description
ApplicationName Namnet på applikationen.
BuildVersion Byggversionen av applikationen.
DeploymentRing Distributionsringen eller -fasen (till exempel Canary, Production).
EnvironmentName Miljön där programmet körs (till exempel Utveckling, Mellanlagring, Produktion).

Användning med loggning

Programmetadata är särskilt användbara för att utöka loggmeddelanden:

using Microsoft.Extensions.AmbientMetadata;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;

var builder = Host.CreateApplicationBuilder(args);

builder.UseApplicationMetadata();
builder.Services.AddSingleton<LoggingService>();

var host = builder.Build();

var loggingService = host.Services.GetRequiredService<LoggingService>();
loggingService.LogWithMetadata();

await host.RunAsync();

public class LoggingService(
    ILogger<LoggingService> logger,
    IOptions<ApplicationMetadata> metadata)
{
    private readonly ILogger<LoggingService> _logger = logger;
    private readonly ApplicationMetadata _metadata = metadata.Value;

    public void LogWithMetadata()
    {
        _logger.LogInformation(
            "Processing request in {ApplicationName} v{Version} ({Environment})",
            _metadata.ApplicationName,
            _metadata.BuildVersion,
            _metadata.EnvironmentName);
    }
}

Anpassad konfigurationssektion

Om du föredrar att använda ett annat namn på konfigurationsavsnittet anger du det när du anropar UseApplicationMetadata<TBuilder>(TBuilder, String):

using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

// Use custom configuration section
builder.UseApplicationMetadata("myapp:metadata");

var host = builder.Build();

await host.RunAsync();

Med den här konfigurationen skulle inställningarna se ut så här:

{
  "myapp": {
    "metadata": {
      "ApplicationName": "MyWebApi", // ApplicationName will be imported from `IHostEnvironment`.
      "BuildVersion": "1.0.0",
      "DeploymentRing": "Production",
      "EnvironmentName": "Production" // EnvironmentName will be imported from `IHostEnvironment`.
    }
  }
}
  • Last updated on