Zelfstudie: Dynamische configuratie gebruiken in een .NET-app

Artikel
02/20/2024

De .NET-providerbibliotheek van App Configuration ondersteunt het bijwerken van configuratie op aanvraag zonder dat een toepassing opnieuw wordt opgestart. In deze zelfstudie leert hoe u dynamische configuratie-updates kunt implementeren in uw code. Het bouwt voort op de app die is geïntroduceerd in de quickstart. U moet een .NET-app maken met App Configuration voltooien voordat u doorgaat.

U kunt elke code-editor gebruiken om de stappen in deze zelfstudie uit te voeren. Visual Studio Code is een uitstekende optie die beschikbaar is op de Windows-, macOS- en Linux-platforms.

In deze zelfstudie leert u het volgende:

Stel uw .NET-app in om de configuratie bij te werken als reactie op wijzigingen in een App Configuration-archief.
De meest recente configuratie in uw toepassing gebruiken.

Vereisten

Als u geen Azure-abonnement hebt, kunt u een gratis Azure-account maken voordat u begint.

Voltooi de quickstart Een .NET-app maken met App Configuration.

Activiteitsgestuurde configuratie vernieuwen

Open Program.cs en werk het bestand bij met de volgende code.

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!");

}

In de ConfigureRefresh methode wordt een sleutel in uw App Configuration-archief geregistreerd voor wijzigingscontrole. De Register methode heeft een optionele Booleaanse parameter refreshAll die kan worden gebruikt om aan te geven of alle configuratiewaarden moeten worden vernieuwd als de geregistreerde sleutel verandert. In dit voorbeeld wordt alleen de sleutel TestApp:Instellingen:Message vernieuwd. De SetCacheExpiration methode geeft de minimale tijd op die moet verstrijken voordat een nieuwe aanvraag wordt ingediend bij App Configuration om te controleren op eventuele configuratiewijzigingen. In dit voorbeeld overschrijft u de standaardverlooptijd van 30 seconden, waarbij u een tijd van 10 seconden opgeeft voor demonstratiedoeleinden.

Als u de ConfigureRefresh methode alleen aanroept, wordt de configuratie niet automatisch vernieuwd. U roept de TryRefreshAsync methode aan vanuit de interface IConfigurationRefresher om een vernieuwing te activeren. Dit ontwerp is om aanvragen te voorkomen die naar App Configuration worden verzonden, zelfs wanneer uw toepassing niet actief is. U wilt de TryRefreshAsync aanroep opnemen waar u uw toepassing actief beschouwt. Dit kan bijvoorbeeld zijn wanneer u een binnenkomend bericht, een order of een iteratie van een complexe taak verwerkt. Het kan ook in een timer staan als uw toepassing altijd actief is. In dit voorbeeld belt TryRefreshAsync u elke keer dat u op Enter drukt. Zelfs als de aanroep TryRefreshAsync om welke reden dan ook mislukt, blijft uw toepassing de configuratie in de cache gebruiken. Er wordt nog een poging gedaan wanneer de geconfigureerde verlooptijd van de cache is verstreken en de TryRefreshAsync aanroep opnieuw wordt geactiveerd door uw toepassingsactiviteit. Bellen TryRefreshAsync is een no-op voordat de geconfigureerde cacheverlooptijd is verstreken, dus de invloed op de prestaties is minimaal, zelfs als deze vaak wordt aangeroepen.

Configuratie vernieuwen met behulp van afhankelijkheidsinjectie

In de vorige code slaat u handmatig een exemplaar op van IConfigurationRefresher aanroepen TryRefreshAsync. Als u afhankelijkheidsinjectie gebruikt om uw services op te lossen, kunt u ook verwijzen naar de volgende stappen.

Registreer de vereiste App Configuration-services door u aan te AddAzureAppConfiguration roepen.IServiceCollection

Voeg de volgende code toe aan Program.cs.
```
// Existing code in Program.cs
// ... ...

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

Vernieuw uw configuratie door een exemplaar van IConfigurationRefresherProvider uw serviceverzameling op te lossen en aan te TryRefreshAsync roepen op elk van de vernieuwingen.

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

De app lokaal bouwen en uitvoeren

Stel een omgevingsvariabele met de naam ConnectionString in en stel deze in op de toegangssleutel van het App Configuration-archief. Als u de Windows-opdrachtprompt gebruikt, voert u de volgende opdracht uit en start u de opdrachtprompt opnieuw om de wijziging door te voeren:
```
 setx ConnectionString "connection-string-of-your-app-configuration-store"
```
Als u Windows PowerShell gebruikt, voert u de volgende opdracht uit:
```
 $Env:ConnectionString = "connection-string-of-your-app-configuration-store"
```
Als u macOS of Linux gebruikt, voert u de volgende opdracht uit:
```
 export ConnectionString='connection-string-of-your-app-configuration-store'
```
Voer de volgende opdracht uit om de console-app te bouwen:
```
 dotnet build
```
Nadat het bouwen is voltooid, voert u de volgende opdracht uit om de app lokaal uit te voeren:
```
 dotnet run
```
Meld u aan bij het Azure-portaal. Selecteer Alle resources en selecteer de instantie van het App Configuration-archief dat u in de quickstart hebt gemaakt.
Selecteer Configuratieverkenner en werk de waarde van de volgende sleutels bij:

Sleutel Weergegeven als

TestApp:Settings:Message Gegevens van Azure App Configuration - bijgewerkt
Druk op Enter om een vernieuwing te activeren en de bijgewerkte waarde af te drukken naar de opdrachtprompt of het PowerShell-venster.

Notitie

Omdat de vervaltijd van de cache is ingesteld op tien seconden met behulp van de methode SetCacheExpiration tijdens het opgeven van de configuratie voor de vernieuwingsbewerking, wordt de waarde voor de configuratie-instelling alleen bijgewerkt als er ten minste tien seconden zijn verstreken sinds de laatste vernieuwing voor die instelling.

Sleutel	Weergegeven als
TestApp:Settings:Message	Gegevens van Azure App Configuration - bijgewerkt

Logboekregistratie en controle

Logboeken worden uitgevoerd bij het vernieuwen van de configuratie en bevatten gedetailleerde informatie over sleutelwaarden die zijn opgehaald uit uw App Configuration-archief en configuratiewijzigingen in uw toepassing. Als u een ASP.NET Core-toepassing hebt, raadpleegt u deze instructies voor logboekregistratie en bewaking in ASP.NET Core. Anders kunt u logboekregistratie inschakelen met behulp van de instructies voor logboekregistratie met de Azure SDK.

Logboeken worden uitgevoerd op verschillende gebeurtenisniveaus. Het standaardniveau is Informational.

Gebeurtenisniveau	Beschrijving
Uitgebreid	Logboeken bevatten de sleutel en het label van sleutelwaarden die uw toepassing bewaakt op wijzigingen in uw App Configuration-archief. De informatie bevat ook of de sleutelwaarde is gewijzigd in vergelijking met wat uw toepassing al heeft geladen. Schakel logboeken op dit niveau in om problemen met uw toepassing op te lossen als een configuratiewijziging niet is uitgevoerd zoals verwacht.
Informatief	Logboeken bevatten de sleutels van configuratie-instellingen die zijn bijgewerkt tijdens een configuratievernieuwing. Waarden van configuratie-instellingen worden weggelaten uit het logboek om te voorkomen dat gevoelige gegevens worden gelekt. U kunt logboeken op dit niveau bewaken om ervoor te zorgen dat uw toepassing verwachte configuratiewijzigingen ophaalt.
Waarschuwing	Logboeken bevatten fouten en uitzonderingen die zijn opgetreden tijdens het vernieuwen van de configuratie. Incidentele gebeurtenissen kunnen worden genegeerd omdat de configuratieprovider de gegevens in de cache blijft gebruiken en de configuratie de volgende keer probeert te vernieuwen. U kunt logboeken op dit niveau bewaken voor terugkerende waarschuwingen die mogelijke problemen kunnen aangeven. U hebt bijvoorbeeld de verbindingsreeks gedraaid, maar u bent vergeten uw toepassing bij te werken.

U kunt logboekregistratie op Verbose gebeurtenisniveau inschakelen door de EventLevel.Verbose parameter op te geven, zoals in het volgende voorbeeld wordt gedaan. Deze instructies zijn ook van toepassing op alle andere gebeurtenisniveaus. In dit voorbeeld worden ook logboeken voor alleen de Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh categorie ingeschakeld.

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

De categorie logboekregistratie is Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh, die vóór elk logboek wordt weergegeven. Hier volgen enkele voorbeeldlogboeken op elk gebeurtenisniveau:

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

Notitie

Logboekregistratie is beschikbaar als u versie 6.0.0 of hoger van een van de volgende pakketten gebruikt.

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

Resources opschonen

Als u de resources die in dit artikel zijn gemaakt niet wilt blijven gebruiken, verwijdert u de resourcegroep die u hier hebt gemaakt om kosten te voorkomen.

Belangrijk

Het verwijderen van een resourcegroep kan niet ongedaan worden gemaakt. De resourcegroep en alle resources daarin worden permanent verwijderd. Zorg ervoor dat u niet per ongeluk de verkeerde resourcegroep of resources verwijdert. Als u de resources voor dit artikel in een resourcegroep hebt gemaakt die andere resources bevat die u wilt behouden, moet u elke resource afzonderlijk verwijderen uit het deelvenster in plaats van dat u de resourcegroep verwijdert.

Meld u aan bij de Azure-portal en selecteer Resourcegroepen.
Voer de naam van de resourcegroep in het vak Filteren op naam in.
Selecteer in de resultatenlijst de resourcegroepnaam om een overzicht te bekijken.
Selecteer Resourcegroep verwijderen.
U wordt gevraagd om het verwijderen van de resourcegroep te bevestigen. Voer de naam van de resourcegroep in ter bevestiging en selecteer Verwijderen.

Na enkele ogenblikken worden de resourcegroep en alle bijbehorende resources verwijderd.

Volgende stappen

In deze zelfstudie hebt u uw .NET-app ingeschakeld om configuratie-instellingen dynamisch te vernieuwen vanuit App Configuration. Als u wilt weten hoe u een door Azure beheerde identiteit kunt gebruiken om de toegang tot App Configuration te stroomlijnen, gaat u verder met de volgende zelfstudie.

Integratie van beheerde identiteit

Delen via