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

Artikel
12/10/2024

In diesem Tutorial wird gezeigt, wie Sie dynamische Konfigurationsupdates in einer ASP.NET Core-App aktivieren. Dies baut auf der Web-App auf, die in den Schnellstartanleitungen vorgestellt wurde. Ihre App nutzt die App Configuration-Anbieterbibliothek für die integrierten Funktionen zur Zwischenspeicherung und Aktualisierung der Konfiguration. Durchlaufen Sie zuerst die Schnellstartanleitung zum Erstellen einer ASP.NET Core-App mit Azure App Configuration, bevor Sie fortfahren.

In diesem Tutorial lernen Sie Folgendes:

Einrichten Ihrer App für die Aktualisierung der Konfiguration als Reaktion auf Änderungen in einem App Configuration-Speicher
Einfügen der aktuellen Konfiguration in Ihre App

Voraussetzungen

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

Hinzufügen eines Sentinel-Schlüssels

Ein Sentinel-Schlüssel ist ein Schlüssel, den Sie aktualisieren, nachdem Sie die Änderung aller anderen Schlüssel abgeschlossen haben. Ihre App überwacht den Sentinel-Schlüssel. Wird eine Änderung erkannt, werden alle Konfigurationswerte von Ihrer App aktualisiert. Dieser Ansatz trägt dazu bei, die Konsistenz der Konfiguration in Ihrer App sicherzustellen, und verringert die Gesamtanzahl von Anforderungen, die an den App Configuration-Speicher gesendet werden (verglichen mit der Überwachung aller Schlüssel auf Änderungen).

Öffnen Sie im Azure-Portal den App Configuration-Speicher, und wählen Sie Konfigurations-Explorer > Erstellen > Schlüsselwert aus.
Geben Sie unter Schlüssel die Zeichenfolge TestApp:Settings:Sentinel ein. Geben Sie unter Wert den Wert „1“ ein. Lassen Sie Bezeichnung und Inhaltstyp leer.
Wählen Sie Übernehmen.

Erneutes Laden von Daten aus App Configuration

Öffnen Sie Program.cs, und aktualisieren Sie die Methode AddAzureAppConfiguration, die Sie während der Schnellstartanleitung hinzugefügt haben. 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.
```
// Load configuration from Azure App Configuration
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential());
            // 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));
});
```
Die Select-Methode wird verwendet, um alle Schlüsselwerte zu laden, deren Schlüsselname mit TestApp: beginnt und keine Bezeichnung hat. Sie können die Select-Methode mehrmals aufrufen, um Konfigurationen mit unterschiedlichen Präfixen oder Bezeichnungen zu laden. Wenn Sie einen App Configuration-Speicher für mehrere Apps freigeben, wird mit diesem Ansatz nur die Konfiguration geladen, die für Ihre aktuelle App relevant ist, und nicht alles aus dem Speicher.

In der Methode ConfigureRefresh werden Schlüssel, die Sie auf Änderungen überwachen möchten, in Ihrem App Configuration-Speicher registriert. Der refreshAll-Parameter der Register-Methode gibt an, dass alle Konfigurationen, die Sie durch die Select-Methode angegeben haben, neu geladen werden, wenn sich der registrierte Schlüssel ändert.

Tipp

Sie können der refreshOptions.SetCacheExpiration-Methode einen Aufruf hinzufügen, um die Mindestzeit zwischen Konfigurationsaktualisierungen anzugeben. In diesem Beispiel verwenden Sie den Standardwert von 30 Sekunden. Geben Sie einen höheren Wert an, wenn Sie die Anzahl der Anforderungen an Ihren App Configuration-Speicher verringern müssen.

Fügen Sie der Dienstsammlung Ihrer App Azure App Configuration-Middleware hinzu.

Aktualisieren Sie Program.cs mit dem folgenden 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
// ... ...

Rufen Sie die UseAzureAppConfiguration-Methode auf. Dadurch kann Ihre App die Konfiguration automatisch mithilfe der App Configuration-Middleware aktualisieren.

Aktualisieren Sie Program.cs mit dem folgenden 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
// ... ...

Sie haben Ihre App während der Schnellstartanleitung so eingerichtet, dass sie das Optionsmuster in ASP.NET Core verwendet. Wenn die zugrunde liegende Konfiguration Ihrer App von App Configuration aktualisiert wird, wird Ihr über IOptionsSnapshot<T> abgerufenes stark typisiertes Settings-Objekt automatisch aktualisiert. Beachten Sie, dass Sie IOptions<T> nicht verwenden sollten, wenn das dynamische Konfigurationsupdate gewünscht ist, da es keine Konfigurationsdaten liest, nachdem die App gestartet wurde.

Anforderungsgesteuerte Konfigurationsaktualisierung

Die Konfigurationsaktualisierung wird durch die eingehenden Anforderungen an Ihre Web-App ausgelöst. Es erfolgt keine Aktualisierung, wenn sich Ihre App im Leerlauf befindet. Wenn Ihre App aktiv ist, überwacht die App Configuration-Middleware den Sentinel-Schlüssel oder alle anderen Schlüssel, die Sie im Aufruf von ConfigureRefresh für die Aktualisierung registriert haben. Die Middleware wird bei jeder eingehenden Anforderung Ihrer App ausgelöst. Von der Middleware werden jedoch erst dann Anforderungen zum Überprüfen des Werts in App Configuration gesendet, wenn die von Ihnen festgelegte Cacheablaufzeit verstrichen ist.

Tritt bei einer an App Configuration gesendeten Änderungserkennungsanforderung ein Fehler auf, wird von Ihrer App weiterhin die zwischengespeicherte Konfiguration verwendet. In regelmäßigen Abständen werden neue Versuche unternommen, nach Änderungen zu suchen, während neue Anfragen bei Ihrer App eingehen.
Die Konfigurationsaktualisierung wird asynchron zur Verarbeitung der eingehenden Anforderungen Ihrer App durchgeführt. Die eingehende Anforderung, durch die die Aktualisierung ausgelöst wurde, wird nicht blockiert oder verlangsamt. Die Anforderung, durch die die Aktualisierung ausgelöst wurde, erhält möglicherweise nicht die aktualisierten Konfigurationswerte, nachfolgende Anforderungen dagegen schon.
Um sicherzustellen, dass die Middleware ausgelöst wird, empfiehlt es sich, die app.UseAzureAppConfiguration()-Methode möglichst früh in Ihrer Anforderungspipeline aufzurufen, damit sie nicht durch eine andere Middleware in Ihrer App übersprungen wird.

Lokales Erstellen und Ausführen der App

Führen Sie den folgenden Befehl in der Befehlsshell aus, um die App mithilfe der .NET-CLI zu erstellen:
```
    dotnet build
```
Führen Sie nach erfolgreicher Erstellung den folgenden Befehl aus, um die Web-App lokal auszuführen:
```
    dotnet run
```
Öffnen Sie ein Browserfenster, und navigieren Sie zu der URL, die in der dotnet run-Ausgabe angezeigt wird.
Melden Sie sich beim Azure-Portal an. Wählen Sie Alle Ressourcen und dann den App Configuration-Speicher aus, den Sie in der Schnellstartanleitung erstellt haben.

Wählen Sie Konfigurations-Explorer aus, und aktualisieren Sie die Werte der folgenden Schlüssel. Denken Sie daran, den Sentinel-Schlüssel zuletzt zu aktualisieren.

Schlüssel	Wert
TestApp:Settings:BackgroundColor	green
TestApp:Settings:FontColor	lightGray
TestApp:Settings:Message	Daten aus Azure App Configuration – jetzt mit Liveupdates!
TestApp:Settings:Sentinel	2

Aktualisieren Sie den Browser mehrmals. Wenn der Cache nach 30 Sekunden abläuft, wird die Seite mit aktualisiertem Inhalt angezeigt.

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.

Ein Standardwert ILoggerFactory wird automatisch hinzugefügt, wenn services.AddAzureAppConfiguration() aufgerufen wird. Der App Configuration-Anbieter verwendet diese ILoggerFactory, um eine Instanz von ILogger zu erstellen, die diese Protokolle ausgibt. ASP.NET Core verwendet ILogger standardmäßig für die Protokollierung, sodass Sie keine zusätzlichen Codeänderungen vornehmen müssen, um die Protokollierung für den App Configuration-Anbieter zu aktivieren.

Protokolle werden auf verschiedenen Protokollebenen ausgegeben. Die Standardebene ist Information.

Protokollebene	BESCHREIBUNG
Debuggen	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.
Informationen	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 Protokollierung auf der Debug-Protokollebene aktivieren, indem Sie der Datei appsettings.json das folgende Beispiel hinzufügen. Dieses Beispiel gilt auch für alle anderen Protokollebenen.

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

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

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'

Die Verwendung von ILogger ist die bevorzugte Methode in ASP.NET-Anwendungen und wird als Protokollierungsquelle priorisiert, wenn eine Instanz von ILoggerFactory vorhanden ist. Wenn ILoggerFactory jedoch nicht verfügbar ist, können Protokolle alternativ über die Anweisungen für .NET Core-Apps aktiviert und konfiguriert werden. Weitere Informationen finden Sie unter Protokollieren in .NET Core und ASP.NET Core.

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 ASP.NET Core-Web-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.

Greifen Sie mit verwalteter Identität auf die Azure App Configuration zu

Freigeben über