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

  • Článek

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 startech. 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 pomocí konfigurace aplikace.

Přidání klíče sentinelu

Klíč sentinelu je klíč, který aktualizujete po dokončení změny všech ostatních klíčů. Vaše aplikace monitoruje klíč sentinelu. Když se zjistí změna, aplikace aktualizuje všechny konfigurační hodnoty. Tento přístup pomáhá zajistit konzistenci konfigurace ve vaší aplikaci a snížit celkový počet požadavků provedených v obchodě App Configuration Store v porovnání s monitorováním všech klíčů pro změny.

  1. Na webu Azure Portal otevřete obchod App Configuration Store a vyberte Configuration Explorer Create Key-value (Vytvořit > klíč v Průzkumníku > konfigurace).
  2. Jako klíč zadejte TestApp:Nastavení:Sentinel. Jako hodnotu zadejte 1. Ponechte popisek a typ obsahu prázdný.
  3. Vyberte Použít.

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

  1. Otevřete Program.cs a aktualizujte metodu AddAzureAppConfiguration , kterou jste přidali dříve během rychlého startu.

    // 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 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 a 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 V metodě zaregistrujete klíče, které chcete monitorovat o změnách v App Configuration Storu. Parametr refreshAllRegister metody označuje, že všechny konfigurace, které jste zadali metodou Select , se znovu načtou, pokud se registrovaný klíč změní.

    Tip

    Do metody můžete přidat volání refreshOptions.SetCacheExpiration , 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.

  2. Do kolekce služeb vaší aplikace přidejte middleware Aplikace Azure Configuration.

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

  3. 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 konfigurace aplikace, objekt silného Settings typu získaný prostřednictvím IOptionsSnapshot<T> se automaticky aktualizuje. Mějte na IOptions<T> paměti, že byste neměli používat, 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í, middleware Konfigurace aplikace monitoruje klíč sentinelu nebo jakékoli jiné klíče, které jste zaregistrovali k aktualizaci ve ConfigureRefresh volání. Middleware se aktivuje při každém příchozím požadavku do vaší aplikace. Middleware ale bude odesílat požadavky pouze na kontrolu hodnoty v App Configuration, pokud vypršela doba vypršení platnosti mezipaměti, kterou jste nastavili.

  • 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, zatímco ve vaší aplikaci probíhají nové příchozí 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

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

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

  3. Otevřete okno prohlížeče a přejděte na adresu URL zobrazenou ve výstupu dotnet run .

    Launching quickstart app locally

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

  5. Vyberte Průzkumníka konfigurace a aktualizujte hodnoty následujících klíčů. Nezapomeňte nakonec aktualizovat klíč sentinelu.

    Key Hodnota
    TestApp:Nastavení:BackgroundColor zelená
    TestApp:Nastavení:FontColor lightGray
    TestApp:Nastavení:Message Data z konfigurace Aplikace Azure – nyní s živými aktualizacemi!
    TestApp:Nastavení:Sentinel 2

  6. Několikrát aktualizujte prohlížeč. Když po 30 sekundách vyprší platnost mezipaměti, zobrazí se stránka s aktualizovaným obsahem.

    Launching updated quickstart app locally

Protokolování a monitorování

Protokoly jsou výstupem při aktualizaci konfigurace a obsahují podrobné informace o hodnotách klíčů načtených z úložiště app Configuration Store a změn konfigurace provedených ve vaší aplikaci.

  • Při vyvolání se automaticky services.AddAzureAppConfiguration() přidá výchozí hodnotaILoggerFactory. Zprostředkovatel konfigurace aplikace to ILoggerFactory používá k vytvoření instance , která ILoggertyto protokoly vypíše. 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 výstupem na různých úrovních protokolu. Výchozí úroveň je Information.

    Úroveň protokolu Popis
    Ladění Protokoly obsahují klíč a popisek hodnot klíčů, které vaše aplikace monitoruje změny z obchodu App Configuration Store. 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í Protokoly zahrnují klíče nastavení konfigurace aktualizované během aktualizace 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.
    Upozorňující Mezi protokoly patří 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 ILoggerFactory ale není k dispozici, protokoly je možné 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čištění prostředků

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 neodstraníte 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ů.

  1. Přihlaste se k webu Azure Portal a vyberte skupiny prostředků.
  2. Do pole Filtrovat podle názvu zadejte název vaší skupiny prostředků.
  3. V seznamu výsledků vyberte název skupiny prostředků, abyste zobrazili přehled.
  4. Vyberte Odstranit skupinu prostředků.
  5. 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