Freigeben über

Umgebungsmetadaten der Anwendung

Das Microsoft.Extensions.AmbientMetadata.Application NuGet-Paket bietet Funktionen zum Erfassen und Fließen von Umgebungsmetadaten auf Anwendungsebene in der gesamten Anwendung. Diese Metadaten umfassen Informationen wie Anwendungsname, Version, Bereitstellungsumgebung und Bereitstellungsring, was für die Erweiterung von Telemetrie, Problembehandlung und Analyse nützlich ist.

Gründe für die Verwendung von Anwendungsmetadaten

Anwendungsmetadaten bieten einen wesentlichen Kontext zu Ihrer ausgeführten Anwendung, die die Observierbarkeit verbessern kann:

  • Telemetrieanreicherung: Fügen Sie Anwendungsdetails automatisch zu Protokollen, Metriken und Ablaufverfolgungen hinzu.
  • Problembehandlung: Identifizieren Sie schnell, welche Version Ihrer Anwendung Probleme hat.
  • Umgebungsidentifikation: Unterscheiden Sie zwischen verschiedenen Umgebungen in Ihrer Telemetrie.
  • Nachverfolgung der Bereitstellung: Nachverfolgen von Problemen über verschiedene Bereitstellungsringe oder Regionen hinweg.
  • Konsistente Metadaten: Stellen Sie sicher, dass alle Komponenten in Ihrer Anwendung dieselben Metadatenwerte verwenden.

Installiere das Paket

Installieren Sie zunächst das 📦 Paket "Microsoft.Extensions.AmbientMetadata.Application NuGet":

dotnet add package Microsoft.Extensions.AmbientMetadata.Application

Oder, wenn Sie .NET 10+ SDK verwenden:

dotnet package add Microsoft.Extensions.AmbientMetadata.Application

Konfigurieren von Anwendungsmetadaten

Anwendungsmetadaten können über das Konfigurationssystem Ihrer Anwendung konfiguriert werden. Das Paket sucht standardmäßig nach Metadaten im ambientmetadata:application Konfigurationsabschnitt.

Konfigurieren mit appsettings.json

Fügen Sie der appsettings.json-Datei die Anwendungsmetadaten hinzu:

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

Konfigurieren mit IHostBuilder

Verwenden Sie die UseApplicationMetadata-Erweiterungsmethode, um Anwendungsmetadaten zu registrieren, bei der ApplicationName- und EnvironmentName-Werte automatisch aus IHostEnvironment ausgefüllt werden. Optional können Sie Werte für BuildVersion und DeploymentRing über die appsettings.json Datei bereitstellen.

Die folgende Tabelle zeigt die vom Anbieter zur Verfügung gestellten Metadaten über IConfiguration:

Key Erforderlich? Woher der Wert stammt Wertbeispiel Description
ambientmetadata:application:applicationname ja automatisch von IHostEnvironment myApp Der Anwendungsname.
ambientmetadata:application:environmentname ja automatisch von IHostEnvironment Production, Development Die Umgebung, in der die Anwendung bereitgestellt wird.
ambientmetadata:application:buildversion nein konfiguriere es in IConfiguration 1.0.0-rc1 Die Buildversion der Anwendung.
ambientmetadata:application:deploymentring nein konfiguriere es in IConfiguration r0, public Der Bereitstellungsring, von dem aus die Anwendung ausgeführt wird. 
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;

Alternativ können Sie dasselbe Ergebnis wie oben erzielen:

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;

Ihr appsettings.json kann einen Abschnitt wie folgt haben:

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

Konfigurieren mit IHostApplicationBuilder

Für Anwendungen, die Folgendes verwenden 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;

Ihr appsettings.json kann einen Abschnitt wie folgt haben:

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

Access-Anwendungsmetadaten

Nach der Konfiguration können Sie den ApplicationMetadata Typ einfügen und verwenden:

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

Die ApplicationMetadata Klasse enthält die folgenden Eigenschaften:

Eigentum Description
ApplicationName Der Name der Anwendung.
BuildVersion Die Version des Anwendungsbuilds.
DeploymentRing Der Bereitstellungsring oder die Phase (z. B. Canary, Produktion).
EnvironmentName Die Umgebung, in der die Anwendung ausgeführt wird (z. B. Entwicklung, Staging, Produktion).

Verwendung mit Protokollierung

Anwendungsmetadaten eignen sich besonders zum Anreichern von Protokollnachrichten:

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

Abschnitt "Benutzerdefinierte Konfiguration"

Wenn Sie einen anderen Konfigurationsabschnittsnamen verwenden möchten, geben Sie ihn beim Aufrufen UseApplicationMetadata<TBuilder>(TBuilder, String)an:

using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

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

var host = builder.Build();

await host.RunAsync();

Mit dieser Konfiguration würden Ihre Einstellungen wie folgt aussehen:

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