Samouczek: używanie konfiguracji dynamicznej w aplikacji ASP.NET Core

2025-04-17

W tym samouczku pokazano, jak włączyć aktualizacje konfiguracji dynamicznej w aplikacji ASP.NET Core. Opiera się on na aplikacji internetowej wprowadzonej w przewodnikach Szybki start. Aplikacja będzie korzystać z biblioteki dostawcy usługi App Configuration na potrzeby wbudowanego buforowania konfiguracji i odświeżania. Przed kontynuowaniem najpierw zakończ tworzenie aplikacji ASP.NET Core za pomocą usługi App Configuration .

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

Skonfiguruj aplikację, aby aktualizowała swoją konfigurację w odpowiedzi na zmiany w App Configuration.
Wstrzyknij najnowszą konfigurację do swojej aplikacji.

Wymagania wstępne

Dokończ przewodnik szybkiego startu: Stwórz aplikację ASP.NET Core przy użyciu usługi App Configuration.

Ponowne ładowanie danych z usługi App Configuration

Otwórz Program.cs i zaktualizuj metodę AddAzureAppConfiguration dodaną podczas szybkiego startu. 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.

Należy użyć DefaultAzureCredential do uwierzytelnienia się w magazynie App Configuration. Podczas realizowania wymagań wstępnych w ramach Szybkiego startu przypisano już swoje poświadczenia do roli Czytelnik danych konfiguracji aplikacji.
```
// Load configuration from Azure App Configuration
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential())
           // Load all keys that start with `TestApp:` and have no label.
           .Select("TestApp:*", LabelFilter.Null)
           // Reload configuration if any selected key-values have changed.
           .ConfigureRefresh(refreshOptions =>
               refreshOptions.RegisterAll());
});
```
Metoda Select służy do ładowania wszystkich par klucz-wartość, których nazwa klucza zaczyna się od TestApp: i są bez etykiety. Metodę Select można wywołać więcej niż raz, aby załadować konfiguracje z różnymi prefiksami lub etykietami. Jeśli udostępniasz jeden sklep App Configuration z wieloma aplikacjami, takie podejście ułatwia ładowanie konfiguracji tylko dla bieżącej aplikacji zamiast ładowania wszystkich elementów ze sklepu.

Wewnątrz metody ConfigureRefresh wywołasz metodę RegisterAll, aby poinstruować dostawcę konfiguracji aplikacji o ponownym załadowaniu całej konfiguracji ilekroć wykryje zmianę w dowolnej z wybranych wartości kluczy (rozpoczynające się od TestApp: i bez etykiety). Aby uzyskać więcej informacji na temat monitorowania zmian konfiguracji, zobacz Najlepsze rozwiązania dotyczące odświeżania konfiguracji.

Napiwek

Możesz dodać wywołanie metody refreshOptions.SetRefreshInterval , aby określić minimalny czas między odświeżeniami konfiguracji. W tym przykładzie użyjesz wartości domyślnej 30 sekund. Dostosuj do wyższej wartości, jeśli musisz zmniejszyć liczbę żądań wysyłanych do magazynu App Configuration.

Dodaj oprogramowanie pośredniczące Azure App Configuration do kolekcji usług Twojej aplikacji.

Zaktualizuj Program.cs przy użyciu następującego kodu.

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

builder.Services.AddRazorPages();

// Add Azure App Configuration middleware to the container of services.
builder.Services.AddAzureAppConfiguration();

// Bind configuration "TestApp:Settings" section to the Settings object
builder.Services.Configure<Settings>(builder.Configuration.GetSection("TestApp:Settings"));

var app = builder.Build();

// The rest of existing code in program.cs
// ... ...

Wywołaj metodę UseAzureAppConfiguration . Umożliwia Twojej aplikacji automatyczne aktualizowanie konfiguracji za pomocą oprogramowania pośredniczącego App Configuration.

Zaktualizuj Program.cs przy użyciu następującego kodu.

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

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

// Use Azure App Configuration middleware for dynamic configuration refresh.
app.UseAzureAppConfiguration();

// The rest of existing code in program.cs
// ... ...

Podczas pracy z przewodnikiem "Szybki start" skonfigurowałeś swoją aplikację do używania wzorca opcji w programie ASP.NET Core. Gdy podstawowa konfiguracja Twojej aplikacji zostanie zaktualizowana z usługi App Configuration, silnie typizowany obiekt Settings uzyskany za pośrednictwem IOptionsSnapshot<T> zostaje automatycznie zaktualizowany. Należy pamiętać, że nie należy używać IOptions<T>, jeśli pożądana jest dynamiczna aktualizacja konfiguracji, ponieważ nie odczytuje danych konfiguracji po uruchomieniu aplikacji.

Odświeżanie konfiguracji opartej na żądaniach

Odświeżanie konfiguracji jest wyzwalane przez przychodzące żądania do aplikacji internetowej. W przypadku bezczynności aplikacji nie zostanie wykonane żadne odświeżanie. Gdy Twoja aplikacja jest aktywna, middleware App Configuration na bieżąco monitoruje klucze, które zarejestrowałeś do odświeżania w wywołaniu ConfigureRefresh. Oprogramowanie pośredniczące jest wyzwalane po każdym żądaniu przychodzącym do aplikacji. Jednak oprogramowanie pośredniczące będzie wysyłać żądania tylko w celu sprawdzenia wartości w usłudze App Configuration po upływie ustawionego interwału odświeżania.

Jeśli żądanie do usługi App Configuration dotyczące wykrywania zmian nie powiedzie się, aplikacja będzie nadal używać buforowanej konfiguracji. Nowe próby sprawdzenia zmian będą podejmowane okresowo, gdy do aplikacji będą napływać nowe żądania.
Odświeżanie konfiguracji odbywa się równolegle z procesem przetwarzania żądań przychodzących aplikacji. Nie spowoduje to zablokowania ani spowolnienia żądania przychodzącego, które wyzwoliło odświeżanie. Żądanie, które wyzwoliło odświeżanie, może nie uzyskać zaktualizowanych wartości konfiguracji, ale późniejsze żądania otrzymają nowe wartości konfiguracji.
Aby upewnić się, że oprogramowanie pośredniczące zostało wyzwolone, wywołaj metodę app.UseAzureAppConfiguration() tak wcześnie, jak to odpowiednie w potoku żądania, aby inne oprogramowanie pośredniczące jej nie pominęło w aplikacji.

Lokalne kompilowanie i uruchamianie aplikacji

Aby skompilować aplikację przy użyciu interfejsu wiersza polecenia platformy .NET, uruchom następujące polecenie w powłoce poleceń:
```
    dotnet build
```
Po pomyślnym zakończeniu kompilacji uruchom następujące polecenie, aby uruchomić aplikację internetową lokalnie:
```
    dotnet run
```
Otwórz okno przeglądarki i przejdź do adresu URL wyświetlanego w danych wyjściowych dotnet run .
Zaloguj się w witrynie Azure Portal. Wybierz pozycję Wszystkie zasoby i wybierz magazyn App Configuration, który utworzyłeś w szybkim przewodniku.

Wybierz Eksplorator konfiguracji i zaktualizuj wartości następujących kluczy.

Klucz	Wartość
TestApp:Ustawienia:Kolor tła	zielony
TestApp:Ustawienia:FontColor	jasnySzary
TestApp:Ustawienia:Wiadomość	Dane z usługi Azure App Configuration — teraz z aktualizacjami na żywo!

Odśwież przeglądarkę kilka razy. Gdy interwał odświeżania upłynie po 30 sekundach, strona będzie wyświetlana ze zaktualizowaną zawartością.

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.

Wartość domyślna ILoggerFactory jest dodawana automatycznie po services.AddAzureAppConfiguration() wywołaniu. Dostawca usługi App Configuration używa tego ILoggerFactory, aby utworzyć ILogger, które generuje te dzienniki. ASP.NET Core domyślnie używa ILogger funkcji rejestrowania, dlatego nie trzeba wprowadzać dodatkowych zmian kodu w celu włączenia rejestrowania dla dostawcy usługi App Configuration.

Dzienniki są generowane na różnych poziomach logów. Domyślnym poziomem jest Information.

Poziom logowania	opis
Debugowanie	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.
Informacja	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 Debug poziomie dziennika, dodając następujący przykład do appsettings.json pliku. Przykład ten dotyczy także wszystkich pozostałych poziomów dziennika.

"Logging": {
    "LogLevel": {
        "Microsoft.Extensions.Configuration.AzureAppConfiguration": "Debug"
    }
}

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 logowania:

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

info: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
    Setting updated. Key:'ExampleKey'

warn: Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh[0]
    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'

Użycie ILogger jest preferowaną metodą w aplikacjach ASP.NET i jest priorytetyzowane jako źródło rejestrowania, jeśli istnieje wystąpienie ILoggerFactory. Jednakże, jeśli ILoggerFactory nie jest dostępny, dzienniki można alternatywnie włączyć i skonfigurować zgodnie z instrukcjami dotyczącymi aplikacji platformy .NET Core. Aby uzyskać więcej informacji, zobacz Rejestrowanie na platformie .NET Core i ASP.NET Core.

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 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 umożliwiłeś swojej aplikacji internetowej ASP.NET Core dynamiczne odświeżanie ustawień konfiguracji z 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.

Uzyskiwanie dostępu do usługi App Configuration przy użyciu tożsamości zarządzanej

Udostępnij za pośrednictwem