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

2025-04-22

Die .NET-Anbieterbibliothek der App-Konfiguration unterstützt das Aktualisieren der Konfiguration bei Bedarf, ohne dass eine Anwendung neu gestartet wird. In diesem Lernprogramm wird gezeigt, wie Sie dynamische Konfigurationsupdates in Ihrem Code implementieren können. Sie baut auf der in der Schnellstartanleitung eingeführten App auf. Sie sollten die Erstellung einer .NET-App mit der App-Konfiguration abschließen, 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:

Richten Sie Ihre .NET-App ein, um die Konfiguration als Reaktion auf Änderungen in einem App-Konfigurationsspeicher zu aktualisieren.
Verwenden der aktuellen Konfiguration in Ihrer Anwendung

Voraussetzungen

Wenn Sie nicht über ein Azure-Konto verfügen, erstellen Sie ein kostenloses Konto , bevor Sie beginnen.

Beenden Sie die Schnellstartanleitung Erstellen einer .NET-App mit App-Konfiguration.

Aktivitätsgesteuerte Konfigurationsaktualisierung

Öffnen Sie Program.cs , und aktualisieren Sie die Datei mit dem folgenden Code. Sie können eine Verbindung mit App Configuration entweder mithilfe von Microsoft Entra ID (empfohlen) oder mit einer Verbindungszeichenfolge herstellen. Der folgende Codeausschnitt veranschaulicht die Verwendung von Microsoft Entra ID.

Sie verwenden die DefaultAzureCredential für die Authentifizierung beim App Configuration-Speicher. Nachdem Sie die in den Voraussetzungen aufgeführte Schnellstartanleitung abgeschlossen haben, Sie Ihren Anmeldeinformationen bereits folgende Rolle zugewiesen: App Configuration-Datenleser.

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

}

Innerhalb der ConfigureRefresh Methode rufen Sie die RegisterAll Methode auf, den App-Konfigurationsanbieter anzuweisen, die gesamte Konfiguration neu zu laden, wenn eine Änderung in einem der ausgewählten Schlüsselwerte erkannt wird (in diesem Fall nur TestApp:Settings:Message). Weitere Informationen zum Überwachen von Konfigurationsänderungen finden Sie unter Bewährte Methoden für die Aktualisierung der Konfiguration.

Durch die Methode SetRefreshInterval 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 überschreiben Sie die standardmäßige Ablaufzeit von 30 Sekunden und geben stattdessen zu Demonstrationszwecken einen Zeitraum von 10 Sekunden an.

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 jedes Mal TryRefreshAsync auf, wenn Sie die EINGABETASTE drücken. Auch wenn der Aufruf TryRefreshAsync aus irgendeinem Grund fehlschlägt, verwendet Ihre Anwendung weiterhin die zwischengespeicherte Konfiguration. Ein weiterer Versuch wird unternommen, wenn das konfigurierte Aktualisierungsintervall verstrichen ist und der TryRefreshAsync Aufruf durch Ihre Anwendungsaktivität erneut ausgelöst wird. Das Aufrufen von TryRefreshAsync ist vor Verstreichen des konfigurierten Aktualisierungsintervalls 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 manuell eine Instanz von IConfigurationRefresher, 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 zum Program.cs hinzu.
```
// 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 Endpoint auf den Endpunkt Ihres App Configuration-Speichers fest, den Sie in der Übersicht Ihres Speichers im Azure-Portal finden.

Führen Sie bei Verwendung einer Windows-Eingabeaufforderung den folgenden Befehl aus, und starten Sie die Eingabeaufforderung neu, damit die Änderung wirksam wird:
```
setx Endpoint "<endpoint-of-your-app-configuration-store>"
```
Wenn Sie PowerShell verwenden, führen Sie den folgenden Befehl aus:
```
$Env:Endpoint = "<endpoint-of-your-app-configuration-store>"
```
Führen Sie bei Verwendung von macOS oder Linux den folgenden Befehl aus:
```
export Endpoint='<endpoint-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. Wählen Sie "Alle Ressourcen" und dann die App-Konfigurationsspeicherinstanz 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:Einstellungen:Nachricht Daten aus der Azure App-Konfiguration – Aktualisiert
Drücken Sie die EINGABETASTE, um eine Aktualisierung auszulösen und den aktualisierten Wert in der Eingabeaufforderung oder im PowerShell-Fenster zu drucken.

Hinweis

Da das Aktualisierungsintervall mithilfe der SetRefreshInterval Methode auf 10 Sekunden festgelegt wurde, während die Konfiguration für den Aktualisierungsvorgang angegeben wurde, wird der Wert für die Konfigurationseinstellung nur aktualisiert, wenn mindestens 10 Sekunden seit der letzten Aktualisierung für diese Einstellung verstrichen sind.

Schlüssel	Wert
TestApp:Einstellungen:Nachricht	Daten aus der Azure App-Konfiguration – 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 diese Anweisungen zur Protokollierung und Überwachung in ASP.NET Core. Andernfalls können Sie die Protokollierung mithilfe der Anweisungen für die Protokollierung mit dem Azure SDK aktivieren.

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

Ereignisebene	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.
Informativ	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 rotiert, aber vergessen, Ihre Anwendung zu aktualisieren.

Sie können die Verbose Protokollierung auf Ereignisebene aktivieren, indem Sie den EventLevel.Verbose Parameter wie im folgenden Beispiel angeben. 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 Lernprogramm haben Sie Ihre .NET-App aktiviert, um Konfigurationseinstellungen dynamisch aus der App-Konfiguration 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