Öğretici: .NET uygulamasında dinamik yapılandırma kullanma

  • Makale

Uygulama Yapılandırması .NET sağlayıcı kitaplığı, bir uygulamanın yeniden başlatılmasına neden olmadan yapılandırmanın isteğe bağlı olarak güncelleştirilmesini destekler. Bu öğretici, kodunuzda dinamik yapılandırma güncelleştirmelerini nasıl uygulayabileceğinizi gösterir. Hızlı başlangıçta tanıtılan uygulamayı temel alır. Devam etmeden önce Uygulama Yapılandırması ile .NET uygulaması oluşturma işlemini tamamlamanız gerekir.

Bu öğreticideki adımları gerçekleştirmek için herhangi bir kod düzenleyicisini kullanabilirsiniz. Visual Studio Code , Windows, macOS ve Linux platformlarında kullanılabilen mükemmel bir seçenektir.

Bu öğreticide aşağıdakilerin nasıl yapılacağını öğreneceksiniz:

  • .NET uygulamanızı bir Uygulama Yapılandırması deposundaki değişikliklere yanıt olarak yapılandırmasını güncelleştirecek şekilde ayarlayın.
  • Uygulamanızda en son yapılandırmayı kullanma.

Önkoşullar

Azure aboneliğiniz yoksa başlamadan önce birücretsiz Azure hesabı oluşturun.

hızlı başlangıcı bitirin Uygulama Yapılandırması ile .NET uygulaması oluşturma.

Etkinlik temelli yapılandırma yenilemesi

Program.cs açın ve dosyayı aşağıdaki kodla güncelleştirin.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;

IConfiguration _configuration = null;
IConfigurationRefresher _refresher = null;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    options.Connect(Environment.GetEnvironmentVariable("ConnectionString"))
            .ConfigureRefresh(refresh =>
            {
                refresh.Register("TestApp:Settings:Message")
                       .SetCacheExpiration(TimeSpan.FromSeconds(10));
            });

    _refresher = options.GetRefresher();
});

_configuration = builder.Build();

Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");

// Wait for the user to press Enter
Console.ReadLine();

if (_refresher != null)
{
    await _refresher.TryRefreshAsync();
    Console.WriteLine(_configuration["TestApp:Settings:Message"] ?? "Hello world!");

}

yöntemindeConfigureRefresh, değişiklik izleme için Uygulama Yapılandırması deponuzdaki bir anahtar kaydedilir. yöntemi, Register kayıtlı anahtar değişirse tüm yapılandırma değerlerinin yenilenip yenilenmeyeceğini belirtmek için kullanılabilecek isteğe bağlı bir boole parametresine refreshAll sahiptir. Bu örnekte yalnızca TestApp:Ayarlar:Message anahtarı yenilenir. yöntemi, SetCacheExpiration yapılandırma değişikliklerini denetlemek için Uygulama Yapılandırması yeni bir istekte bulunulmadan önce geçmesi gereken en kısa süreyi belirtir. Bu örnekte, gösterim amacıyla bunun yerine 10 saniyelik bir süre belirterek 30 saniyelik varsayılan süre sonunu geçersiz kılarsınız.

Yöntemin tek başına çağrılması ConfigureRefresh , yapılandırmanın otomatik olarak yenilenmesine neden olmaz. Yenilemeyi TryRefreshAsync tetiklemek için arabiriminden IConfigurationRefresher yöntemini çağırırsınız. Bu tasarım, uygulamanız boşta olsa bile Uygulama Yapılandırması gönderilen istekleri önlemeye yöneliktir. Çağrıyı TryRefreshAsync uygulamanızın etkin olduğunu düşündüğünüz yere eklemek istersiniz. Örneğin, gelen bir iletiyi, bir sırayı veya karmaşık bir görevin yinelemesini işlerken olabilir. Uygulamanız sürekli etkinse zamanlayıcıda da olabilir. Bu örnekte Enter tuşuna her bastığınızda çağrısında TryRefreshAsync bulunursunuz. Arama TryRefreshAsync herhangi bir nedenle başarısız olsa bile, uygulamanız önbelleğe alınmış yapılandırmayı kullanmaya devam eder. Yapılandırılan önbellek süre sonu süresi geçtiğinde ve TryRefreshAsync çağrı uygulama etkinliğiniz tarafından yeniden tetiklendiğinde başka bir deneme yapılır. Çağrı TryRefreshAsync , yapılandırılan önbellek süre sonu süresi dolmadan önce yapılan bir işlev değildir, bu nedenle sık sık çağrılsa bile performans etkisi en düşük düzeyde olur.

Bağımlılık ekleme kullanarak yapılandırma yenilemesi

Önceki kodda, öğesini çağırmak TryRefreshAsynciçin örneğini IConfigurationRefresher el ile kaydediyorsunuz. Alternatif olarak, hizmetlerinizi çözümlemek için bağımlılık ekleme kullanıyorsanız aşağıdaki adımlara başvurabilirsiniz.

  1. üzerinde IServiceCollectionçağırarak AddAzureAppConfiguration gerekli Uygulama Yapılandırması hizmetlerini kaydedin.

    aşağıdaki kodu Program.cs ekleyin.

    // Existing code in Program.cs
// ... ...

// Add Azure App Configuration services to IServiceCollection
builder.Services.AddAzureAppConfiguration();

  2. Hizmet koleksiyonunuzdaki bir örneğini IConfigurationRefresherProvider çözümleyerek ve her bir yenileyiciyi çağırarak TryRefreshAsync yapılandırmanızı yenileyin.

    class SampleConfigRefresher
{
    private readonly IEnumerable<IConfigurationRefresher> _refreshers = null;

    public SampleConfigRefresher(IConfigurationRefresherProvider refresherProvider)
    {
        _refreshers = refresherProvider.Refreshers;
    }

    public async Task RefreshConfiguration()
    {
        foreach (var refresher in _refreshers)
        {
            _ = refresher.TryRefreshAsync();
        }
    }
}

Uygulamayı yerel olarak derleme ve çalıştırma

  1. Bağlan ionString adlı bir ortam değişkeni ayarlayın ve bunu Uygulama Yapılandırması deponuzun erişim anahtarına ayarlayın. Windows komut istemini kullanıyorsanız, aşağıdaki komutu çalıştırın ve değişikliğin etkili olması için komut istemini yeniden başlatın:

     setx ConnectionString "connection-string-of-your-app-configuration-store"

    Windows PowerShell kullanıyorsanız aşağıdaki komutu çalıştırın:

     $Env:ConnectionString = "connection-string-of-your-app-configuration-store"

    macOS veya Linux kullanıyorsanız aşağıdaki komutu çalıştırın:

     export ConnectionString='connection-string-of-your-app-configuration-store'

  2. Konsol uygulamasını oluşturmak için aşağıdaki komutu çalıştırın:

     dotnet build

  3. Derleme başarıyla tamamlandıktan sonra aşağıdaki komutu çalıştırarak uygulamayı yerel olarak çalıştırın:

     dotnet run

    Quickstart app launch local

  4. Azure Portal’ında oturum açın. Tüm kaynaklar'ı seçin ve hızlı başlangıçta oluşturduğunuz Uygulama Yapılandırması mağaza örneğini seçin.

  5. Yapılandırma Gezgini'ni seçin ve aşağıdaki anahtarların değerlerini güncelleştirin:

    Anahtar Değer
    TestApp:Ayarlar:Message Azure Uygulaması Yapılandırmasından Veriler - Güncelleştirildi

  6. Yenilemeyi tetiklemek ve güncelleştirilmiş değeri Komut İstemi veya PowerShell penceresinde yazdırmak için Enter tuşuna basın.

    Quickstart app refresh local

    Not

    Yenileme işlemi için yapılandırma belirtilirken önbellek süre sonu süresi yöntemi kullanılarak SetCacheExpiration 10 saniye olarak ayarlandığından, yapılandırma ayarının değeri yalnızca bu ayar için son yenilemeden bu yana en az 10 saniye geçtiğinde güncelleştirilir.

Günlüğe kaydetme ve izleme

Günlükler yapılandırma yenilemesi sonrasında çıkarılır ve Uygulama Yapılandırması deponuzdan alınan anahtar değerleri ve uygulamanızda yapılan yapılandırma değişiklikleri hakkında ayrıntılı bilgiler içerir. ASP.NET Core uygulamanız varsa ASP.NET Core'da Günlüğe Kaydetme ve İzleme yönergelerine bakın. Aksi takdirde, Azure SDK ile günlüğe kaydetme yönergelerini kullanarak günlüğü etkinleştirebilirsiniz.

  • Günlükler farklı olay düzeylerinde çıkıştır. Varsayılan düzey: Informational.

    Olay Düzeyi Açıklama
    Ayrıntılı Günlükler, uygulamanızın Uygulama Yapılandırması deponuzdan gelen değişiklikler için izlediği anahtar-değerlerin anahtarını ve etiketini içerir. Bilgiler ayrıca anahtar-değerin uygulamanızın zaten yüklemiş olduğu değerle karşılaştırıldığında değişip değişmediğini de içerir. Yapılandırma değişikliği beklendiği gibi gerçekleşmediyse uygulamanızın sorunlarını gidermek için günlükleri bu düzeyde etkinleştirin.
    Bilgi Günlükler, yapılandırma yenilemesi sırasında güncelleştirilen yapılandırma ayarlarının anahtarlarını içerir. Hassas verilerin sızmasını önlemek için yapılandırma ayarlarının değerleri günlükten atlanır. Uygulamanızın beklenen yapılandırma değişikliklerini aldığından emin olmak için günlükleri bu düzeyde izleyebilirsiniz.
    Uyarı Günlükler, yapılandırma yenilemesi sırasında oluşan hataları ve özel durumları içerir. Yapılandırma sağlayıcısı önbelleğe alınan verileri kullanmaya devam edeceğinden ve bir dahaki sefere yapılandırmayı yenilemeye çalışacağından, zaman zaman oluşumlar yoksayılabilir. Olası sorunları gösterebilecek yinelenen uyarılar için bu düzeydeki günlükleri izleyebilirsiniz. Örneğin, bağlantı dizesi döndürdünüz ancak uygulamanızı güncelleştirmeyi unuttunuz.

    Aşağıdaki örnekte olduğu gibi parametresini EventLevel.Verbose belirterek olay düzeyinde günlüğe kaydetmeyi Verbose etkinleştirebilirsiniz. Bu yönergeler diğer tüm olay düzeyleri için de geçerlidir. Bu örnek yalnızca kategori için Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh günlükleri de etkinleştirir.

    using var listener = new AzureEventSourceListener((eventData, text) =>
{
    if (eventData.EventSource.Name == "Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh")
    {
        Console.WriteLine("[{1}] {0}: {2}", eventData.EventSource.Name, eventData.Level, text);
    }
}, EventLevel.Verbose);

  • Günlük kategorisi, her günlük öncesinde görünen şeklindedir Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh. Her olay düzeyinde bazı örnek günlükler aşağıda verilmiştir:

    [Verbose] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
Key-value read from App Configuration. Change:'Modified' Key:'ExampleKey' Label:'ExampleLabel' Endpoint:'https://examplestore.azconfig.io'

[Informational] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
Setting updated. Key:'ExampleKey'

[Warning] Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh:
A refresh operation failed while resolving a Key Vault reference.
Key vault error. ErrorCode:'SecretNotFound' Key:'ExampleKey' Label:'ExampleLabel' Etag:'6LaqgBQM9C_Do2XyZa2gAIfj_ArpT52-xWwDSLb2hDo' SecretIdentifier:'https://examplevault.vault.azure.net/secrets/ExampleSecret'

Not

Aşağıdaki paketlerden herhangi birinin 6.0.0 veya sonraki bir sürümünü kullanıyorsanız günlüğe kaydetme kullanılabilir.

  • Microsoft.Extensions.Configuration.AzureAppConfiguration
  • Microsoft.Azure.AppConfiguration.AspNetCore
  • Microsoft.Azure.AppConfiguration.Functions.Worker

Kaynakları temizleme

Bu makalede oluşturulan kaynakları kullanmaya devam etmek istemiyorsanız ücretlerden kaçınmak için burada oluşturduğunuz kaynak grubunu silin.

Önemli

Silinen kaynak grupları geri alınamaz. Kaynak grubu ve içindeki tüm kaynaklar kalıcı olarak silinir. Yanlış kaynak grubunu veya kaynakları yanlışlıkla silmediğinizden emin olun. Bu makalenin kaynaklarını, saklamak istediğiniz diğer kaynakları içeren bir kaynak grubu içinde oluşturduysanız, kaynak grubunu silmek yerine her kaynağı ilgili bölmeden tek tek silin.

  1. Azure portalında oturum açın ve Kaynak grupları'nı seçin.
  2. Ada göre filtrele kutusuna kaynak grubunuzun adını girin.
  3. Genel bir bakış görmek için sonuç listesinde kaynak grubu adını seçin.
  4. Kaynak grubunu sil'i seçin.
  5. Kaynak grubunun silinmesini onaylamanız istenir. Onaylamak için kaynak grubunuzun adını girin ve Sil'i seçin.

Birkaç dakika sonra kaynak grubu ve tüm kaynakları silinir.

Sonraki adımlar

Bu öğreticide yapılandırma ayarlarını Uygulama Yapılandırması dinamik olarak yenilemek için .NET uygulamanızı etkinleştirmişsiniz. Azure yönetilen kimliğini kullanarak Uygulama Yapılandırması erişimini kolaylaştırmayı öğrenmek için sonraki öğreticiye geçin.

Yönetilen kimlik tümleştirmesi