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

  • Článek

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 kurzu se naučíte:

  • 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 ještě nemáte předplatné Azure, vytvořte si bezplatný účet Azure před tím, než začnete.

Dokončete rychlý start – Vytvoření aplikace .NET pomocí služby App Configuration.

Aktualizace konfigurace řízené aktivitami

Otevřete Program.cs a aktualizujte soubor následujícím kódem.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Configuration.AzureAppConfiguration;

IConfiguration _configuration = null;
IConfigurationRefresher _refresher = null;

var builder = new ConfigurationBuilder();
builder.AddAzureAppConfiguration(options =>
{
    options.Connect(Environment.GetEnvironmentVariable("ConnectionString"))
            .ConfigureRefresh(refresh =>
            {
                refresh.Register("TestApp:Settings:Message")
                       .SetCacheExpiration(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 V metodě je pro monitorování změn zaregistrovaný klíč v obchodě App Configuration Store. Metoda Register má volitelný logický parametr refreshAll , který lze použít k označení, zda se mají aktualizovat všechny hodnoty konfigurace, pokud se registrovaný klíč změní. V tomto příkladu se aktualizuje pouze klíč TestApp:Nastavení:Message. Metoda SetCacheExpiration 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ším pokusem je provést, když vypršela nakonfigurovaná doba vypršení platnosti mezipaměti a TryRefreshAsync volání se znovu aktivuje vaší aktivitou aplikace. Volání TryRefreshAsync je no-op před uplynutím nakonfigurovaného času vypršení platnosti mezipaměti, 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 vyvolání TryRefreshAsync. Pokud k vyřešení služeb používáte injektáž závislostí, můžete na tyto kroky odkazovat.

  1. 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();

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

  1. Nastavte proměnnou prostředí s názvem Připojení ionString a nastavte ji na přístupový klíč do obchodu App Configuration Store. 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 ConnectionString "connection-string-of-your-app-configuration-store"

    Pokud používáte Windows PowerShell, spusťte následující příkaz:

     $Env:ConnectionString = "connection-string-of-your-app-configuration-store"

    Pokud používáte macOS nebo Linux, spusťte následující příkaz:

     export ConnectionString='connection-string-of-your-app-configuration-store'

  2. Spuštěním následujícího příkazu sestavte konzolovou aplikaci:

     dotnet build

  3. Po úspěšném dokončení sestavení spusťte aplikaci místně spuštěním následujícího příkazu:

     dotnet run

    Quickstart app launch local

  4. Přihlaste se k portálu Azure. Vyberte Všechny prostředky a vyberte instanci app Configuration Storu, kterou jste vytvořili v rychlém startu.

  5. Vyberte Configuration Explorer a aktualizujte hodnoty následujících klíčů:

    Key Hodnota
    TestApp:Nastavení:Message Data z konfigurace Aplikace Azure – aktualizována

  6. Stisknutím klávesy Enter aktivujte aktualizaci a vytiskněte aktualizovanou hodnotu v příkazovém řádku nebo okně PowerShellu.

    Quickstart app refresh local

    Poznámka:

    Vzhledem k tomu, že doba vypršení platnosti mezipaměti byla nastavena na 10 sekund pomocí SetCacheExpiration metody při zadávání konfigurace operace aktualizace, hodnota pro nastavení konfigurace se aktualizuje pouze v případě, že uplynulo nejméně 10 sekund od poslední aktualizace pro toto nastavení.

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. 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
    Podrobnosti 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 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 protokoly pouze Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh pro kategorii.

    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

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