.NET yapılandırma sağlayıcısı

Azure Uygulama Yapılandırması, geliştiricilerin uygulama yapılandırmalarını basit ve güvenli bir biçimde merkezileştirmesine yardımcı olan, yönetilen bir hizmettir. .NET yapılandırma sağlayıcısı kitaplığı, azure uygulama yapılandırma deposundan yapılandırmanın yönetilen bir şekilde yüklenmesini sağlar. Bu istemci kitaplığı, .NET için Azure SDK'sının üzerine ek işlevler ekler.

Yapılandırmayı Yükle

Azure Uygulama Yapılandırması .NET yapılandırma sağlayıcısı .NET yapılandırma sistemiyle tümleştirerek Azure Uygulama Yapılandırma deponuzdan yapılandırma değerlerini yüklemeyi kolaylaştırır. Sağlayıcıyı uygulama başlatma sırasında ekleyebilir ve diğer yapılandırma kaynaklarıyla birlikte kullanabilirsiniz.

.NET yapılandırma sağlayıcısını kullanmak için paketini yükleyin:

dotnet add package Microsoft.Extensions.Configuration.AzureAppConfiguration

Azure Uygulama Yapılandırması'nı uygulamanızın yapılandırma sağlayıcısı olarak eklemek için uzantı yöntemini AddAzureAppConfiguration üzerinde IConfigurationBuilder çağırın.

Yapılandırma sağlayıcısı kitaplığı, yapılandırmanın temiz, bildirim temelli bir yolunu sağlamak için birleştirilmiş Seçenekler Deseni ve Oluşturucu DeseniAzureAppConfigurationOptionsuygular. AddAzureAppConfiguration yöntemi, sağlayıcıyı akıcı bir Action<AzureAppConfigurationOptions> API aracılığıyla yapılandırmanızı sağlayan bir temsilci parametresini kabul eder.

Azure Uygulama Yapılandırma deponuza bağlanmak için Connect örneği üzerinde AzureAppConfigurationOptions yöntemini çağırın; bu yöntem, yöntem zincirlemeyi etkinleştirmek için aynı seçenekler nesnesini döndürür.

Microsoft Entra ID
Bağlantı dizesi

Uygulama Yapılandırma deponuzda kimlik doğrulaması yapmak için DefaultAzureCredential, veya başka bir jeton kimlik bilgisi uygulamasını kullanabilirsiniz. Kimlik bilgilerinizi Uygulama Yapılandırması Veri Okuyucusu rolüne atamak için yönergeleri izleyin.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
using Azure.Identity;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
    {
        string endpoint = Environment.GetEnvironmentVariable("AppConfigurationEndpoint");
        options.Connect(new Uri(endpoint), new DefaultAzureCredential());
    });

var config = builder.Build();
Console.WriteLine(config["TestApp:Settings:Message"] ?? "Hello world!");

Uyarı

ASP.NET Core uygulamasında veya arka plan hizmetinde AddAzureAppConfiguration üzerinde builder.Configuration çağrısını yapabilirsiniz.

var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddAzureAppConfiguration(options =>
    {
        string endpoint = Environment.GetEnvironmentVariable("Endpoint");
        options.Connect(new Uri(endpoint), new DefaultAzureCredential());
    });

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;
using Azure.Identity;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
    {
        string connectionString = Environment.GetEnvironmentVariable("ConnectionString");
        options.Connect(connectionString);
    });

var config = builder.Build();
Console.WriteLine(config["TestApp:Settings:Message"] ?? "Hello world!");

Uyarı

ASP.NET Core uygulamasında veya arka plan hizmetinde AddAzureAppConfiguration üzerinde builder.Configuration çağrısını yapabilirsiniz.

var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddAzureAppConfiguration(options =>
    {
        string connectionString = Environment.GetEnvironmentVariable("ConnectionString");
        options.Connect(connectionString);
    });

Yapılandırmayı tüketme

Azure Uygulama Yapılandırma sağlayıcısını ekledikten sonra yapılandırma değerlerinize çeşitli yollarla erişebilirsiniz:

1. Doğrudan erişim

En basit yaklaşım, değerleri doğrudan örnekten IConfiguration almaktır:

// Directly get the configuration
string message = configuration["TestApp:Settings:Message"];

IConfigurationSection settingsSection = configuration.GetSection("TestApp:Settings");

2. IConfiguration ile bağımlılık ekleme

Hizmetlerde veya denetleyicilerde arabirimi doğrudan ekleyebilir ve kullanabilirsiniz IConfiguration :

public class WeatherService
{
    private readonly IConfiguration _configuration;

    public WeatherService(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    public Task<WeatherForecast> GetForecastAsync()
    {
        // Access configuration values directly from the injected instance
        string apiEndpoint = _configuration["TestApp:Weather:ApiEndpoint"];

        ...

        return Task.FromResult(new WeatherForecast());
    }
}

3. Güçlü tip yapılandırma için seçenekler şablonu

// Define a strongly typed settings class
public class Settings
{
    public string BackgroundColor { get; set; }
    public long FontSize { get; set; }
    public string FontColor { get; set; }
    public string Message { get; set; }
}

builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));

.NET'teki seçenekler deseni hakkında daha fazla bilgi için belgelere gidin.

JSON içerik türü işleme

Uygulama Yapılandırması'nda JSON anahtar değerleri oluşturabilirsiniz. İçerik türüne "application/json" sahip bir anahtar-değer okunduğunda, yapılandırma sağlayıcısı bunu içindeki IConfigurationtek tek ayarlara düzleştirir. Daha fazla bilgi için uygulama yapılandırmasında JSON anahtar değerlerini depolamak için içerik türünü kullanma bölümüne gidin.

Uyarı

8.4.0 sürümünden Microsoft.Extensions.Configuration.AzureAppConfigurationbaşlayarak, yapılandırma sağlayıcısı içerik türüne sahip anahtar değerlerinde (application/json) tanımlandığı gibi açıklamalara izin verir.

Seçicileri kullanarak belirli anahtar değerlerini yükleme

Varsayılan olarak, yapılandırma sağlayıcısı Uygulama Yapılandırması'ndan etiket içermeyen tüm anahtar değerlerini yükler. Select yöntemini AzureAppConfigurationOptions üzerinde çağırarak, Anahtar-değerleri Uygulama Yapılandırma deponuzdan seçmeli olarak yükleyebilirsiniz.

builder.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())
        // Load configuration values with prefix "TestApp:" and no label
        .Select("App:Settings:*")
        // Load configuration values with prefix "TestApp:" and "Prod" label
        .Select("App:Settings:*", "Prod")
        // Load configuration values with prefix "TestApp:" and "Prod" label that have the tag "Group" with value "Contoso"
        .Select("App:Settings:*", "Prod", new[] { "Group=Contoso" })
});

Select yöntemi üç parametre alır. İlk parametre, yüklenecek anahtarları belirten bir anahtar filtresidir, ikinci parametre yüklenecek belirli etiketlere sahip anahtar değerlerini belirten bir etiket filtresidir ve üçüncü parametre, yüklenecek anahtar-değerde bulunması gereken etiket filtreleri koleksiyonunu belirtir.

Uyarı

Birden çok Select çağrı çakışan anahtarlar içerdiğinde, sonraki çağrılar öncekilerden önceliklidir.

Anahtar filtresi

Anahtar filtresi parametresi hangi yapılandırma anahtarlarının dahilleneceğini belirler:

Tam eşleşme: Belirli bir dizenin kullanılması yalnızca filtreyle tam olarak eşleşen anahtarlarla eşleşir.
Ön ek eşleşmesi: Sona yıldız işareti (*) eklemek bir ön ek filtresi oluşturur (örneğin, App:Settings:* "App:Settings:" ile başlayan tüm anahtarları yükler).
Birden çok anahtar seçimi: Virgül (,) kullanmak birden çok açık anahtar (örn. Key1,Key2,Key3) seçilmesine izin verir.
Ayrılmış karakterler: Yıldız işareti (*), virgül (,) ve ters eğik çizgi (\) karakterleri ayrılmıştır ve anahtar adlarında kullanıldığında, ters eğik çizgi ile ifade edilmelidir (örneğin, anahtar filtresi a\\b\,\*c*, anahtarı a\b,*c ile başlayan tüm anahtar-değerleri döndürür).

Uyarı

Joker karakter ön ek eşleştirmesini aynı Select çağrıda virgülle ayrılmış filtrelerle birleştiremezsiniz. Örneğin, abc*,def desteklenmez, ancak Select ve abc* ile ayrı def çağrılar yapabilirsiniz.

Etiket filtresi

Etiket filtresi parametresi, belirli bir etikete sahip anahtar-değerleri seçer. Belirtilmezse, yerleşik LabelFilter.Null kullanılır.

Uyarı

Etiket filtresi için yıldız işareti (*) ve virgül (, ) karakterleri desteklenmez. Ters eğik çizgi (\) karakteri ayrılmıştır ve başka bir ters eğik çizgi (\) kullanılarak kaçış karakteri kullanılmalıdır.

Etiket filtreleri

Etiket filtreleri parametresi, belirli etiketlere sahip anahtar-değerleri seçer. Anahtar-değer yalnızca filtrelerde belirtilen tüm etiketlere ve karşılık gelen değerlere sahipse yüklenir. Bir etiket için null değer belirtmek için yerleşik TagValue.Null kullanılabilir.

Uyarı

Yıldız işareti (*), virgül (,) ve ters eğik çizgi (\) karakterleri ayrılmıştır ve etiket filtresinde kullanıldığında ters eğik çizgiyle kaçış karakteriyle kullanılmalıdır.

Anahtarlardan önekleri kırpın

Belirli ön eklere sahip yapılandırma değerlerini yüklerken, bu ön ekleri yapılandırmanızdaki anahtarlardan kaldırmak için yöntemini kullanabilirsiniz TrimKeyPrefix . Bu, uygulamanızda daha temiz yapılandırma anahtarları oluştururken, uygulama Yapılandırma deponuzda kuruluş bakımı da sağlar.

builder.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())
        // Load configuration values with prefix "TestApp:" and trim the prefix
        .Select("TestApp:*")
        .TrimKeyPrefix("TestApp:");
});

Örneğin, Uygulama Yapılandırma deponuzda TestApp:Settings:Message adlı bir anahtar varsa, Settings:Message ön eki kırpıldıktan sonra uygulamanızda TestApp: olarak erişilebilir.

Yapılandırma ayarı eşlemesi

Azure Uygulama Yapılandırması'ndan anahtar-değerleri yüklerken yükleyici, bunları .NET yapılandırma sistemine eklemeden önce anahtar-değerleri nesne olarak getirir. Map API, bu işlem hattı sırasında bu ayarları dönüştürmenize olanak tanıyarak yapılandırmaların uygulamanızda nasıl görüneceğini denetlemenizi sağlar.

Map yöntemi, bir ConfigurationSetting nesnesini alan bir temsilci işlevi kabul eder, nesneyi değiştirmenizi sağlar ve bir ValueTask<ConfigurationSetting> döndürür. Bu özellikle çalışma zamanı koşullarına göre anahtar adı dönüştürmeleri veya değer biçimlendirmesi için kullanışlıdır.

Aşağıdaki örnek, yapılandırma anahtarlarındaki çift alt çizgiyi (Map) iki nokta (__) ile değiştirmek için : API'sinin nasıl kullanıldığını gösterir. Bu dönüştürme, anahtarların Uygulama Yapılandırması'nda alternatif karakterler kullanması gerektiğinde .NET yapılandırması tarafından beklenen hiyerarşik yapıyı korur:

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .Map((setting) =>
        {
            // Transform keys from format "App__Settings__Message" to "App:Settings:Message"
            setting.Key = setting.Key.Replace("__", ":");
            
            return new ValueTask<ConfigurationSetting>(setting);
        });
});

Tavsiye

İşlem Map , Uygulama Yapılandırması'ndan alınan tüm yapılandırma ayarlarına uygulanır, bu nedenle dönüştürme mantığınızın tüm olası anahtar biçimlerini doğru işlediğinden emin olun.

Yapılandırma yenilemesi

Yenilemenin yapılandırılması, uygulamanın yeniden başlatmaya gerek kalmadan Uygulama Yapılandırma deposundan en son değerleri çekmesini sağlar. Anahtar-değer yenilemesini yapılandırmak için ConfigureRefresh yöntemini kullanabilirsiniz.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        // Load all keys that start with `TestApp:` and have no label
        .Select(keyFilter: "TestApp:*", labelFilter: LabelFilter.Null)
        .ConfigureRefresh(refreshOptions => {
            // Trigger full configuration refresh when any selected key changes.
            refreshOptions.RegisterAll()
            // Check for changes no more often than every 60 seconds
                .SetRefreshInterval(TimeSpan.FromSeconds(60));
        });
});

ConfigureRefresh yönteminin içinde, seçilen anahtar değerlerden herhangi birinde (TestApp: ile başlayan ve etiketi olmayanlar) bir değişiklik algılandığında yapılandırmayı yeniden yüklemesi için Uygulama Yapılandırma sağlayıcısını bilgilendirmek amacıyla RegisterAll yöntemini çağırırsınız.

Yapılandırma yenilemeleri arasındaki en düşük süreyi belirtmek için yöntemine bir çağrı SetRefreshInterval ekleyebilirsiniz. Ayarlanmadıysa, varsayılan yenileme aralığı 30 saniyedir.

Yenilemeyi tetikleme

Yenilemeyi tetiklemek için TryRefreshAsync yöntemini IConfigurationRefresher çağırmanız gerekir. Azure Uygulama Yapılandırması, uygulama mimarinize bağlı olarak uygulamaya yönelik çeşitli desenler sağlar.

1. Bağımlılık enjeksiyonu

Bağımlılık ekleme (ASP.NET Core ve arka plan hizmetleri dahil) kullanan uygulamalar için yenileyici hizmetini kaydedin:

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())            
           .ConfigureRefresh(refreshOptions =>
           {
                refreshOptions.RegisterAll()
                    .SetRefreshInterval(TimeSpan.FromSeconds(60));
           })
});

// Register refresher service with the DI container
builder.Services.AddAzureAppConfiguration();

builder.Services.AddAzureAppConfiguration() IConfigurationRefreshProvider hizmeti DI kapsayıcısına ekler ve bu sayede uygulamanın yapılandırmasındaki tüm Azure Uygulama Yapılandırması kaynaklarının yenileyicilerine erişebilirsiniz.

ASP.NET Core uygulamaları

ASP.NET Core uygulamaları için paketi kullanarak Microsoft.Azure.AppConfiguration.AspNetCore yerleşik ara yazılımla istek temelli yapılandırma yenilemesi yapabilirsiniz.

dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore

Hizmeti kaydettikten sonra gelen isteklerde yapılandırmayı otomatik olarak yenilemek için UseAzureAppConfiguration uygulama işlem hattınıza eklemek üzere AzureAppConfigurationRefreshMiddleware çağırın.

...

// Call the AddAzureAppConfiguration to add refresher service to the DI container
builder.Services.AddAzureAppConfiguration();

var app = builder.Build();

// Call the app.UseAzureAppConfiguration() method as early as appropriate in your request pipeline so another middleware doesn't skip it
app.UseAzureAppConfiguration();

// Continue with other middleware registration
app.UseRouting();
...

yapılandırılan AzureAppConfigurationRefreshMiddleware yenileme aralığında yapılandırma değişikliklerini otomatik olarak denetler. Bu yaklaşım, yalnızca her iki koşul karşılandığında yenilendiğinden verimlidir: BIR HTTP isteği alınır ve yenileme aralığı doldu.

Arka plan hizmetleri

Arka plan hizmetleri için IConfigurationRefresherProvider hizmetini enjekte edebilir ve kayıtlı yenileyicilerin her birini el ile yenileyebilirsiniz.

public class Worker : BackgroundService
{
    private readonly IConfiguration _configuration;
    private readonly IEnumerable<IConfigurationRefresher> _refreshers;

    public Worker(IConfiguration configuration, IConfigurationRefresherProvider refresherProvider)
    {
        _configuration = configuration;
        _refreshers = refresherProvider.Refreshers;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        foreach (IConfigurationRefresher refresher in _refreshers)
        {
            refresher.TryRefreshAsync();
        }

        ...
    }
}

2. Doğrudan erişim

Bağımlılık ekleme kullanmayan uygulamalar için, yenileyiciyi doğrudan seçeneklerden edinebilirsiniz:

IConfigurationRefresher refresher = null;
var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())            
           .ConfigureRefresh(refreshOptions =>
           {
               refreshOptions.RegisterAll();
           });

    // Store the refresher for later use
    refresher = options.GetRefresher();
});

IConfiguration config = builder.Build();

// Later in your code, trigger refresh when needed
if (refresher != null)
{
    await refresher.TryRefreshAsync()
}

Console.WriteLine(config["TestApp:Settings:Message"]);

Uyarı

Yenileme çağrısı herhangi bir nedenle başarısız olsa bile, uygulamanız önbelleğe alınmış yapılandırmayı kullanmaya devam eder. Uygulama etkinliğinize bağlı olarak kısa bir süre sonra başka bir deneme yapılır. Yenilemeyi çalıştırmak, yapılandırılan yenileme aralığı dolmadan önce bir no-op olduğundan, sık sık çağrılsa bile performans üzerindeki etkisi minimum düzeydedir.

Sentinel anahtarını yenile

Sentinel anahtarı, diğer tüm anahtarların değiştirilmesini tamamladıktan sonra güncelleştirdiğiniz bir anahtardır. Yapılandırma sağlayıcısı, seçilen tüm anahtar-değerler yerine sentinel anahtarını izler. Bir değişiklik algılandığında uygulamanız tüm yapılandırma değerlerini yeniler.

Bu yaklaşım, birden çok anahtar değerini güncelleştirirken kullanışlıdır. Sentinel anahtarını yalnızca diğer tüm yapılandırma değişiklikleri tamamlandıktan sonra güncelleştirerek uygulamanızın yapılandırmayı yalnızca bir kez yeniden yüklediğinden emin olur ve tutarlılığı korursunuz.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        // Load all keys that start with `TestApp:` and have no label
        .Select(keyFilter: "TestApp:*", labelFilter: LabelFilter.Null)
        .ConfigureRefresh(refreshOptions => {
            // Trigger full configuration refresh only if the `SentinelKey` changes.
            refreshOptions.Register("SentinelKey", refreshAll: true);
        });
});

Önemli

Anahtar-değerler yenileme izleme için otomatik olarak kaydedilmez. Önce ConfigureRefresh'yü açıkça çağırmanız, ardından anahtarları kaydetmek için ya RegisterAll yöntemini (tüm yüklenen anahtarları izlemek için) ya da Register yöntemini (tek bir anahtarı izlemek için) kullanmanız gerekir.

Yenileme yapılandırması hakkında daha fazla bilgi için Öğretici: ASP.NET Core uygulamasında dinamik yapılandırmayı kullanma bölümüne gidin.

Özellik bayrağı

Azure Uygulama Yapılandırması'ndaki özellik bayrakları, uygulamalarınızda özellik kullanılabilirliğini denetlemek için modern bir yol sağlar. Normal yapılandırma değerlerinden farklı olarak, özellik bayraklarının yöntemi kullanılarak UseFeatureFlags açıkça yüklenmesi gerekir. seçicileri kullanarak belirli özellik bayraklarını yükleyip özellik bayrağı yenileme aralığını ayarlamak için 'ı FeatureFlagOptions yapılandırabilirsiniz.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .UseFeatureFlags(featureFlagOptions => {
            // Load feature flags with prefix "TestApp:" and "dev" label
            featureFlagOptions.Select("TestApp:*", "dev")
            // Check for changes no more often than every 60 seconds
                .SetRefreshInterval(TimeSpan.FromSeconds(60));
        });
});

UseFeatureFlags yönteminin içinde, özellik bayraklarını seçici olarak yüklemek için Select yöntemini çağırırsınız. Yüklemek istediğiniz özellik bayraklarını seçmek için anahtar filtresi, etiket filtresi ve etiket filtrelerini kullanabilirsiniz. Select Hiçbir yöntem çağrılmazsa, UseFeatureFlags varsayılan olarak etiketsiz tüm özellik bayraklarını yükler.

Anahtar değerlerinden farklı olarak özellik bayrakları, açık ConfigureRefresh çağrı gerekmeden yenileme için otomatik olarak kaydedilir. Yöntemi aracılığıyla SetRefreshInterval özellik bayrağı yenilemeleri arasındaki en düşük süreyi belirtebilirsiniz. Varsayılan yenileme aralığı 30 saniyedir.

Özellik yönetimi

Özellik yönetimi kitaplığı, özellik bayraklarını temel alarak uygulama işlevselliği geliştirmenin ve kullanıma sunmanın bir yolunu sağlar. Özellik yönetimi kitaplığı, yapılandırma sağlayıcısı kitaplığıyla birlikte çalışacak şekilde tasarlanmıştır. Microsoft.FeatureManagement Paketi yükleyin:

dotnet add package Microsoft.FeatureManagement

AddFeatureManagement'ı arayarak IVariantFeatureManager ve ilgili hizmetleri DI kapsayıcısına kaydedebilirsiniz. Bu kayıt, özellik bayrağı işlevselliğini bağımlılık ekleme yoluyla uygulamanızda kullanılabilir hale getirir.

using Microsoft.FeatureManagement;

...

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential());
    // Use feature flags
    options.UseFeatureFlags();
});

// Register feature management services
builder.Services.AddFeatureManagement();

Bağımlılık ekleme yoluyla özellik yöneticisi hizmetinin nasıl kullanılacağını gösteren aşağıdaki örnek:

public class WeatherForecastController : ControllerBase
{
    private readonly IFeatureManager _featureManager;

    public WeatherForecastController(IVariantFeatureManager featureManager)
    {
        _featureManager = featureManager;
    }

    [HttpGet]
    public async Task<IActionResult> Get()
    {
        // Check if a feature flag is enabled
        if (await _featureManager.IsEnabledAsync("WeatherForecast"))
        {
            var forecast = GenerateWeatherForecast();
            return Ok(forecast);
        }
        
        return NotFound("Weather forecast feature is not available");
    }
}

Özellik yönetimi kitaplığını kullanma hakkında daha fazla bilgi için özellik bayrağı hızlı başlangıç kılavuzuna gidin.

Özellik kontrol bayrağı telemetrisi

Özellik bayrağı telemetrisi etkinleştirildiğinde, Azure Uygulama Yapılandırması sağlayıcısı özellik bayrağı telemetri verilerine ek özellikler ekler. Bu özellikler özellik bayrağı ve değerlendirmesi hakkında daha fazla bağlam sağlar:

AllocationID: Özellik bayrağının ayırma durumunu temsil eden benzersiz tanımlayıcı.
ETag: Özellik bayrağı için geçerli ETag.
FeatureFlagReference: Özellik bayrağına biçiminde <your_store_endpoint>kv/<feature_flag_key> bir referans. Bir etiket mevcut olduğunda, başvuru bunu sorgu parametresi olarak içerir: <your_store_endpoint>kv/<feature_flag_key>?label=<feature_flag_label>.

Tam şema , Uygulama Yapılandırması Özellik Değerlendirme Olayı şema tanımında bulunabilir. Özellik bayrakları telemetrisini nasıl kullanacağınız hakkında daha fazla bilgi için özellik bayrakları için telemetriyi etkinleştirme kılavuzuna gidin.

Key Vault referansı

Azure Uygulama Yapılandırması, Azure Key Vault'ta depolanan gizli bilgilere başvurmayı destekler. Uygulama Yapılandırması'da Key Vault'ta depolanan gizli dizilere eşleyen anahtarlar oluşturabilirsiniz. Gizli bilgiler Key Vault'ta güvenli bir şekilde saklanır, ancak yüklendikten sonra diğer yapılandırma ayarları gibi erişilebilir.

Yapılandırma sağlayıcısı kütüphanesi, Uygulama Yapılandırmasında depolanan diğer anahtarlar gibi Key Vault başvurularını da alır. İstemci anahtarları Key Vault başvuruları olarak tanıdığından, benzersiz bir içerik türüne sahiptir ve istemci, uygulamanızın değerlerini almak için Key Vault'a bağlanır.

Key Vault'a bağlanma

Key Vault'a nasıl bağlanılacağını yapılandırmak için ConfigureKeyVault yöntemini çağırmanız gerekir. Azure Uygulama Yapılandırma sağlayıcısı, Key Vault gizli dizilerinizin kimliğini doğrulamak ve bu gizli dizilere erişmek için birden çok yol sunar.

1. Örneği kaydettir `SecretClient`

Belirtilen SecretClient örnekleri, ilişkili anahtar kasasında bulunan gizli bilgilerin anahtar kasası referanslarını çözmek için kullanılmak üzere kaydedilebilir.

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

...

var secretClient = new SecretClient(new Uri(vaultUri), new DefaultAzureCredential());

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())  
        .ConfigureKeyVault(kv =>
        {
            // Register a SecretClient instance
            kv.Register(secretClient);
        });
});

2. Kimlik bilgilerini kullanma

Kayıtlı SecretClientolmayan anahtar kasalarında kimlik doğrulaması yapmak için kullanılan kimlik bilgilerini ayarlayabilirsiniz.

using Azure.Identity;

...

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())  
        .ConfigureKeyVault(kv =>
        {
            // Use DefaultAzureCredential to access all Key Vaults
            kv.SetCredential(new DefaultAzureCredential());
        });
});

3. Özel gizli anahtar çözümleyicisi kullanma

Özel bir gizli dizi çözümleyicisi eklemek için, kayıtlı bir SetSecretResolver çözümleyici mevcut olmadığında veya sağlanan kimlik bilgisi Key Vault'ta doğrulanamadığında kullanılan SecretClient çağrısı yapabilirsiniz. Bu yöntem, Key Vault URI'sini gizli dizi değerine çözümleyen bir temsilci işlevi kabul eder. Aşağıdaki örnek, geliştirme ortamındaki çevresel değişkenlerden gizli bilgiyi alan ve Key Vault'tan gizliyi alamadığı durumda yedek değerleri kullanan bir gizli çözücü kullanımını gösterir.

var secretClient = new SecretClient(new Uri(vaultUri), new DefaultAzureCredential());

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())  
        .ConfigureKeyVault(kv =>
        {
            // Add a custom secret resolver function
            kv.SetSecretResolver(async (Uri secretUri) =>
            {                
                if (builder.Environment.IsDevelopment())
                {
                    return Environment.GetEnvironmentVariable("FALLBACK_SECRET_VALUE");
                }

                try 
                {
                    var secret = await secretClient.GetSecretAsync(secretName);
                    return secret.Value;
                }
                catch (Exception ex)
                {
                    logger.LogWarning($"Failed to retrieve secret from {secretUri}: {ex.Message}");
                    
                    return Environment.GetEnvironmentVariable("FALLBACK_SECRET_VALUE");
                }
            });
        });
});

Uyarı

Key Vault başvurularını çözümlerken sağlayıcı şu sırayı izler:

Kayıtlı SecretClient örnekler
Varsayılan kimlik bilgileri
Özel gizlilik çözümleyicisi

Önemli

Uygulamanız uygun Key Vault yapılandırması olmadan Key Vault başvurularını içeren anahtar değerlerini yüklerse, uygulama başlatıldığında bir özel durum fırlatılır. Key Vault erişimini veya gizli dizi çözümleyicisini düzgün yapılandırdığınızdan emin olun.

Tavsiye

Key Vault başvurularının yanlışlıkla Uygulama Yapılandırma deponuza eklendiği durumlar için, özel bir gizli anahtar çözümleyici kullanabilirsiniz. Çözümleyici, geri dönüş değerleri sağlayabilir, uyarıları kaydedebilir veya özel durumlar atmak yerine Key Vault'a erişmek için eksik veya hatalı kimlik bilgilerini uygun bir şekilde işleyebilir.

Key Vault sırrı yenileme

Azure Uygulama Yapılandırması, gizli dizi yenileme aralıklarını yapılandırma yenileme döngünüzden bağımsız olarak yapılandırmanıza olanak tanır. Bu güvenlik açısından çok önemlidir çünkü Uygulama Yapılandırması'ndaki Key Vault başvuru URI'si değişmeden kalırken, Key Vault'taki temel gizli dizi güvenlik uygulamalarınızın bir parçası olarak döndürülebilir.

Uyarı

Gizli yenileme, en az bir dakika süresi kullanır. Bu, gizli anahtarların aşırı yeniden yüklenmesini ve bunun sonucunda Key Vault üzerinde sınırlamaya yol açabilmesini önler.

Uygulamanızın her zaman en güncel gizli dizi değerlerini kullandığından emin olmak için SetSecretRefreshInterval yöntemini yapılandırın. Bu, aşağıdaki durumlarda sağlayıcıyı Key Vault'tan yeni gizli anahtar değerlerini almaya zorlar:

Uygulamanız IConfigurationRefresher.TryRefreshAsync çağrısı yapıyor
Gizli için yapılandırılan yenileme aralığının süresi doldu

Bu mekanizma, Uygulama Yapılandırma deponuzda hiçbir değişiklik algılanmadığında bile çalışır ve uygulamanızın döndürülen gizli dizilerle eşitlenmiş durumda kalmasını sağlar.

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .ConfigureKeyVault(kv =>
        {
            kv.SetCredential(new DefaultAzureCredential());

            // Option 1: Set refresh interval for specific secrets
            kv.SetSecretRefreshInterval("ApiKey", TimeSpan.FromHours(12)); 
            
            // Option 2: Set a global refresh interval for all secrets with no refresh interval specified
            kv.SetSecretRefreshInterval(TimeSpan.FromHours(24));
        })
        .ConfigureRefresh(refreshOptions => refreshOptions.RegisterAll());
});

Key Vault başvurusunu kullanma hakkında daha fazla bilgi için Öğretici: ASP.NET Core uygulamasında Key Vault başvurularını kullanma bölümüne gidin.

Anlık Görüntü

Anlık görüntü , Bir Uygulama Yapılandırma deposunun anahtar-değerlerinin adlandırılmış, sabit bir alt kümesidir. Anlık görüntüyü oluşturan anahtar-değerler, anahtar ve etiket filtreleri kullanımı aracılığıyla oluşturma sırasında seçilir. Anlık görüntü oluşturulduktan sonra içindeki anahtar-değerlerin değişmeden kalacağı garanti edilir.

Anlık görüntüden anahtar değerlerini yüklemek için çağırabilirsiniz SelectSnapshot .

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential());
    // Select an existing snapshot by name. This adds all of the key-values and feature flags from the snapshot to this application's configuration.
    options.SelectSnapshot("SnapshotName");
});

Anlık görüntüleri kullanma hakkında bilgi için Anlık görüntüler oluşturma ve kullanma bölümüne gidin.

Anlık görüntü referansı

Anlık görüntü referansı, aynı Uygulama Yapılandırma deposundaki bir anlık görüntüye başvuran bir yapılandırma ayarıdır. Yüklendiğinde sağlayıcı bu sorunu çözer ve bu anlık görüntüdeki tüm anahtar değerlerini ekler. Çalışma zamanında anlık görüntüler arasında geçiş yapılmasını sağlayan anlık görüntü başvuruları kullanmak, kod değişiklikleri ve/veya yeniden başlatmalar gerektiren SelectSnapshot("...")'den farklıdır.

Anlık görüntü başvurusu oluşturma hakkında daha fazla bilgi için anlık görüntü başvurusu kavramına gidin.

Uyarı

8.4.0 veya sonraki bir sürümünü kullanarak anlık görüntü referanslarını kullanın.

Başlatma tekrar denemesi

Yapılandırma yüklemesi, uygulama başlatma sırasında kritik bir yol işlemidir. Güvenilirliği sağlamak için Azure Uygulama Yapılandırması sağlayıcısı, ilk yapılandırma yükü sırasında sağlam bir yeniden deneme mekanizması uygular. Bu, uygulamanızın başlatma işleminin başarılı olmasını engelleyebilecek geçici ağ sorunlarından korunmasına yardımcı olur.

Yöntemini kullanarak ConfigureStartupOptions bu davranışı özelleştirebilirsiniz:

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential())
        .ConfigureStartupOptions(startupOptions =>
        {
            // Set the time-out for the initial configuration load
            startupOptions.Timeout = TimeSpan.FromSeconds(60);
        });
});

Coğrafi çoğaltma

Coğrafi çoğaltma kullanımı hakkında bilgi için Coğrafi çoğaltmayı etkinleştirme bölümüne gidin.

Dağıtılmış izleme

Azure Uygulama Yapılandırması .NET sağlayıcısı, dağıtılmış izleme için yerleşik destek içerir ve uygulamanızdaki yapılandırma işlemlerini izlemenize ve sorunlarını gidermenize olanak tanır. Sağlayıcı, yapılandırmayı yükleme ve yapılandırmayı yenileme gibi önemli işlemler için başlayan ActivitySource bir "Microsoft.Extensions.Configuration.AzureAppConfiguration" adı Activity kullanıma sunar.

Aşağıdaki örnekte, yapılandırma sağlayıcısı tarafından oluşturulan dağıtılmış izlemeleri yakalamak ve izlemek için OpenTelemetry'nin nasıl yapılandırıldığı gösterilmektedir:

List<Activity> exportedActivities = new();
builder.Services.AddOpenTelemetry()
    .WithTracing(traceBuilder => {
        traceBuilder.AddSource(["Microsoft.Extensions.Configuration.AzureAppConfiguration"]);
            .AddInMemoryExporter(exportedActivities)
    });

.NET'te OpenTelemetry hakkında daha fazla bilgi için OpenTelemetry .NET belgelerine bakın.

Sağlık denetimi

Azure Uygulama Yapılandırması .NET sağlayıcısı .NET uygulama durumu denetimlerini destekler. Sağlık denetimlerini etkinleştirmek için, IHealthChecksBuilder üzerinde AddAzureAppConfiguration() yöntemini çağırabilirsiniz; bu, varsayılan kayıt adı "Microsoft.Extensions.Configuration.AzureAppConfiguration" olan bir IHealthCheck öğesini ekler.

builder.Configuration.AddAzureAppConfiguration(options => 
    options.Connect(new Uri(appConfigEndpoint), new DefaultAzureCredential()));

builder.Services.AddHealthChecks()
    .AddAzureAppConfiguration();

Son yükleme veya yenileme girişimi başarısız olduğunda .NET sağlayıcısı iyi durumda değil olarak kabul edilir.

.NET'teki sistem durumu denetimleri hakkında daha fazla bilgi için .NET sistem durumu izleme belgelerine bakın.

Azure Front Door'a bağlanma

Azure Front Door tümleştirmesi, istemci uygulamalarının yapılandırmayı doğrudan Uygulama Yapılandırması yerine uç önbelleğe alınmış uç noktalardan getirmesine olanak tanır. Bu mimari, genel CDN dağıtımının performans avantajlarıyla güvenli, ölçeklenebilir yapılandırma erişimi sunar.

Aşağıdaki örnekte, Azure Front Door'dan yapılandırma ayarlarının nasıl yüklenecekleri gösterilmektedir:

builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.ConnectAzureFrontDoor(new Uri("{YOUR-AFD-ENDPOINT}"))
            .Select("TestApp:*")
            .ConfigureRefresh(refreshOptions =>
            {
                refreshOptions.RegisterAll()
                    .SetRefreshInterval(TimeSpan.FromMinutes(1));
            });
});

Azure Front Door hakkında daha fazla bilgi için bkz. İstemci Uygulamalarında Azure Front Door'dan Yükleme Yapılandırması.

Sonraki Adımlar

.NET yapılandırma sağlayıcısını kullanmayı öğrenmek için aşağıdaki öğreticiye geçin.

ASP.NET web uygulamasında dinamik yapılandırmayı etkinleştirme

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-03-12

.NET yapılandırma sağlayıcısı

Yapılandırmayı Yükle

Yapılandırmayı tüketme

1. Doğrudan erişim

2. IConfiguration ile bağımlılık ekleme

3. Güçlü tip yapılandırma için seçenekler şablonu

JSON içerik türü işleme

Seçicileri kullanarak belirli anahtar değerlerini yükleme

Anahtar filtresi

Etiket filtresi

Etiket filtreleri

Anahtarlardan önekleri kırpın

Yapılandırma ayarı eşlemesi

Yapılandırma yenilemesi

Yenilemeyi tetikleme

1. Bağımlılık enjeksiyonu

ASP.NET Core uygulamaları

Arka plan hizmetleri

2. Doğrudan erişim

Sentinel anahtarını yenile

Özellik bayrağı

Özellik yönetimi

Özellik kontrol bayrağı telemetrisi

Key Vault referansı

Key Vault'a bağlanma

1. Örneği kaydettir SecretClient

2. Kimlik bilgilerini kullanma

3. Özel gizli anahtar çözümleyicisi kullanma

Key Vault sırrı yenileme

Anlık Görüntü

Anlık görüntü referansı

Başlatma tekrar denemesi

Coğrafi çoğaltma

Dağıtılmış izleme

Sağlık denetimi

Azure Front Door'a bağlanma

Sonraki Adımlar

Geri Bildirim

Ek kaynaklar

1. Örneği kaydettir `SecretClient`