Freigeben über

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

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.

Erneutes Laden von Daten aus App Configuration

  1. Ö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. Während des in den Voraussetzungen aufgeführten Schnellstarts 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)
           // Reload configuration if any selected key-values have changed.
           .ConfigureRefresh(refreshOptions =>
               refreshOptions.RegisterAll());
});

    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-Konfigurationsspeicher für mehrere Apps freigeben, ermöglicht dieser Ansatz, nur die für Ihre aktuelle App relevante Konfiguration zu laden, anstatt alle Konfigurationen aus dem Speicher zu laden.

    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 (die mit TestApp beginnen und keine Bezeichnung haben). Weitere Informationen zum Überwachen von Konfigurationsänderungen finden Sie unter Bewährte Methoden für die Aktualisierung der Konfiguration.

    Tipp

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

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

  3. Rufen Sie die UseAzureAppConfiguration-Methode auf. Dadurch wird es Ihrer App ermöglicht, die App Configuration-Middleware zu nutzen, um die Konfiguration automatisch für Sie zu 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 des Quickstarts 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 Settings abgerufenes stark typisiertes IOptionsSnapshot<T>-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 alle 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. Die Middleware sendet jedoch nur Anforderungen, um den Wert in App Configuration zu überprüfen, wenn das von Ihnen festgelegte Aktualisierungsintervall 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

  1. Führen Sie den folgenden Befehl in der Befehlsshell aus, um die App mithilfe der .NET-CLI zu erstellen:

        dotnet build

  2. Führen Sie nach erfolgreicher Erstellung den folgenden Befehl aus, um die Web-App lokal auszuführen:

        dotnet run

  3. Öffnen Sie ein Browserfenster, und navigieren Sie zu der URL, die in der dotnet run-Ausgabe angezeigt wird.

    Lokales Starten der Schnellstart-App

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

  5. Wählen Sie Konfigurations-Explorer aus, und aktualisieren Sie die Werte der folgenden Schlüssel.

    Schlüssel Wert
    TestApp:Settings:Hintergrundfarbe grün
    TestApp:Einstellungen:Schriftfarbe hellGrau
    TestApp:Einstellungen:Nachricht Daten aus Azure App Configuration – jetzt mit Liveupdates!

  6. Aktualisieren Sie den Browser mehrmals. Wenn das Aktualisierungsintervall nach 30 Sekunden verstrichen ist, wird die Seite mit aktualisierten Inhalten angezeigt.

    Lokales Starten der aktualisierten Schnellstart-App

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.

    Protokolliergrad BESCHREIBUNG
    Fehlerbehebung 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 Log-Level.

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

  1. Melden Sie sich beim Azure-Portal an, und klicken Sie auf Ressourcengruppen.
  2. Geben Sie im Feld Nach Name filtern den Namen Ihrer Ressourcengruppe ein.
  3. Wählen Sie in der Ergebnisliste den Ressourcengruppennamen aus, um eine Übersicht anzuzeigen.
  4. Wählen Sie die Option Ressourcengruppe löschen.
  5. 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