Metadane otoczenia aplikacji

Microsoft.Extensions.AmbientMetadata.Application Pakiet NuGet udostępnia funkcje przechwytywania i przepływu metadanych otoczenia na poziomie aplikacji w całej aplikacji. Te metadane zawierają informacje, takie jak nazwa aplikacji, wersja, środowisko wdrażania i pierścień wdrażania, które są przydatne do wzbogacania danych telemetrycznych, rozwiązywania problemów i analizy.

Dlaczego warto używać metadanych aplikacji

Metadane aplikacji zapewniają podstawowy kontekst dotyczący uruchomionej aplikacji, który może zwiększyć czytelność:

• Wzbogacanie telemetrii: automatycznie dodaj szczegóły aplikacji do dzienników, metryk i śladów.
• Rozwiązywanie problemów: Szybko zidentyfikuj, która wersja aplikacji ma problemy.
• Identyfikacja środowiska: rozróżnianie różnych środowisk w telemetrii.
• Śledzenie wdrożenia: śledzenie problemów między różnymi pierścieniami wdrożenia lub regionami.
• Spójne metadane: Upewnij się, że wszystkie składniki w aplikacji używają tych samych wartości metadanych.

Instalowanie pakietu

Aby rozpocząć, zainstaluj 📦 pakiet NuGet Microsoft.Extensions.AmbientMetadata.Application :

dotnet add package Microsoft.Extensions.AmbientMetadata.Application

dotnet package add Microsoft.Extensions.AmbientMetadata.Application

<PackageReference Include="Microsoft.Extensions.AmbientMetadata.Application"
                  Version="*" /> <!-- Adjust version -->

Konfigurowanie metadanych aplikacji

Metadane aplikacji można skonfigurować za pomocą systemu konfiguracji aplikacji. Pakiet domyślnie wyszukuje metadane w ambientmetadata:application sekcji konfiguracji.

Konfigurowanie przy użyciu appsettings.json

Dodaj metadane aplikacji do pliku appsettings.json :

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

Konfigurowanie za pomocą programu IHostBuilder

Użyj metody rozszerzeń UseApplicationMetadata, aby zarejestrować metadane aplikacji, co automatycznie wypełnia wartości ApplicationName i EnvironmentName z IHostEnvironment. Opcjonalnie możesz podać wartości dla BuildVersion oraz DeploymentRing za pośrednictwem pliku appsettings.json.

W poniższej tabeli przedstawiono metadane udostępniane przez dostawcę za pośrednictwem usługi IConfiguration:

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;

Alternatywnie możesz osiągnąć ten sam wynik co powyżej, wykonując następujące czynności:

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;

Sekcja appsettings.json może być następująca:

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

Konfigurowanie za pomocą IHostApplicationBuilder

W przypadku aplikacji korzystających z funkcji 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;

Sekcja appsettings.json może być następująca:

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

Uzyskiwanie dostępu do metadanych aplikacji

Po skonfigurowaniu można wstrzyknąć i użyć typu 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();

Właściwości AplikacjaMetadata

Klasa ApplicationMetadata zawiera następujące właściwości:

Użyj z logowaniem

Metadane aplikacji są szczególnie przydatne podczas wzbogacania komunikatów dziennika:

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

Sekcja konfiguracji niestandardowej

Jeśli wolisz użyć innej nazwy sekcji konfiguracji, określ ją podczas wywoływania polecenia 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();

W przypadku tej konfiguracji ustawienia będą wyglądać następująco:

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