Kurz: Použití dynamické konfigurace v aplikaci ASP.NET Core

2025-04-17

V tomto kurzu se dozvíte, jak povolit dynamické aktualizace konfigurace v aplikaci ASP.NET Core. Vychází z webové aplikace představené v rychlých návodech. Vaše aplikace bude využívat knihovnu zprostředkovatele konfigurace aplikace pro integrované možnosti ukládání do mezipaměti a aktualizace konfigurace. Než budete pokračovat, nejprve dokončete vytvoření aplikace ASP.NET Core s konfigurací aplikace.

V tomto kurzu se naučíte:

Nastavte aplikaci tak, aby aktualizovala konfiguraci v reakci na změny v App Configuration Storu.
Vložte do aplikace nejnovější konfiguraci.

Požadavky

Dokončete rychlý start: Vytvoření aplikace ASP.NET Core s App Configuration.

Opětovné načtení dat z konfigurace aplikace

Otevřete Program.cs a aktualizujte metodu AddAzureAppConfiguration , kterou jste přidali během rychlého startu. Můžete se připojit k App Configuration pomocí Microsoft Entra ID (doporučeno) nebo pomocí připojovacího řetězce. Následující fragment kódu ukazuje použití Microsoft Entra ID.

Použijete DefaultAzureCredential pro ověření do služby App Configuration. Během dokončování rychlého průvodce uvedeného v požadavcích jste už přiřadili svému pověření roli čtenáře dat konfigurace aplikace.
```
// 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 se používá k načtení všech hodnot klíče, jejichž název klíče začíná testApp: a nemají žádný popisek. Metodu Select můžete volat vícekrát, aby bylo možné načíst konfigurace s různými předponami nebo popisky. Pokud sdílíte jeden obchod s konfigurací aplikací s více aplikacemi, pomůže vám tento přístup načíst konfiguraci jenom relevantní pro vaši aktuální aplikaci, a ne načítat všechno z vašeho storu.

ConfigureRefresh Uvnitř metody zavoláte metoduRegisterAll, která zprostředkovateli konfigurace aplikace dá pokyn, aby znovu načítal celou konfiguraci, kdykoli zjistí změnu v některé z vybraných hodnot klíče (ty, které začínají testAppem: a nemají žádný popisek). Pro více informací o sledování změn konfigurace viz Nejlepší praxe pro aktualizaci konfigurace.

Návod

Do metody můžete přidat volání refreshOptions.SetRefreshInterval , které určuje minimální čas mezi aktualizacemi konfigurace. V tomto příkladu použijete výchozí hodnotu 30 sekund. Pokud potřebujete snížit počet požadavků provedených ve službě App Configuration Store, upravte hodnotu na vyšší hodnotu.

Přidejte middleware Azure App Configuration do kolekce služeb vaší aplikace.

Aktualizujte Program.cs následujícím kódem.

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

Zavolejte metodu UseAzureAppConfiguration . Umožňuje vaší aplikaci automaticky aktualizovat konfiguraci pomocí middlewaru App Configuration.

Aktualizujte Program.cs následujícím kódem.

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

Aplikaci jste nastavili tak, aby používala vzor možností v ASP.NET Core během rychlého startu. Když se základní konfigurace vaší aplikace aktualizuje z App Configuration, objekt se silným typem Settings získaný prostřednictvím IOptionsSnapshot<T> se automaticky aktualizuje. Mějte na paměti, že byste neměli používat IOptions<T>, pokud je požadovaná dynamická aktualizace konfigurace, protože po spuštění aplikace nečte konfigurační data.

Aktualizace konfigurace řízená požadavky

Aktualizace konfigurace se aktivuje příchozími požadavky vaší webové aplikace. Pokud je vaše aplikace nečinná, nedojde k žádné aktualizaci. Když je vaše aplikace aktivní, Konfigurace aplikace monitoruje middleware všechny klíče, které jste zaregistrovali pro aktualizaci v rámci volání ConfigureRefresh. Middleware se aktivuje při každém příchozím požadavku do vaší aplikace. Middleware však pošle požadavky na kontrolu hodnoty v App Configuration pouze tehdy, když uplynul vámi nastavený interval aktualizace.

Pokud požadavek na konfiguraci aplikace pro detekci změn selže, vaše aplikace bude dál používat konfiguraci uloženou v mezipaměti. Nové pokusy o kontrolu změn se budou pravidelně provádět, pokud budou vaší aplikaci přicházet nové požadavky.
Aktualizace konfigurace probíhá asynchronně ke zpracování příchozích požadavků vaší aplikace. Příchozí požadavek, který aktivoval aktualizaci, nezablokuje ani nezpomalí. Požadavek, který aktivoval aktualizaci, nemusí získat aktualizované hodnoty konfigurace, ale později požadavky získají nové hodnoty konfigurace.
Pokud chcete zajistit, aby se middleware aktivoval, zavolejte metodu app.UseAzureAppConfiguration() co nejdříve v kanálu požadavku, aby ho jiný middleware ve vaší aplikaci nepřeskočil.

Sestavení a místní spuštění aplikace

Pokud chcete aplikaci sestavit pomocí rozhraní příkazového řádku .NET CLI, spusťte v příkazovém prostředí následující příkaz:
```
    dotnet build
```
Po úspěšném dokončení sestavení spusťte místně webovou aplikaci spuštěním následujícího příkazu:
```
    dotnet run
```
Otevřete okno prohlížeče a přejděte na adresu URL zobrazenou ve výstupu dotnet run .
Přihlaste se k portálu Azure. Vyberte Všechny prostředky a vyberte obchod App Configuration, který jste vytvořili v rychlém startu.

Vyberte Průzkumníka konfigurace a aktualizujte hodnoty následujících klíčů.

Klíč	Hodnota
TestApp:Nastavení:Barva pozadí	zelená
TestApp:Nastavení:Barva písma	světle šedá
TestApp:Nastavení:Zpráva	Data z konfigurace Aplikace Azure – nyní s živými aktualizacemi!

Několikrát aktualizujte prohlížeč. Po uplynutí intervalu aktualizace po 30 sekundách se zobrazí stránka s aktualizovaným obsahem.

Protokolování a monitorování

Logy jsou výstupem při aktualizaci konfigurace a obsahují podrobné informace o párech klíč-hodnota načtených z vašeho úložiště konfigurace aplikace a o změnách konfigurace provedených ve vaší aplikaci.

Automaticky se přidá ILoggerFactory výchozí při vyvolání services.AddAzureAppConfiguration(). Zprostředkovatel konfigurace aplikace používá tento ILoggerFactory k vytvoření instance ILogger, která vypíše tyto protokoly. ASP.NET Core používá ILogger protokolování ve výchozím nastavení, takže nemusíte provádět další změny kódu, abyste povolili protokolování pro poskytovatele konfigurace aplikace.

Protokoly jsou generovány na různých úrovních protokolování. Výchozí úroveň je Information.

Úroveň protokolu	Popis
Ladění	Protokoly obsahují klíč a popisek klíčů hodnot, které vaše aplikace monitoruje kvůli změnám z úložiště konfigurace aplikace. Informace také zahrnují, jestli se hodnota klíče změnila v porovnání s tím, co už vaše aplikace načetla. Povolte protokoly na této úrovni, abyste mohli řešit potíže s aplikací, pokud nedošlo ke změně konfigurace podle očekávání.
Informace	Záznamy zahrnují klíče nastavení konfigurace, které byly aktualizovány při aktualizaci konfigurace. Hodnoty nastavení konfigurace se v protokolu vynechávají, aby nedošlo k úniku citlivých dat. Protokoly můžete monitorovat na této úrovni, abyste zajistili, že vaše aplikace převezme očekávané změny konfigurace.
Varování	Protokoly zahrnují selhání a výjimky, ke kterým došlo během aktualizace konfigurace. Občasné výskyty se dají ignorovat, protože zprostředkovatel konfigurace bude dál používat data uložená v mezipaměti a při příštím pokusu o aktualizaci konfigurace. Na této úrovni můžete monitorovat protokoly s opakovanými upozorněními, která můžou značit potenciální problémy. Například jste otočili připojovací řetězec, ale zapomněli jste aktualizovat aplikaci.

Protokolování můžete povolit na Debug úrovni protokolu přidáním následujícího příkladu do appsettings.json souboru. Tento příklad platí i pro všechny ostatní úrovně protokolu.

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

Kategorie protokolování je Microsoft.Extensions.Configuration.AzureAppConfiguration.Refresh, která se zobrazí před každým protokolem. Tady je několik ukázkových protokolů na každé úrovni protokolu:

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'

Použití ILogger je upřednostňovanou metodou v ASP.NET aplikací a je určena jako zdroj protokolování, pokud je k dispozici instance ILoggerFactory . Pokud ale ILoggerFactory není k dispozici, je možné protokoly povolit a nakonfigurovat pomocí pokynů pro aplikace .NET Core. Další informace najdete v tématu protokolování v .NET Core a ASP.NET Core.

Poznámka:

Protokolování je k dispozici, pokud používáte verzi 6.0.0 nebo novější z následujících balíčků.

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

Vyčistěte prostředky

Pokud nechcete dál používat prostředky vytvořené v tomto článku, odstraňte skupinu prostředků, kterou jste tady vytvořili, abyste se vyhnuli poplatkům.

Důležité

Odstranění skupiny prostředků je nevratné. Skupina prostředků a všechny prostředky v ní se trvale odstraní. Ujistěte se, že omylem nevymažete nesprávnou skupinu prostředků nebo prostředky. Pokud jste vytvořili prostředky pro tento článek ve skupině prostředků, která obsahuje další prostředky, které chcete zachovat, odstraňte jednotlivé prostředky z příslušného podokna místo odstranění skupiny prostředků.

Přihlaste se k webu Azure Portal a vyberte skupiny prostředků.
Do pole Filtrovat podle názvu zadejte název vaší skupiny prostředků.
V seznamu výsledků vyberte název skupiny prostředků, abyste zobrazili přehled.
Vyberte Odstranit skupinu prostředků.
Zobrazí se výzva k potvrzení odstranění skupiny prostředků. Potvrďte název skupiny prostředků a vyberte Odstranit.

Po chvíli se skupina prostředků a všechny její prostředky odstraní.

Další kroky

V tomto kurzu jste povolili webovou aplikaci ASP.NET Core tak, aby dynamicky aktualizovala nastavení konfigurace z konfigurace aplikace. Pokud se chcete dozvědět, jak pomocí identity spravované Azure zjednodušit přístup ke službě App Configuration, pokračujte dalším kurzem.

Přístup ke konfiguraci aplikace pomocí spravované identity