Condividi tramite

Metadati di ambiente dell'applicazione

Il Microsoft.Extensions.AmbientMetadata.Application pacchetto NuGet offre funzionalità per acquisire e scorrere i metadati di ambiente a livello di applicazione in tutta l'applicazione. Questi metadati includono informazioni quali il nome dell'applicazione, la versione, l'ambiente di distribuzione e l'anello di distribuzione, utili per arricchire i dati di telemetria, la risoluzione dei problemi e l'analisi.

Perché usare i metadati dell'applicazione

I metadati dell'applicazione forniscono un contesto essenziale sull'applicazione in esecuzione che può migliorare l'osservabilità:

  • Arricchimento dei dati di telemetria: aggiungere automaticamente i dettagli dell'applicazione ai log, alle metriche e alle tracce.
  • Risoluzione dei problemi: identificare rapidamente la versione dell'applicazione che riscontra problemi.
  • Identificazione dell'ambiente: distinguere tra ambienti diversi nei dati di telemetria.
  • Rilevamento della distribuzione: tenere traccia dei problemi in diversi anelli di distribuzione o aree geografiche.
  • Metadati coerenti: assicurarsi che tutti i componenti dell'applicazione usino gli stessi valori di metadati.

Installare il pacchetto

Per iniziare, installare il 📦 pacchetto NuGet Microsoft.Extensions.AmbientMetadata.Application :

dotnet add package Microsoft.Extensions.AmbientMetadata.Application

Oppure, se stai utilizzando il SDK di .NET 10+

dotnet package add Microsoft.Extensions.AmbientMetadata.Application

Configurare i metadati dell'applicazione

I metadati dell'applicazione possono essere configurati tramite il sistema di configurazione dell'applicazione. Il pacchetto cerca i metadati nella ambientmetadata:application sezione di configurazione per impostazione predefinita.

Configurare con appsettings.json

Aggiungere i metadati dell'applicazione al appsettings.json file:

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

Configurare con IHostBuilder

Usare il metodo delle estensioni UseApplicationMetadata per registrare i metadati dell'applicazione, che popolano automaticamente i valori ApplicationName da EnvironmentName. Facoltativamente, è possibile specificare i valori per BuildVersion e DeploymentRing tramite il appsettings.json file .

La tabella seguente illustra i metadati resi disponibili dal provider tramite IConfiguration:

Key Obbligatorio? Da dove proviene il valore Esempio di valore Description
ambientmetadata:application:applicationname yes automaticamente da IHostEnvironment myApp Nome dell'applicazione.
ambientmetadata:application:environmentname yes automaticamente da IHostEnvironment Production, Development L'ambiente in cui viene distribuita l'applicazione.
ambientmetadata:application:buildversion no Configurare nel IConfiguration 1.0.0-rc1 Versione di compilazione dell'applicazione.
ambientmetadata:application:deploymentring no Configurare nel IConfiguration r0, public Anello di distribuzione da cui è in esecuzione l'applicazione. 
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;

In alternativa, è possibile ottenere lo stesso risultato ottenuto in precedenza eseguendo questa operazione:

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;

È possibile che il tuo appsettings.json abbia una sezione come segue:

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

Configurare con IHostApplicationBuilder

Per le applicazioni che usano 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;

È possibile che il tuo appsettings.json abbia una sezione come segue:

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

Accedere ai metadati dell'applicazione

Dopo la configurazione, è possibile inserire e usare il ApplicationMetadata tipo :

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

Proprietà di metadati dell'applicazione

La ApplicationMetadata classe include le proprietà seguenti:

Proprietà Description
ApplicationName Nome dell'applicazione.
BuildVersion Versione di build dell'applicazione.
DeploymentRing L'anello di distribuzione o la fase (ad esempio "Canary", "Production").
EnvironmentName Ambiente in cui è in esecuzione l'applicazione, ad esempio Sviluppo, Gestione temporanea, Produzione.

Usare con la registrazione

I metadati dell'applicazione sono particolarmente utili per arricchire i messaggi di log:

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

Sezione configurazione personalizzata

Se si preferisce usare un nome di sezione di configurazione diverso, specificarlo quando si chiama 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();

Con questa configurazione, le impostazioni sono simili alle seguenti:

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