Metadados do ambiente do aplicativo

O Microsoft.Extensions.AmbientMetadata.Application pacote NuGet fornece funcionalidades para capturar e propagar metadados ao nível da aplicação em toda a aplicação. Esses metadados incluem informações como o nome do aplicativo, a versão, o ambiente de implantação e o anel de implantação, que são valiosos para enriquecer a telemetria, a solução de problemas e a análise.

Por que usar metadados de aplicativos

Os metadados do aplicativo fornecem um contexto essencial sobre seu aplicativo em execução que pode melhorar a observabilidade:

• Enriquecimento de telemetria: adicione automaticamente detalhes do aplicativo a logs, métricas e rastreamentos.
• Solução de problemas: identifique rapidamente qual versão do seu aplicativo está enfrentando problemas.
• Identificação do ambiente: distinga entre diferentes ambientes na sua telemetria.
• Acompanhamento de implantação: rastreie problemas em diferentes anéis ou regiões de implantação.
• Metadados consistentes: certifique-se de que todos os componentes em seu aplicativo usem os mesmos valores de metadados.

Instale o pacote

Para começar, instale o pacote NuGet Microsoft.Extensions.AmbientMetadata.Application📦:

dotnet add package Microsoft.Extensions.AmbientMetadata.Application

Ou, se você estiver usando o SDK do .NET 10+:

dotnet package add Microsoft.Extensions.AmbientMetadata.Application

PackageReference

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

Configurar metadados do aplicativo

Os metadados do aplicativo podem ser configurados através do sistema de configuração do seu aplicativo. O pacote procura metadados na ambientmetadata:application seção de configuração por padrão.

Configurar utilizando appsettings.json

Adicione os metadados do aplicativo ao seu appsettings.json arquivo:

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

Configurar com IHostBuilder

Use o método de extensões UseApplicationMetadata para registar os metadados da aplicação, que preenchem automaticamente os valores ApplicationName e EnvironmentName a partir de IHostEnvironment. Opcionalmente, você pode fornecer valores para BuildVersion e DeploymentRing através do appsettings.json arquivo.

A tabela a seguir mostra os metadados disponibilizados pelo provedor via IConfiguration:

Key	Necessário?	De onde vem o valor	Exemplo de valor	Description
ambientmetadata:application:applicationname	yes	automaticamente a partir de IHostEnvironment	myApp	O nome do aplicativo.
ambientmetadata:application:environmentname	yes	automaticamente a partir de IHostEnvironment	Production, Development	O ambiente no qual o aplicativo é implantado.
ambientmetadata:application:buildversion	no	configurá-lo em IConfiguration	1.0.0-rc1	A versão de compilação da aplicação.
ambientmetadata:application:deploymentring	no	configurá-lo em IConfiguration	r0, public	O anel de implantação em que a aplicação está a ser executada.

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;

Alternativamente, você pode obter o mesmo resultado acima, fazendo o seguinte:

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;

A sua appsettings.json pode ter uma secção da seguinte forma:

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

Configurar com IHostApplicationBuilder

Para aplicações que utilizem 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;

A sua appsettings.json pode ter uma secção da seguinte forma:

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

Acessar metadados do aplicativo

Uma vez configurado, você pode injetar e usar o 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();

Propriedades dos Metadados da Aplicação

A ApplicationMetadata classe inclui as seguintes propriedades:

Propriedade	Description
ApplicationName	O nome do aplicativo.
BuildVersion	A versão da compilação da aplicação.
DeploymentRing	O anel ou estágio de implantação (por exemplo, Canário, Produção).
EnvironmentName	O ambiente onde o aplicativo está sendo executado (por exemplo, Desenvolvimento, Preparo, Produção).

Utilização com registo

Os metadados do aplicativo são particularmente úteis para enriquecer mensagens de 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);
    }
}

Seção de configuração personalizada

Se preferir usar um nome de seção de configuração diferente, especifique-o ao chamar 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();

Com essa configuração, suas configurações ficariam assim:

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