Zelfstudie: Dynamische configuratie gebruiken in een .NET-app

2025-04-24

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

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

In deze handleiding leer je hoe je:

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.

Vereiste voorwaarden

Als u geen Azure-account hebt, maak dan een gratis account aan 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. U kunt verbinding maken met App Configuration met behulp van Microsoft Entra ID (aanbevolen) of een verbindingsreeks. Het volgende codefragment laat zien hoe u Microsoft Entra-id gebruikt.

U gebruikt de DefaultAzureCredential om u te authentiseren bij uw App Configuration-opslagplaats. Tijdens het voltooien van de quickstart die wordt vermeld in de vereisten, hebt u al uw referentie toegewezen aan de rol App Configuration Data Reader.

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

}

In de ConfigureRefresh methode roept u de methode aan om de RegisterAll App Configuration-provider te instrueren om de volledige configuratie opnieuw te laden wanneer er een wijziging in een van de geselecteerde sleutelwaarden wordt gedetecteerd (in dit geval alleen TestApp:Settings:Message). Zie De aanbevolen procedures voor het vernieuwen van de configuratie voor meer informatie over het bewaken van configuratiewijzigingen.

De SetRefreshInterval 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. Je wilt de TryRefreshAsync oproep toevoegen waar je je applicatie actief acht. 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 het geconfigureerde vernieuwingsinterval is verstreken en de TryRefreshAsync aanroep opnieuw wordt geactiveerd door uw toepassingsactiviteit. Bellen TryRefreshAsync is een no-op voordat het geconfigureerde vernieuwingsinterval is verstreken, dus de invloed op de prestaties is minimaal, zelfs als het vaak wordt aangeroepen.

Configuratie vernieuwen met behulp van afhankelijkheidsinjectie

In de vorige code slaat u handmatig een exemplaar op van IConfigurationRefresher om TryRefreshAsync aan te roepen. 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 AddAzureAppConfiguration aan te roepen op uw 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 op te lossen uit uw servicecollectie en TryRefreshAsync aan te roepen op elk van de verversingsfuncties.

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 genaamd Eindpunt in op het eindpunt van uw App Configuration-winkel, te vinden onder het Overzicht van uw winkel in de Azure Portal.

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 Endpoint "<endpoint-of-your-app-configuration-store>"
```
Als u PowerShell gebruikt, voert u de volgende opdracht uit:
```
$Env:Endpoint = "<endpoint-of-your-app-configuration-store>"
```
Als u macOS of Linux gebruikt, voert u de volgende opdracht uit:
```
export Endpoint='<endpoint-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 Azure Portal. Selecteer Alle resources en selecteer het Exemplaar van het App Configuration-archief dat u in de quickstart hebt gemaakt.
Selecteer Configuration Explorer en werk de waarden van de volgende sleutels bij:

Sleutelcode Waarde

TestApp:Instellingen:Bericht Gegevens uit Azure App Configuration - bijgewerkt
Druk op Enter om een vernieuwing te activeren en de bijgewerkte waarde in het opdrachtprompt- of PowerShell-venster af te drukken.

Opmerking

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

Sleutelcode	Waarde
TestApp:Instellingen:Bericht	Gegevens uit Azure App Configuration - bijgewerkt

Logboekregistratie en bewaking

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 logcategorie is Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh, wat verschijnt voor elk log. 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'

Opmerking

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

De hulpbronnen 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 groep of bronnen 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 Azure Portal en selecteer Resourcegroepen.
Voer in het vak Filteren op naam de naam van uw resourcegroep 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 die u wilt bevestigen 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