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

2025-04-17

Knihovna zprostředkovatele .NET služby App Configuration podporuje aktualizaci konfigurace na vyžádání, aniž by to způsobilo restartování aplikace. V tomto kurzu se dozvíte, jak v kódu implementovat dynamické aktualizace konfigurace. Sestavuje se v aplikaci představené v rychlém startu. Než budete pokračovat, měli byste dokončit vytvoření aplikace .NET s konfigurací aplikace .

Kroky v tomto kurzu můžete provést pomocí libovolného editoru kódu. Visual Studio Code je vynikající volbou, která je dostupná na platformách Windows, macOS a Linux.

V tomto návodu se naučíte, jak:

Nastavte aplikaci .NET tak, aby aktualizovala konfiguraci v reakci na změny v obchodě App Configuration Store.
Využití nejnovější konfigurace ve vaší aplikaci

Požadavky

Pokud nemáte účet Azure, vytvořte si bezplatný účet před tím, než začnete.

Dokončete rychlý úvod Vytvořte aplikaci .NET pomocí App Configuration.

Aktualizace konfigurace řízené aktivitami

Otevřete Program.cs a aktualizujte soubor následujícím kódem. 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.

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 Uvnitř metody zavoláte metoduRegisterAll, která zprostředkovateli konfigurace aplikace dá pokyn, aby znovu načítá celou konfiguraci, kdykoli zjistí změnu v některé z vybraných hodnot klíčů (v tomto případě pouze TestApp:Settings:Message). Pro více informací o sledování změn konfigurace viz Nejlepší praxe pro aktualizaci konfigurace.

Metoda SetRefreshInterval určuje minimální čas, který musí uplynout před provedením nového požadavku do služby App Configuration, aby se zkontrolovaly všechny změny konfigurace. V tomto příkladu přepíšete výchozí dobu vypršení platnosti 30 sekund a místo toho zadáte čas 10 sekund pro demonstrační účely.

ConfigureRefresh Volání samotné metody nezpůsobí automatickou aktualizaci konfigurace. Zavoláte metodu TryRefreshAsync z rozhraní IConfigurationRefresher , která aktivuje aktualizaci. Tento návrh spočívá v tom, že se vyhnete požadavkům odesílaným do služby App Configuration, i když je vaše aplikace nečinná. Budete chtít zahrnout TryRefreshAsync volání, ve kterém považujete vaši aplikaci za aktivní. Může to být například při zpracování příchozí zprávy, pořadí nebo iterace složité úlohy. Může být také v časovači, pokud je vaše aplikace aktivní po celou dobu. V tomto příkladu voláte TryRefreshAsync pokaždé, když stisknete klávesu Enter. I když volání TryRefreshAsync z nějakého důvodu selže, vaše aplikace bude dál používat konfiguraci uloženou v mezipaměti. Další pokus se provede, když se předá nakonfigurovaný interval aktualizace a TryRefreshAsync volání se znovu aktivuje aktivitou vaší aplikace. Volání TryRefreshAsync je no-op před uplynutím nakonfigurovaného intervalu aktualizace, takže jeho dopad na výkon je minimální, i když se volá často.

Aktualizace konfigurace pomocí injektáže závislostí

V předchozím kódu ručně ukládáte instanci IConfigurationRefresher k vyvolání TryRefreshAsync. Pokud k vyřešení služeb používáte vkládání závislostí, můžete postupovat podle těchto kroků.

Zaregistrujte požadované služby App Configuration tím AddAzureAppConfiguration , že na svém zařízení vyvoláte IServiceCollection.

Do Program.cs přidejte následující kód.
```
// Existing code in Program.cs
// ... ...

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

Aktualizujte konfiguraci tak, že přeložíte instanci IConfigurationRefresherProvider z kolekce služeb a vyvoláte TryRefreshAsync každou z jejích aktualizačních rutin.

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

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

Nastavte proměnnou prostředí s názvem Koncový bod na koncový bod úložiště app Configuration, který najdete v části Přehled obchodu na webu Azure Portal.

Pokud používáte příkazový řádek systému Windows, spusťte následující příkaz a restartujte příkazový řádek, aby se změna projevila:
```
setx Endpoint "<endpoint-of-your-app-configuration-store>"
```
Pokud používáte PowerShell, spusťte následující příkaz:
```
$Env:Endpoint = "<endpoint-of-your-app-configuration-store>"
```
Pokud používáte macOS nebo Linux, spusťte následující příkaz:
```
export Endpoint='<endpoint-of-your-app-configuration-store>'
```
Spuštěním následujícího příkazu sestavte konzolovou aplikaci:
```
 dotnet build
```
Po úspěšném dokončení sestavení spusťte aplikaci místně spuštěním následujícího příkazu:
```
 dotnet run
```
Přihlaste se do Azure Portalu. Vyberte Všechny prostředky a vyberte instanci App Configuration Store, kterou jste vytvořili v průvodci rychlým startem.
Vyberte Configuration Explorer a aktualizujte hodnoty následujících klíčů:

Klíč Hodnota

TestApp:Nastavení:Zpráva Data z Azure App Configuration – aktualizováno
Stisknutím klávesy Enter aktivujte aktualizaci a vytiskněte aktualizovanou hodnotu v příkazovém řádku nebo okně PowerShellu.

Poznámka:

Vzhledem k tomu, že interval aktualizace byl nastaven na 10 sekund pomocí SetRefreshInterval metody při zadávání konfigurace pro operaci aktualizace, hodnota pro nastavení konfigurace bude aktualizována pouze v případě, že uplynulo nejméně 10 sekund od poslední aktualizace pro toto nastavení.

Klíč	Hodnota
TestApp:Nastavení:Zpráva	Data z Azure App Configuration – aktualizováno

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. Pokud máte aplikaci ASP.NET Core, přečtěte si tyto pokyny pro protokolování a monitorování v ASP.NET Core. V opačném případě můžete protokolování povolit pomocí pokynů pro protokolování pomocí sady Azure SDK.

Protokoly jsou výstupem na různých úrovních událostí. Výchozí úroveň je Informational.

Úroveň události	Popis
Zdlouhavý	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í.
Informační	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.
Výstraha	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 Verbose úrovni události zadáním parametru EventLevel.Verbose , jak je to provedeno v následujícím příkladu. Tyto pokyny platí i pro všechny ostatní úrovně událostí. Tento příklad také umožňuje záznamy pouze pro 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);

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 jednotlivých úrovních událostí:

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

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

Upravte zdroje

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í. Dávejte pozor, abyste omylem neodstranili nesprávnou skupinu prostředků nebo jednotlivé 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 zdrojů.
Zobrazí se výzva k potvrzení odstranění skupiny prostředků. Potvrďte název skupiny prostředků a vyberte Odstranit.

Po několika okamžicích se skupina prostředků a všechny její prostředky vymažou.

Další kroky

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

Integrace spravované identity