Omgevingsmetagegevens van toepassingen

Het Microsoft.Extensions.AmbientMetadata.Application NuGet-pakket biedt functionaliteit voor het vastleggen en stromen van omgevingsmetagegevens op toepassingsniveau in uw toepassing. Deze metagegevens bevatten informatie zoals de toepassingsnaam, versie, implementatieomgeving en implementatiering, wat waardevol is voor het verrijken van telemetrie, probleemoplossing en analyse.

Waarom metagegevens van toepassingen gebruiken

Toepassingsmetagegevens bieden essentiële context over uw actieve toepassing die de waarneembaarheid kan verbeteren:

  • Telemetrieverrijking: voeg automatisch toepassingsgegevens toe aan logboeken, metrische gegevens en traceringen.
  • Probleemoplossing: Identificeer snel welke versie van uw toepassing problemen ondervindt.
  • Omgevingsidentificatie: Onderscheid maken tussen verschillende omgevingen in uw telemetrie.
  • Implementatietracering: houd problemen bij in verschillende implementatieringen of regio's.
  • Consistente metagegevens: zorg ervoor dat alle onderdelen in uw toepassing dezelfde metagegevenswaarden gebruiken.

Installeer het pakket

Installeer het NuGet-pakket Microsoft.Extensions.AmbientMetadata.Application NuGet om aan de📦 slag te gaan:

dotnet add package Microsoft.Extensions.AmbientMetadata.Application

Of als u .NET 10+ SDK gebruikt:

dotnet package add Microsoft.Extensions.AmbientMetadata.Application

Toepassingsmetagegevens configureren

Toepassingsmetagegevens kunnen worden geconfigureerd via het configuratiesysteem van uw toepassing. Het pakket zoekt standaard naar metagegevens in de ambientmetadata:application configuratiesectie.

Configureren met appsettings.json

Voeg de metagegevens van de toepassing toe aan uw appsettings.json bestand:

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

Configureren met IHostBuilder

Gebruik de UseApplicationMetadata uitbreidingsmethode om metagegevens van toepassingen te registreren, waarmee ApplicationName- en EnvironmentName-waarden automatisch worden ingevuld vanaf IHostEnvironment. U kunt eventueel waarden voor BuildVersion en DeploymentRing via het appsettings.json bestand opgeven.

In de volgende tabel ziet u de metagegevens die door de provider beschikbaar worden gesteld via IConfiguration:

Key Vereist? Waar de waarde vandaan komt Voorbeeld van waarde Description
ambientmetadata:application:applicationname yes automatisch van IHostEnvironment myApp De naam van de toepassing.
ambientmetadata:application:environmentname yes automatisch van IHostEnvironment Production, Development De omgeving waar de toepassing naar wordt geïmplementeerd.
ambientmetadata:application:buildversion no configureren in IConfiguration 1.0.0-rc1 De buildversie van de toepassing.
ambientmetadata:application:deploymentring no configureren in IConfiguration r0, public De implementatiering van waaruit de toepassing wordt uitgevoerd. 
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;

U kunt ook hetzelfde resultaat bereiken als hierboven:

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;

U appsettings.json kunt als volgt een sectie hebben:

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

Configureren met IHostApplicationBuilder

Voor toepassingen die gebruikmaken van 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;

U appsettings.json kunt als volgt een sectie hebben:

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

Toegang tot toepassingsmetagegevens

Zodra dit is geconfigureerd, kunt u het ApplicationMetadata type injecteren en gebruiken:

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

De ApplicationMetadata klasse bevat de volgende eigenschappen:

Vastgoed Description
ApplicationName De naam van de toepassing.
BuildVersion De buildversie van de applicatie.
DeploymentRing De uitrolring of fase (bijvoorbeeld Canary, productie).
EnvironmentName De omgeving waarin de toepassing wordt uitgevoerd (bijvoorbeeld Ontwikkeling, Fasering, Productie).

Gebruiken met logboekregistratie

Toepassingsmetagegevens zijn met name handig voor het verrijken van logboekberichten:

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

Aangepaste configuratiesectie

Als u liever een andere configuratiesectienaam gebruikt, geeft u deze op bij het aanroepen 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();

Met deze configuratie zien uw instellingen er als volgt uit:

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