Breyta

Deila með

Application ambient metadata

The Microsoft.Extensions.AmbientMetadata.Application NuGet package provides functionality to capture and flow application-level ambient metadata throughout your application. This metadata includes information such as the application name, version, deployment environment, and deployment ring, which is valuable for enriching telemetry, troubleshooting, and analysis.

Why use application metadata

Application metadata provides essential context about your running application that can enhance observability:

  • Telemetry enrichment: Automatically add application details to logs, metrics, and traces.
  • Troubleshooting: Quickly identify which version of your application is experiencing issues.
  • Environment identification: Distinguish between different environments in your telemetry.
  • Deployment tracking: Track issues across different deployment rings or regions.
  • Consistent metadata: Ensure all components in your application use the same metadata values.

Install the package

To get started, install the 📦 Microsoft.Extensions.AmbientMetadata.Application NuGet package:

dotnet add package Microsoft.Extensions.AmbientMetadata.Application

Or, if you're using .NET 10+ SDK:

dotnet package add Microsoft.Extensions.AmbientMetadata.Application

Configure application metadata

Application metadata can be configured through your application's configuration system. The package looks for metadata under the ambientmetadata:application configuration section by default.

Configure with appsettings.json

Add the application metadata to your appsettings.json file:

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

Configure with IHostBuilder

Use the UseApplicationMetadata extensions method to register application metadata, which populates ApplicationName and EnvironmentName values automatically from IHostEnvironment. Optionally, you can provide values for BuildVersion and DeploymentRing via the appsettings.json file.

The following table shows the metadata made available by the provider via IConfiguration:

Key Required? Where the value comes from Value example Description
ambientmetadata:application:applicationname yes automatically from IHostEnvironment myApp The application name.
ambientmetadata:application:environmentname yes automatically from IHostEnvironment Production, Development The environment the application is deployed to.
ambientmetadata:application:buildversion no configure it in IConfiguration 1.0.0-rc1 The application's build version.
ambientmetadata:application:deploymentring no configure it in IConfiguration r0, public The deployment ring from where the application is running. 
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;

Alternatively, you can achieve the same result as above by doing this:

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;

Your appsettings.json can have a section as follows:

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

Configure with IHostApplicationBuilder

For applications using 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;

Your appsettings.json can have a section as follows:

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

Access application metadata

Once configured, you can inject and use the ApplicationMetadata type:

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 properties

The ApplicationMetadata class includes the following properties:

Property Description
ApplicationName The name of the application.
BuildVersion The version of the application build.
DeploymentRing The deployment ring or stage (for example, Canary, Production).
EnvironmentName The environment where the application is running (for example, Development, Staging, Production).

Use with logging

Application metadata is particularly useful for enriching log messages:

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

Custom configuration section

If you prefer to use a different configuration section name, specify it when calling 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();

With this configuration, your settings would look like:

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