Metadatos ambientales de la aplicación

El Microsoft.Extensions.AmbientMetadata.Application paquete NuGet proporciona funcionalidad para capturar y fluir metadatos ambientales de nivel de aplicación en toda la aplicación. Estos metadatos incluyen información como el nombre de la aplicación, la versión, el entorno de implementación y el anillo de implementación, que es útil para enriquecer la telemetría, la solución de problemas y el análisis.

¿Por qué usar metadatos de aplicación?

Los metadatos de la aplicación proporcionan un contexto esencial sobre la aplicación en ejecución que puede mejorar la observabilidad:

Enriquecimiento de telemetría: agregue automáticamente los detalles de la aplicación a los registros, las métricas y los seguimientos.
Solución de problemas: identifique rápidamente qué versión de la aplicación está experimentando problemas.
Identificación del entorno: distinga entre distintos entornos de la telemetría.
Seguimiento de la implementación: realice un seguimiento de los problemas en diferentes anillos de implementación o regiones.
Metadatos coherentes: asegúrese de que todos los componentes de la aplicación usan los mismos valores de metadatos.

Instalar el paquete

Para empezar, instale el 📦 paquete NuGet Microsoft.Extensions.AmbientMetadata.Application :

CLI de .NET
ReferenciaDePaquete

dotnet add package Microsoft.Extensions.AmbientMetadata.Application

O bien, si usa el SDK de .NET 10+:

dotnet package add Microsoft.Extensions.AmbientMetadata.Application

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

Configuración de metadatos de aplicación

Los metadatos de la aplicación se pueden configurar mediante el sistema de configuración de la aplicación. El paquete busca metadatos en la ambientmetadata:application sección de configuración de forma predeterminada.

Configurar con appsettings.json

Agregue los metadatos de la aplicación al appsettings.json archivo:

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

Configurar con IHostBuilder

Utilice el método de extensiones UseApplicationMetadata para registrar los metadatos de la aplicación ApplicationName, que rellena los valores EnvironmentName automáticamente desde IHostEnvironment. Opcionalmente, puede proporcionar valores para BuildVersion y DeploymentRing a través del appsettings.json archivo.

En la tabla siguiente se muestran los metadatos disponibles del proveedor a través de IConfiguration.

Key	¿Obligatorio?	Dónde procede el valor	Ejemplo de valor	Description
`ambientmetadata:application:applicationname`	Sí	automáticamente desde `IHostEnvironment`	`myApp`	Nombre de la aplicación.
`ambientmetadata:application:environmentname`	Sí	automáticamente desde `IHostEnvironment`	`Production`, `Development`	Entorno en el que se implementa la aplicación.
`ambientmetadata:application:buildversion`	no	configúrelo en `IConfiguration`	`1.0.0-rc1`	Versión de compilación de la aplicación.
`ambientmetadata:application:deploymentring`	no	configúrelo en `IConfiguration`	`r0`, `public`	Anillo de implementación desde donde se ejecuta la aplicación.

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;

Como alternativa, puede lograr el mismo resultado que antes haciendo esto:

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;

Tu appsettings.json puede tener una sección como la siguiente:

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

Configurar con IHostApplicationBuilder

Para las aplicaciones que usan 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;

Tu appsettings.json puede tener una sección como la siguiente:

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

Acceso a los metadatos de la aplicación

Una vez configurado, puede insertar y usar el 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();

Propiedades de los metadatos de la aplicación

La ApplicationMetadata clase incluye las siguientes propiedades:

Propiedad	Description
`ApplicationName`	Nombre de la aplicación.
`BuildVersion`	Versión del build de la aplicación.
`DeploymentRing`	Anillo o fase de implementación (por ejemplo, Canary, Production).
`EnvironmentName`	Entorno en el que se ejecuta la aplicación (por ejemplo, Desarrollo, Ensayo, Producción).

Uso con el registro

Los metadatos de la aplicación son especialmente útiles para enriquecer los mensajes de registro:

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

Sección de configuración personalizada

Si prefiere usar un nombre de sección de configuración diferente, especifíquelo al llamar a 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 esta configuración, la configuración tendría el siguiente aspecto:

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

Comentarios

Resultoulle útil esta páxina?

Last updated on 2026-01-23