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

Artykuł
02/28/2024

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 zaktualizować jej konfigurację w odpowiedzi na zmiany w magazynie usługi App Configuration.
Wstrzykiwanie najnowszej konfiguracji do aplikacji.

Wymagania wstępne

Zakończ przewodnik Szybki start: tworzenie aplikacji ASP.NET Core przy użyciu usługi App Configuration.

Dodawanie klucza sentinel

Klucz sentinel to klucz aktualizowany po zakończeniu zmiany wszystkich innych kluczy. Aplikacja monitoruje klucz sentinel. Po wykryciu zmiany aplikacja odświeża wszystkie wartości konfiguracji. Takie podejście pomaga zapewnić spójność konfiguracji w aplikacji i zmniejszyć ogólną liczbę żądań wysyłanych do magazynu usługi App Configuration w porównaniu do monitorowania wszystkich kluczy pod kątem zmian.

W witrynie Azure Portal otwórz sklep App Configuration Store i wybierz pozycję Eksplorator konfiguracji Utwórz > klucz-wartość>.
W polu Klucz wprowadź ciąg TestApp:Ustawienia:Sentinel. W polu Wartość wprowadź wartość 1. Pozostaw pole Etykieta i Typ zawartości puste.
Wybierz Zastosuj.

Ponowne ładowanie danych z usługi App Configuration

Otwórz Program.cs i zaktualizuj AddAzureAppConfiguration metodę dodaną wcześniej podczas przewodnika Szybki start.
```
// Load configuration from Azure App Configuration
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(connectionString)
           // Load all keys that start with `TestApp:` and have no label
           .Select("TestApp:*", LabelFilter.Null)
           // Configure to reload configuration if the registered sentinel key is modified
           .ConfigureRefresh(refreshOptions =>
                refreshOptions.Register("TestApp:Settings:Sentinel", refreshAll: true));
});
```
Metoda Select służy do ładowania wszystkich wartości klucz-wartości, których nazwa klucza zaczyna się od TestApp: i które nie mają 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.

W metodzie ConfigureRefresh rejestrujesz klucze, które chcesz monitorować pod kątem zmian w magazynie usługi App Configuration. Parametr refreshAll metody Register wskazuje, że wszystkie konfiguracje określone przez Select metodę zostaną ponownie załadowane, jeśli zarejestrowany klucz ulegnie zmianie.

Napiwek

Możesz dodać wywołanie metody refreshOptions.SetCacheExpiration , 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 usługi App Configuration.

Dodaj oprogramowanie pośredniczące aplikacja systemu Azure Configuration do kolekcji usług 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 aplikacji automatyczne aktualizowanie konfiguracji przy użyciu 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 skonfigurowaliśmy aplikację do używania wzorca opcji w programie ASP.NET Core . Gdy podstawowa konfiguracja aplikacji zostanie zaktualizowana z poziomu usługi App Configuration, silnie typizowanego Settings obiektu uzyskanego za pośrednictwem IOptionsSnapshot<T> zostanie automatycznie zaktualizowany. Należy pamiętać, że nie należy używać IOptions<T> aktualizacji konfiguracji dynamicznej, 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 aplikacja jest aktywna, oprogramowanie pośredniczące App Configuration monitoruje klucz sentinel lub inne klucze zarejestrowane 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 czasu wygaśnięcia pamięci podręcznej.

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, czy zmiany zostaną wprowadzone okresowo, gdy do aplikacji będą wysyłane nowe żądania przychodzące.
Odświeżanie konfiguracji odbywa się asynchronicznie do 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() odpowiednio w potoku żądania, aby inne oprogramowanie pośredniczące nie pominąło go 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 został utworzony w przewodniku Szybki start.

Wybierz pozycję Eksplorator konfiguracji i zaktualizuj wartości następujących kluczy. Pamiętaj, aby zaktualizować klucz sentinel w końcu.

Key	Wartość
TestApp:Settings:BackgroundColor	zielony
TestApp:Settings:FontColor	lightGray
TestApp:Settings:Message	Dane z usługi Azure App Configuration — teraz z aktualizacjami na żywo!
TestApp:Ustawienia:Sentinel	2

Odśwież przeglądarkę kilka razy. Gdy pamięć podręczna wygaśnie po 30 sekundach, na stronie zostanie wyświetlona zaktualizowana zawartość.

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 polecenia do utworzenia ILoggerwystąpienia klasy , 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ą danymi wyjściowymi na różnych poziomach dziennika. Domyślnym poziomem jest Information.

Poziom dziennika	opis
Debugowanie	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.
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. 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 Debug poziomie dziennika, dodając następujący przykład do appsettings.json pliku. Ten przykład dotyczy również wszystkich innych 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 dziennikem. Oto kilka przykładowych dzienników na każdym poziomie dziennika:

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 priorytetem jako źródło rejestrowania ILoggerFactory , jeśli istnieje wystąpienie. Jeśli ILoggerFactory jednak dzienniki nie są dostępne, można również włączyć i skonfigurować za pomocą instrukcji dotyczących 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 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ę internetową ASP.NET Core 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.

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