Tutorial: Verwenden der dynamischen Konfiguration in einer .NET-App

Artikel
02/20/2024

Die .NET-Anbieterbibliothek von App Configuration unterstützt die bedarfsgesteuerte Aktualisierung der Konfigurationseinstellungen, ohne dass eine Anwendung neu gestartet werden muss. In diesem Tutorial wird veranschaulicht, wie Sie dynamische Konfigurationsupdates in Ihrem Code implementieren können. Dies baut auf der App auf, die in der Schnellstartanleitung vorgestellt wurde. Durchlaufen Sie die Schnellstartanleitung zum Erstellen einer .NET-App mit Azure App Configuration, bevor Sie fortfahren.

Für die Ausführung der Schritte dieses Tutorials können Sie einen beliebigen Code-Editor verwenden. Visual Studio Code ist eine hervorragende Option, die auf Windows-, macOS- und Linux-Plattformen verfügbar ist.

In diesem Tutorial lernen Sie Folgendes:

Einrichten Ihrer .NET-App für die Aktualisierung der Konfiguration als Reaktion auf Änderungen in einem App Configuration-Speicher
Verwenden der aktuellen Konfiguration in Ihrer Anwendung

Voraussetzungen

Sollten Sie über kein Azure-Abonnement verfügen, können Sie zunächst ein kostenloses Azure-Konto erstellen.

Durchlaufen Sie den Schnellstart zum Erstellen einer .NET-App mit App Configuration.

Aktivitätsgesteuerte Konfigurationsaktualisierung

Öffnen Sie die Datei Program.cs, und aktualisieren Sie sie mit folgendem 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 der Methode ConfigureRefresh wird ein Schlüssel in Ihrem App Configuration-Speicher für die Änderungsüberwachung registriert. Die Methode Register enthält den optionalen booleschen Parameter refreshAll, mit dem angegeben werden kann, ob alle Konfigurationswerte bei einer Änderung des registrierten Schlüssels aktualisiert werden sollen. In diesem Beispiel wird nur der Schlüssel TestApp:Settings:Message aktualisiert. Durch die Methode SetCacheExpiration wird angegeben, wie viel Zeit mindestens verstreichen muss, bevor eine neue Anforderung an App Configuration gesendet wird, um nach Konfigurationsänderungen zu suchen. In diesem Beispiel wird die Standardablaufzeit von 30 Sekunden zu Demonstrationszwecken in 10 Sekunden geändert.

Das Aufrufen der Methode ConfigureRefresh allein führt nicht dazu, dass die Konfiguration automatisch aktualisiert wird. Sie rufen die Methode TryRefreshAsync über die Schnittstelle IConfigurationRefresher auf, um eine Aktualisierung auszulösen. Dieses Design soll verhindern, dass Anfragen an die App Configuration gesendet werden, selbst wenn Ihre Anwendung im Leerlauf ist. Der Aufruf TryRefreshAsync sollte an einer Stelle verwendet werden, an der Sie Ihre Anwendung als aktiv betrachten. Dies kann beispielsweise der Fall sein, wenn Sie eine eingehende Nachricht, eine Bestellung oder eine Iteration einer komplexen Aufgabe verarbeiten. Er kann auch Teil eines Timers sein, wenn Ihre Anwendung ständig aktiv ist. In diesem Beispiel rufen Sie TryRefreshAsync jedes Mal auf, wenn Sie die EINGABETASTE drücken. Selbst wenn der Aufruf TryRefreshAsync aus einem beliebigen Grund fehlschlägt, verwendet Ihre Anwendung weiterhin die zwischengespeicherte Konfiguration. Ein weiterer Versuch wird unternommen, wenn die konfigurierte Cacheablaufzeit verstrichen ist und der Aufruf TryRefreshAsync von Ihrer Anwendungsaktivität erneut ausgelöst wird. Das Aufrufen von TryRefreshAsync ist vor Verstreichen der konfigurierten Cacheablaufzeit keine Option. Daher sind die Auswirkungen auf die Leistung minimal, auch wenn der Aufruf häufig erfolgt.

Konfigurationsaktualisierung mithilfe einer Abhängigkeitsinjektion

Im vorherigen Code speichern Sie eine Instanz vonIConfigurationRefresher manuell, um TryRefreshAsync aufzurufen. Wenn Sie die Abhängigkeitsinjektion verwenden, um Ihre Dienste aufzulösen, können Sie alternativ die folgenden Schritte ausführen.

Registrieren Sie die erforderlichen App Configuration-Dienste, indem Sie AddAzureAppConfiguration für Ihre IServiceCollection aufrufen.

Fügen Sie den folgenden Code in die Datei Program.cs ein.
```
// Existing code in Program.cs
// ... ...

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

Aktualisieren Sie Ihre Konfiguration, indem Sie eine Instanz von IConfigurationRefresherProvider aus Ihrer Dienstauflistung auflösen und TryRefreshAsync für die einzelnen Aktualisierungen aufrufen.

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

Lokales Erstellen und Ausführen der App

Legen Sie eine Umgebungsvariable mit dem Namen ConnectionString fest, und geben Sie dafür den Zugriffsschlüssel für Ihren App Configuration-Speicher an. Führen Sie bei Verwendung einer Windows-Eingabeaufforderung den folgenden Befehl aus, und starten Sie die Eingabeaufforderung neu, damit die Änderung wirksam wird:
```
 setx ConnectionString "connection-string-of-your-app-configuration-store"
```
Führen Sie bei Verwendung von Windows PowerShell den folgenden Befehl aus:
```
 $Env:ConnectionString = "connection-string-of-your-app-configuration-store"
```
Führen Sie bei Verwendung von macOS oder Linux den folgenden Befehl aus:
```
 export ConnectionString='connection-string-of-your-app-configuration-store'
```
Führen Sie den folgenden Befehl aus, um die Konsolen-App zu erstellen:
```
 dotnet build
```
Führen Sie nach der erfolgreichen Erstellung den folgenden Befehl aus, um die App lokal auszuführen:
```
 dotnet run
```
Melden Sie sich beim Azure-Portal an. Klicken Sie auf Alle Ressourcen, und wählen Sie dann die Instanz des App Configuration-Speichers aus, die Sie in der Schnellstartanleitung erstellt haben.
Wählen Sie den Konfigurations-Explorer aus, und aktualisieren Sie die Werte der folgenden Schlüssel:

Schlüssel Wert

TestApp:Settings:Message Daten aus Azure App Configuration: Aktualisiert
Drücken Sie die EINGABETASTE, um eine Aktualisierung auszulösen, und geben Sie den aktualisierten Wert in der Eingabeaufforderung oder im PowerShell-Fenster aus.

Hinweis

Da die Cacheablaufzeit beim Angeben der Konfiguration für den Aktualisierungsvorgang mit der SetCacheExpiration-Methode auf zehn Sekunden festgelegt wurde, wird der Wert für die Konfigurationseinstellung erst aktualisiert, wenn seit der letzten Aktualisierung für diese Einstellung mindestens zehn Sekunden verstrichen sind.

Schlüssel	Wert
TestApp:Settings:Message	Daten aus Azure App Configuration: Aktualisiert

Protokollierung und Überwachung

Protokolle werden bei der Konfigurationsaktualisierung ausgegeben und enthalten detaillierte Informationen zu Schlüsselwerten, die aus Ihrem App Configuration-Speicher abgerufen werden, und Konfigurationsänderungen, die an Ihrer Anwendung vorgenommen wurden. Wenn Sie über eine ASP.NET Core-Anwendung verfügen, lesen Sie die folgenden Anweisungen zur Protokollierung und Überwachung in ASP.NET Core. Andernfalls können Sie die Protokollierung mithilfe der Anweisungen für Protokollierung mit dem Azure SDK aktivieren.

Protokolle werden auf verschiedenen Ereignisebenen ausgegeben. Die Standardebene ist Informational.

Ereignisgrad	Beschreibung
Ausführlich	Protokolle enthalten den Schlüssel und die Bezeichnung der Schlüsselwerte, die Ihre Anwendung auf Änderungen aus Ihrem App Configuration-Speicher überwacht. Die Informationen reflektieren auch, ob sich der Schlüsselwert im Vergleich zu dem, was Ihre Anwendung bereits geladen hat, geändert hat. Aktivieren Sie Protokolle auf dieser Ebene, um Probleme mit Ihrer Anwendung zu beheben, wenn eine Konfigurationsänderung nicht wie erwartet erfolgt ist.
Informational	Protokolle enthalten die Schlüssel der Konfigurationseinstellungen, die während einer Konfigurationsaktualisierung aktualisiert wurden. Werte von Konfigurationseinstellungen werden aus dem Protokoll ausgelassen, um zu vermeiden, dass vertrauliche Daten verloren gehen. Sie können Protokolle auf dieser Ebene überwachen, um sicherzustellen, dass Ihre Anwendung erwartete Konfigurationsänderungen übernimmt.
Warnung	Protokolle enthalten Fehler und Ausnahmen, die während der Konfigurationsaktualisierung aufgetreten sind. Gelegentliche Vorkommen können ignoriert werden, da der Konfigurationsanbieter weiterhin die zwischengespeicherten Daten verwendet und versucht, die Konfiguration beim nächsten Mal zu aktualisieren. Sie können Protokolle auf dieser Ebene auf wiederholte Warnungen überwachen, die auf potenzielle Probleme hinweisen können. Beispielsweise haben Sie die Verbindungszeichenfolge gedreht, aber vergessen, Ihre Anwendung zu aktualisieren.

Sie können die Protokollierung auf Verbose Ereignisebene aktivieren, indem Sie den EventLevel.Verbose Parameter angeben, wie im folgenden Beispiel beschrieben. Diese Anweisungen gelten auch für alle anderen Ereignisebenen. In diesem Beispiel werden auch Protokolle nur für die Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh Kategorie aktiviert.

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

Die Protokollierungskategorie ist Microsoft-Extensions-Configuration-AzureAppConfiguration-Refresh, welche vor jedem Protokoll angezeigt wird. Hier sind einige Beispielprotokolle auf jeder Ereignisebene:

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

Hinweis

Die Protokollierung ist verfügbar, wenn Sie Version 6.0.0 oder höher eines der folgenden Pakete verwenden.

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

Bereinigen von Ressourcen

Wenn Sie die in diesem Artikel erstellten Ressourcen nicht mehr verwenden möchten, löschen Sie die erstellte Ressourcengruppe, um Kosten zu vermeiden.

Wichtig

Das Löschen einer Ressourcengruppe kann nicht rückgängig gemacht werden. Die Ressourcengruppe und alle darin enthaltenen Ressourcen werden unwiderruflich gelöscht. Achten Sie daher darauf, dass Sie nicht versehentlich die falsche Ressourcengruppe oder die falschen Ressourcen löschen. Falls Sie die Ressourcen für diesen Artikel in einer Ressourcengruppe erstellt haben, die andere beizubehaltende Ressourcen enthält, löschen Sie die Ressourcen einzeln über den entsprechenden Bereich, statt die Ressourcengruppe zu löschen.

Melden Sie sich beim Azure-Portal an, und klicken Sie auf Ressourcengruppen.
Geben Sie im Feld Nach Name filtern den Namen Ihrer Ressourcengruppe ein.
Wählen Sie in der Ergebnisliste den Ressourcengruppennamen aus, um eine Übersicht anzuzeigen.
Wählen Sie die Option Ressourcengruppe löschen.
Sie werden aufgefordert, das Löschen der Ressourcengruppe zu bestätigen. Geben Sie zur Bestätigung den Namen Ihrer Ressourcengruppe ein, und klicken Sie auf Löschen.

Daraufhin werden die Ressourcengruppe und alle darin enthaltenen Ressourcen gelöscht.

Nächste Schritte

In diesem Tutorial haben Sie Ihre .NET-App aktiviert, um Konfigurationseinstellungen dynamisch aus App Configuration zu aktualisieren. Fahren Sie mit dem nächsten Tutorial fort, um zu erfahren, wie Sie eine von Azure verwaltete Identität hinzufügen, um den Zugriff auf App Configuration zu optimieren.

Integration der verwalteten Identität