Samouczek: używanie konfiguracji dynamicznej w aplikacji .NET

Biblioteka dostawcy .NET usługi App Configuration obsługuje aktualizowanie konfiguracji na żądanie bez powodowania ponownego uruchomienia aplikacji. W tym samouczku pokazano, jak wdrożyć aktualizacje konfiguracji dynamicznej w 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 działania:

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 jeszcze konta platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.

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. Możesz nawiązać połączenie z usługą App Configuration przy użyciu Microsoft Entra ID (zalecane) lub ciągu połączenia. Poniższy fragment kodu przedstawia użycie identyfikatora Entra firmy Microsoft.

Aby się uwierzytelnić w sklepie App Configuration, używasz DefaultAzureCredential. Podczas realizowania wymagań wstępnych w ramach Szybkiego startu przypisano już swoje poświadczenia do roli Czytelnik danych konfiguracji aplikacji.

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

IConfiguration _configuration = null;
IConfigurationRefresher _refresher = null;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    string endpoint = Environment.GetEnvironmentVariable("Endpoint"); 
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())            
           // Load the key-value with key "TestApp:Settings:Message" and no label
           .Select("TestApp:Settings:Message")
           // Reload configuration if any selected key-values have changed.
           .ConfigureRefresh(refresh =>
           {
               refresh.RegisterAll()
                      .SetRefreshInterval(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!");

}

ConfigureRefresh Wewnątrz metody wywołasz RegisterAll metodę , aby poinstruować dostawcę usługi App Configuration o ponownym załadowaniu całej konfiguracji za każdym razem, gdy wykryje zmianę w dowolnej z wybranych wartości klucza (w tym przypadku wystarczy testApp:Settings:Message). Aby uzyskać więcej informacji na temat monitorowania zmian konfiguracji, zobacz Najlepsze rozwiązania dotyczące odświeżania konfiguracji.

Metoda SetRefreshInterval 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 tam, gdzie uznajesz swoją aplikację za aktywną. 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 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 przekazaniu skonfigurowanego interwału odświeżania, a TryRefreshAsync wywołanie zostanie ponownie wyzwolone przez działanie aplikacji. Wywołanie TryRefreshAsync jest no-op, zanim upłynie skonfigurowany interwał odświeżania, więc jego wpływ na wydajność jest minimalny, nawet jeśli jest często wykonywane.

Odświeżanie konfiguracji za pomocą 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 do 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 z kolekcji usług i wywołując TryRefreshAsync na każdym z jego odświeżaczy.

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 Endpoint na punkt końcowy magazynu App Configuration znalezionego w obszarze Przegląd sklepu w witrynie Azure Portal.

Jeśli używasz wiersza polecenia systemu Windows, uruchom następujące polecenie i uruchom ponownie wiersz polecenia, aby zezwolić na wprowadzenie zmian:
```
setx Endpoint "<endpoint-of-your-app-configuration-store>"
```
Jeśli używasz programu PowerShell, uruchom następujące polecenie:
```
$Env:Endpoint = "<endpoint-of-your-app-configuration-store>"
```
Jeśli używasz systemu macOS lub Linux, uruchom następujące polecenie:
```
export Endpoint='<endpoint-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ę do witryny Azure Portal. Wybierz pozycję Wszystkie zasoby i wybierz wystąpienie sklepu App Configuration utworzone w przewodniku Szybki start.
Wybierz Eksplorator konfiguracji i zaktualizuj wartości następujących kluczy:

Klawisz Wartość

TestApp:Ustawienia:Wiadomość Dane z usługi Azure App Configuration — zaktualizowano
Naciśnij Enter, aby wyzwolić odświeżanie i wydrukować zaktualizowaną wartość w wierszu polecenia lub oknie programu PowerShell.

Uwaga

Ponieważ interwał odświeżania został ustawiony na 10 sekund przy użyciu SetRefreshInterval metody podczas określania konfiguracji operacji odświeżania, wartość ustawienia konfiguracji zostanie zaktualizowana tylko wtedy, gdy od ostatniego odświeżenia tego ustawienia upłynął co najmniej 10 sekund.

Klawisz	Wartość
TestApp:Ustawienia:Wiadomość	Dane z usługi Azure App Configuration — 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.

Logi są generowane na różnych poziomach zdarzeń. Domyślnym poziomem jest Informational.

Poziom zdarzenia	Opis
Pełne informacje	Dzienniki zawierają klucz i etykietę wartości kluczy, które aplikacja monitoruje pod kątem zmian w repozytorium 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. Można monitorować dzienniki na tym poziomie, aby mieć pewność, że aplikacja odbiera 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ń. Również w tym przykładzie włączono dzienniki tylko dla kategorii Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh.

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 dziennikiem. 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

Uprzątnij zasoby

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 niewłaściwej grupy zasobów lub 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.
Poproszono Cię 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

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-04-17