Uygulama ortam meta verileri

Microsoft.Extensions.AmbientMetadata.Application NuGet paketi, uygulama genelinde uygulama düzeyindeki ortam meta verilerini yakalamak ve akışa almak için işlevsellik sağlar. Bu meta veriler, telemetriyi, sorun gidermeyi ve çözümlemeyi zenginleştirmek için değerli olan uygulama adı, sürüm, dağıtım ortamı ve dağıtım halkası gibi bilgileri içerir.

Uygulama meta verilerini neden kullanmalısınız?

Uygulama meta verileri, çalışan uygulamanız hakkında gözlemlenebilirliği geliştirebilecek temel bağlam sağlar:

• Telemetri zenginleştirmesi: Günlüklere, ölçümlere ve izlemelere uygulama ayrıntılarını otomatik olarak ekleyin.
• Sorun giderme: Uygulamanızın hangi sürümünde sorun yaşandığını hızla belirleyin.
• Ortam belirleme: Telemetrinizdeki farklı ortamları ayırt edin.
• Dağıtım izleme: Farklı dağıtım halkaları veya bölgelerdeki sorunları izleyin.
• Tutarlı meta veriler: Uygulamanızdaki tüm bileşenlerin aynı meta veri değerlerini kullandığından emin olun.

Paketi yükle

Başlamak için Microsoft.Extensions.AmbientMetadata.Application NuGet paketini yükleyin📦:

.NET CLI

dotnet add package Microsoft.Extensions.AmbientMetadata.Application

Veya .NET 10+ SDK kullanıyorsanız:

dotnet package add Microsoft.Extensions.AmbientMetadata.Application

PackageReference

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

Uygulama meta verilerini yapılandırma

Uygulama meta verileri, uygulamanızın yapılandırma sistemi aracılığıyla yapılandırılabilir. Paket varsayılan olarak yapılandırma bölümünün altında ambientmetadata:application meta verileri arar.

appsettings.json ile yapılandırma

Uygulama meta verilerini dosyanıza appsettings.json ekleyin:

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

IHostBuilder ile yapılandırma

UseApplicationMetadata uzantılar yöntemini kullanarak uygulama meta verilerini kaydedin; bu, ApplicationName'den gelen EnvironmentName ve IHostEnvironment değerlerini otomatik olarak doldurur. İsteğe bağlı olarak, BuildVersion ve DeploymentRing için değerleri appsettings.json dosyası aracılığıyla sağlayabilirsiniz.

Aşağıdaki tabloda, IConfiguration aracılığıyla sağlayıcı tarafından sağlanan meta veriler gösterilmektedir.

Key	Gerekli mi?	Değerin geldiği yer	Değer örneği	Description
ambientmetadata:application:applicationname	yes	otomatik olarak IHostEnvironment	myApp	Uygulama adı.
ambientmetadata:application:environmentname	yes	otomatik olarak IHostEnvironment	Production, Development	Uygulamanın dağıtılacağı ortam.
ambientmetadata:application:buildversion	no	IConfiguration içinde yapılandırın	1.0.0-rc1	Uygulamanın derleme sürümü.
ambientmetadata:application:deploymentring	no	IConfiguration içinde yapılandırın	r0, public	Uygulamanın çalıştığı dağıtım halkası.

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;

Alternatif olarak, bunu yaparak yukarıdakiyle aynı sonucu elde edebilirsiniz:

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;

Bölümünüz appsettings.json aşağıdaki gibi olabilir:

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

IHostApplicationBuilder ile yapılandırma

kullanan IHostApplicationBuilderuygulamalar için:

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;

Bölümünüz appsettings.json aşağıdaki gibi olabilir:

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

Uygulama meta verilerine erişme

Yapılandırıldıktan sonra ApplicationMetadata türünü ekleyebilir ve kullanabilirsiniz.

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 özellikleri

ApplicationMetadata sınıfı aşağıdaki özellikleri içerir:

Mülkiyet	Description
ApplicationName	Uygulamanın adı.
BuildVersion	Uygulama yapısının sürümü.
DeploymentRing	Dağıtım halkası veya aşaması (örneğin, Kanarya, Üretim).
EnvironmentName	Uygulamanın çalıştığı ortam (örneğin, Geliştirme, Hazırlama, Üretim).

Günlüğe kaydetme ile kullanma

Uygulama meta verileri özellikle günlük iletilerini zenginleştirmek için kullanışlıdır:

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

Özel yapılandırma bölümü

Farklı bir yapılandırma bölümü adı kullanmayı tercih ediyorsanız, UseApplicationMetadata<TBuilder>(TBuilder, String) öğesini çağırırken belirtin:

using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

// Use custom configuration section
builder.UseApplicationMetadata("myapp:metadata");

var host = builder.Build();

await host.RunAsync();

Bu yapılandırmayla, ayarlarınız şöyle görünür:

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