Samouczek: używanie konfiguracji dynamicznej w aplikacji .NET

Artykuł
02/28/2024

Biblioteka dostawcy .NET usługi App Configuration obsługuje aktualizowanie konfiguracji na żądanie bez powodowania ponownego uruchomienia aplikacji. W tym samouczku pokazano, jak zaimplementować dynamiczne aktualizacje konfiguracji w swoim kodzie. Jest ona oparta na aplikacji wprowadzonej w przewodniku Szybki start. Przed kontynuowaniem zakończ tworzenie aplikacji .NET przy użyciu usługi App Configuration .

Aby wykonać kroki opisane w tym samouczku, możesz użyć dowolnego edytora kodu. Program Visual Studio Code to doskonała opcja dostępna na platformach Windows, macOS i Linux.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

Skonfiguruj aplikację .NET, aby zaktualizować jej konfigurację w odpowiedzi na zmiany w sklepie App Configuration.
Korzystanie z najnowszej konfiguracji w aplikacji.

Wymagania wstępne

Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto platformy Azure.

Zakończ przewodnik Szybki start Tworzenie aplikacji platformy .NET przy użyciu usługi App Configuration.

Odświeżanie konfiguracji opartej na działaniach

Otwórz Program.cs i zaktualizuj plik przy użyciu następującego kodu.

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!");

}

W metodzie ConfigureRefresh klucz w magazynie usługi App Configuration jest zarejestrowany do monitorowania zmian. Metoda Register ma opcjonalny parametr refreshAll logiczny, który może służyć do wskazania, czy wszystkie wartości konfiguracji powinny zostać odświeżone, jeśli zarejestrowany klucz ulegnie zmianie. W tym przykładzie zostanie odświeżony tylko klucz TestApp:Ustawienia:Message. Metoda SetCacheExpiration określa minimalny czas, który musi upłynąć przed wprowadzeniem nowego żądania do usługi App Configuration, aby sprawdzić, czy nie wprowadzono żadnych zmian konfiguracji. W tym przykładzie zastąpisz domyślny czas wygaśnięcia 30 sekund, określając zamiast tego czas 10 sekund w celach demonstracyjnych.

ConfigureRefresh Wywołanie samej metody nie spowoduje automatycznego odświeżenia konfiguracji. Wywołasz metodę TryRefreshAsync z interfejsu IConfigurationRefresher , aby wyzwolić odświeżanie. Ten projekt polega na unikaniu żądań wysyłanych do usługi App Configuration nawet wtedy, gdy aplikacja jest bezczynna. Należy dołączyć TryRefreshAsync wywołanie, w którym rozważasz aktywną aplikację. Może to być na przykład podczas przetwarzania komunikatu przychodzącego, zamówienia lub iteracji złożonego zadania. Może również znajdować się w czasomierzu, jeśli aplikacja jest aktywna przez cały czas. W tym przykładzie wywołasz wywołanie TryRefreshAsync za każdym razem, gdy naciskasz klawisz Enter. Nawet jeśli wywołanie TryRefreshAsync zakończy się niepowodzeniem z jakiegokolwiek powodu, aplikacja nadal używa buforowanej konfiguracji. Kolejna próba jest podejmowana po upływie skonfigurowanego czasu wygaśnięcia pamięci podręcznej, a TryRefreshAsync wywołanie zostanie ponownie wyzwolone przez działanie aplikacji. Wywołanie TryRefreshAsync jest operacją no-op przed upływem skonfigurowanego czasu wygaśnięcia pamięci podręcznej, więc jej wpływ na wydajność jest minimalny, nawet jeśli jest często wywoływany.

Odświeżanie konfiguracji przy użyciu wstrzykiwania zależności

W poprzednim kodzie ręcznie zapisujesz wystąpienie elementu IConfigurationRefresher w celu wywołania metody TryRefreshAsync. Alternatywnie, jeśli używasz iniekcji zależności w celu rozwiązania usług, możesz odwołać się do poniższych kroków.

Zarejestruj wymagane usługi App Configuration Services, wywołując AddAzureAppConfiguration polecenie w witrynie IServiceCollection.

Dodaj następujący kod, aby Program.cs.
```
// Existing code in Program.cs
// ... ...

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

Odśwież konfigurację, rozpoznając wystąpienie IConfigurationRefresherProvider kolekcji usług i wywołując TryRefreshAsync każde z jego modułów odświeżania.

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

Lokalne kompilowanie i uruchamianie aplikacji

Ustaw zmienną środowiskową o nazwie Połączenie ionString i ustaw ją na klucz dostępu do magazynu usługi App Configuration. Jeśli używasz wiersza polecenia systemu Windows, uruchom następujące polecenie i uruchom ponownie wiersz polecenia, aby zezwolić na wprowadzenie zmian:
```
 setx ConnectionString "connection-string-of-your-app-configuration-store"
```
Jeśli używasz programu Windows PowerShell, uruchom następujące polecenie:
```
 $Env:ConnectionString = "connection-string-of-your-app-configuration-store"
```
Jeśli używasz systemu macOS lub Linux, uruchom następujące polecenie:
```
 export ConnectionString='connection-string-of-your-app-configuration-store'
```
Uruchom następujące polecenie, aby skompilować aplikację konsolową:
```
 dotnet build
```
Po pomyślnym zakończeniu kompilacji uruchom następujące polecenie, aby uruchomić aplikację lokalnie:
```
 dotnet run
```
Zaloguj się w witrynie Azure Portal. Wybierz pozycję Wszystkie zasoby i wybierz wystąpienie sklepu App Configuration utworzone w przewodniku Szybki start.
Wybierz pozycję Eksplorator konfiguracji i zaktualizuj wartości następujących kluczy:

Key Wartość

TestApp:Settings:Message Dane z konfiguracji aplikacja systemu Azure — zaktualizowano
Naciśnij klawisz Enter, aby wyzwolić odświeżanie i wydrukować zaktualizowaną wartość w wierszu polecenia lub oknie programu PowerShell.

Uwaga

Ponieważ czas wygaśnięcia pamięci podręcznej został ustawiony na 10 sekund przy użyciu SetCacheExpiration metody podczas określania konfiguracji operacji odświeżania, wartość ustawienia konfiguracji zostanie zaktualizowana tylko wtedy, gdy od czasu ostatniego odświeżenia tego ustawienia upłynął co najmniej 10 sekund.

Key	Wartość
TestApp:Settings:Message	Dane z konfiguracji aplikacja systemu Azure — zaktualizowano

Rejestrowanie i monitorowanie

Dzienniki są generowane podczas odświeżania konfiguracji i zawierają szczegółowe informacje na temat wartości kluczy pobranych ze sklepu App Configuration i zmian konfiguracji wprowadzonych w aplikacji. Jeśli masz aplikację ASP.NET Core, zapoznaj się z tymi instrukcjami dotyczącymi rejestrowania i monitorowania w programie ASP.NET Core. W przeciwnym razie możesz włączyć rejestrowanie, korzystając z instrukcji dotyczących rejestrowania za pomocą zestawu Azure SDK.

Dzienniki są danymi wyjściowymi na różnych poziomach zdarzeń. Domyślnym poziomem jest Informational.

Poziom zdarzenia	opis
Pełne informacje	Dzienniki zawierają klucz i etykietę klucz-wartości, które aplikacja monitoruje pod kątem zmian ze sklepu App Configuration. Informacje te obejmują również, czy wartość klucza uległa zmianie w porównaniu z tym, co aplikacja już załadowała. Włącz dzienniki na tym poziomie, aby rozwiązać problemy z aplikacją, jeśli zmiana konfiguracji nie wystąpiła zgodnie z oczekiwaniami.
Informacyjny	Dzienniki zawierają klucze ustawień konfiguracji zaktualizowanych podczas odświeżania konfiguracji. Wartości ustawień konfiguracji są pomijane z dziennika, aby uniknąć wycieku poufnych danych. Dzienniki można monitorować na tym poziomie, aby upewnić się, że aplikacja pobiera oczekiwane zmiany konfiguracji.
Ostrzeżenie	Dzienniki obejmują błędy i wyjątki, które wystąpiły podczas odświeżania konfiguracji. Sporadyczne wystąpienia mogą być ignorowane, ponieważ dostawca konfiguracji będzie nadal używać buforowanych danych i próbuje odświeżyć konfigurację przy następnym uruchomieniu. Dzienniki można monitorować na tym poziomie pod kątem powtarzających się ostrzeżeń, które mogą wskazywać na potencjalne problemy. Na przykład obracano parametry połączenia, ale nie pamiętano o aktualizowaniu aplikacji.

Rejestrowanie można włączyć na Verbose poziomie zdarzenia, określając EventLevel.Verbose parametr , jak pokazano w poniższym przykładzie. Te instrukcje dotyczą również wszystkich innych poziomów zdarzeń. W tym przykładzie włączono również dzienniki tylko dla Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh kategorii.

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

Kategoria rejestrowania to Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh, która jest wyświetlana przed każdym dziennikem. Oto kilka przykładowych dzienników na każdym poziomie zdarzenia:

[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'

Uwaga

Rejestrowanie jest dostępne, jeśli używasz wersji 6.0.0 lub nowszej dowolnego z następujących pakietów.

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

Czyszczenie zasobów

Jeśli nie chcesz nadal korzystać z zasobów utworzonych w tym artykule, usuń utworzoną tutaj grupę zasobów, aby uniknąć naliczania opłat.

Ważne

Usunięcie grupy zasobów jest nieodwracalne. Grupa zasobów i wszystkie zasoby w niej są trwale usuwane. Upewnij się, że nie usuniesz przypadkowo nieprawidłowej grupy zasobów ani zasobów. Jeśli zasoby dla tego artykułu zostały utworzone w grupie zasobów zawierającej inne zasoby, które chcesz zachować, usuń każdy zasób oddzielnie z odpowiedniego okienka zamiast usuwać grupę zasobów.

Zaloguj się do witryny Azure Portal i wybierz pozycję Grupy zasobów.
W polu Filtruj według nazwy wprowadź nazwę grupy zasobów.
Na liście wyników wybierz nazwę grupy zasobów, aby wyświetlić przegląd.
Wybierz pozycję Usuń grupę zasobów.
Zobaczysz prośbę o potwierdzenie usunięcia grupy zasobów. Wprowadź nazwę grupy zasobów, aby potwierdzić, a następnie wybierz pozycję Usuń.

Po kilku chwilach grupa zasobów i wszystkie jej zasoby zostaną usunięte.

Następne kroki

W tym samouczku włączono aplikację .NET w celu dynamicznego odświeżania ustawień konfiguracji z poziomu usługi App Configuration. Aby dowiedzieć się, jak używać tożsamości zarządzanej platformy Azure w celu usprawnienia dostępu do usługi App Configuration, przejdź do następnego samouczka.

Integracja tożsamości zarządzanej