Zelfstudie: Dynamische configuratie gebruiken in een ASP.NET Core-app

Artikel
02/28/2024

Deze zelfstudie laat zien hoe u dynamische configuratie-updates kunt inschakelen in een ASP.NET Core-app. Dit is gebaseerd op de web-app die is geïntroduceerd in de quickstarts. Uw app maakt gebruik van de bibliotheek van de App Configuration-provider voor de ingebouwde cacheopslag en het vernieuwen van de configuratie. Volg eerst Een ASP.NET Core-app maken met App Configuration voordat u verder gaat.

In deze zelfstudie leert u het volgende:

Stel uw app in om de configuratie bij te werken als reactie op wijzigingen in een App Configuration-archief.
Injecteer de nieuwste configuratie in uw app.

Vereisten

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

Een Sentinel-sleutel toevoegen

Een sentinel-sleutel is een sleutel die u bijwerkt nadat u de wijziging van alle andere sleutels hebt voltooid. Uw app bewaakt de sentinel-sleutel. Wanneer er een wijziging wordt gedetecteerd, vernieuwt uw app alle configuratiewaarden. Deze aanpak helpt bij het garanderen van de consistentie van de configuratie in uw app en vermindert het totale aantal aanvragen in uw App Configuration-archief, vergeleken met het bewaken van alle sleutels voor wijzigingen.

Open uw App Configuration-archief in Azure Portal en selecteer Configuration Explorer > Sleutelwaarde maken>.
Voer bij SleutelTestApp:Settings:Sentinel in. Voer 1 in bij Waarde. Laat Label en Inhoudstype leeg.
Selecteer Toepassen.

Gegevens opnieuw laden vanuit app-configuratie

Open Program.cs en werk de AddAzureAppConfiguration methode bij die u eerder hebt toegevoegd tijdens de quickstart.
```
// 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));
});
```
De Select methode wordt gebruikt om alle sleutelwaarden te laden waarvan de sleutelnaam begint met TestApp: en die geen label hebben. U kunt de Select methode meer dan één keer aanroepen om configuraties met verschillende voorvoegsels of labels te laden. Als u één App Configuration-archief met meerdere apps deelt, helpt deze aanpak bij het laden van de configuratie alleen relevant voor uw huidige app in plaats van alles uit uw store te laden.

In de ConfigureRefresh methode registreert u sleutels die u wilt controleren op wijzigingen in uw App Configuration-archief. De refreshAll parameter voor de Register methode geeft aan dat alle configuraties die u hebt opgegeven door de Select methode opnieuw worden geladen als de geregistreerde sleutel wordt gewijzigd.

Tip

U kunt een aanroep toevoegen aan de refreshOptions.SetCacheExpiration methode om de minimale tijd op te geven tussen het vernieuwen van de configuratie. In dit voorbeeld gebruikt u de standaardwaarde van 30 seconden. Pas deze waarde aan op een hogere waarde als u het aantal aanvragen in uw App Configuration-archief wilt verminderen.

Voeg Azure-app Configuration-middleware toe aan de serviceverzameling van uw app.

Werk Program.cs bij met de volgende code.

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

Roep de UseAzureAppConfiguration methode aan. Hiermee kan uw app de App Configuration-middleware gebruiken om de configuratie automatisch voor u bij te werken.

Werk Program.cs bij met de volgende code.

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

U hebt uw app ingesteld voor het gebruik van het optiespatroon in ASP.NET Core tijdens de quickstart. Wanneer de onderliggende configuratie van uw app wordt bijgewerkt vanuit App Configuration, wordt uw sterk getypte Settings object dat via is verkregen IOptionsSnapshot<T> , automatisch bijgewerkt. Houd er rekening mee dat u de IOptions<T> indien gewenste dynamische configuratie-update niet moet gebruiken, omdat deze geen configuratiegegevens leest nadat de app is gestart.

Aanvraaggestuurde configuratie vernieuwen

De configuratievernieuwing wordt geactiveerd door de binnenkomende aanvragen voor uw web-app. Er wordt geen vernieuwing uitgevoerd als uw app niet actief is. Wanneer uw app actief is, controleert de App Configuration-middleware de sentinel-sleutel of eventuele andere sleutels die u hebt geregistreerd voor vernieuwen in de ConfigureRefresh aanroep. De middleware wordt geactiveerd bij elke binnenkomende aanvraag voor uw app. De middleware verzendt echter alleen aanvragen om de waarde in App Configuration te controleren wanneer de verlooptijd van de cache is verstreken.

Als een aanvraag voor App Configuration voor wijzigingsdetectie mislukt, blijft uw app de configuratie in de cache gebruiken. Er worden regelmatig nieuwe pogingen gedaan om te controleren op wijzigingen, terwijl er nieuwe binnenkomende aanvragen voor uw app zijn.
De configuratievernieuwing vindt asynchroon plaats bij de verwerking van de binnenkomende aanvragen van uw app. De binnenkomende aanvraag die de vernieuwing heeft geactiveerd, wordt niet geblokkeerd of vertraagd. De aanvraag die de vernieuwing heeft geactiveerd, ontvangt mogelijk niet de bijgewerkte configuratiewaarden, maar latere aanvragen krijgen nieuwe configuratiewaarden.
Als u ervoor wilt zorgen dat de middleware wordt geactiveerd, roept u de app.UseAzureAppConfiguration() methode aan zo vroeg mogelijk in uw aanvraagpijplijn, zodat deze niet door een andere middleware in uw app wordt overgeslagen.

De app lokaal bouwen en uitvoeren

Als u de app wilt bouwen met behulp van de .NET CLI, voert u de volgende opdracht uit in de opdrachtshell:
```
    dotnet build
```
Nadat het bouwen is voltooid, voert u de volgende opdracht uit om de web-app lokaal uit te voeren:
```
    dotnet run
```
Open een browservenster en ga naar de URL die wordt weergegeven in de dotnet run-uitvoer.
Meld u aan bij het Azure-portaal. Selecteer Alle resources en selecteer het App Configuration-archief dat u in de quickstart hebt gemaakt.

Selecteer Configuration Explorer en werk de waarden van de volgende sleutels bij. Vergeet niet om de sentinel-sleutel eindelijk bij te werken.

Sleutel	Weergegeven als
TestApp:Settings:BackgroundColor	groen
TestApp:Settings:FontColor	lightGray
TestApp:Settings:Message	Gegevens uit Azure-app-configuratie - nu met live updates!
TestApp:Settings:Sentinel	2

Vernieuw de browser een paar keer. Wanneer de cache na 30 seconden verloopt, wordt de pagina weergegeven met bijgewerkte inhoud.

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.

Er wordt automatisch een standaard ILoggerFactory toegevoegd wanneer services.AddAzureAppConfiguration() deze wordt aangeroepen. De App Configuration-provider gebruikt deze ILoggerFactory om een exemplaar te maken waarvan ILoggerdeze logboeken worden uitgevoerd. ASP.NET Core standaard gebruikt ILogger voor logboekregistratie, zodat u geen aanvullende codewijzigingen hoeft aan te brengen om logboekregistratie voor de App Configuration-provider in te schakelen.

Logboeken worden uitgevoerd op verschillende logboekniveaus. Het standaardniveau is Information.

Logboekniveau	Beschrijving
Fouten opsporen	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.
Gegevens	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 logboekniveau Debug inschakelen door het volgende voorbeeld toe te voegen aan uw appsettings.json bestand. Dit voorbeeld is ook van toepassing op alle andere logboekniveaus.

"Logging": {
    "LogLevel": {
        "Microsoft.Extensions.Configuration.AzureAppConfiguration": "Debug"
    }
}

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

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'

Het gebruik ILogger is de voorkeursmethode in ASP.NET toepassingen en krijgt prioriteit als de logboekregistratiebron als er een exemplaar van ILoggerFactory aanwezig is. Als ILoggerFactory de logboeken echter niet beschikbaar zijn, kunnen logboeken ook worden ingeschakeld en geconfigureerd via de instructies voor .NET Core-apps. Zie logboekregistratie in .NET Core en ASP.NET Core voor meer informatie.

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 ASP.NET Core-web-app ingeschakeld voor het dynamisch vernieuwen van configuratie-instellingen 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.

Toegang tot App Configuration met beheerde identiteit

Share via