Blazor-Konfiguration in ASP.NET Core

In diesem Artikel erhalten Sie Informationen zur Konfiguration von Blazor-Apps, einschließlich der App-Einstellungen, der Authentifizierung und Protokollierungskonfiguration.

Dieser Leitfaden gilt für die clientseitige Projektkonfiguration in einer Blazor Web App oder einer eigenständigen Blazor WebAssembly-App.

Standardverhalten in Blazor Web Apps:

• Für die serverseitige Konfiguration:
  • Anleitungen finden Sie unter Konfiguration in ASP.NET Core.
  • Es wird nur die Konfiguration in den Stammdateien der App-Einstellungen des Projekts geladen.
  • Der Rest dieses Artikels gilt nur für die clientseitige Konfiguration im .Client-Projekt.
• Für die clientseitige Konfiguration (.Client Projekt) wird die Konfiguration aus den folgenden Dateien für die App-Einstellungen geladen:
  • wwwroot/appsettings.json.
  • wwwroot/appsettings.{ENVIRONMENT}.json, wobei der Platzhalter {ENVIRONMENT} die Laufzeitumgebung der App ist.

In eigenständigen Blazor WebAssembly Apps wird die Konfiguration aus den folgenden Einstellungsdateien für Apps geladen:

• wwwroot/appsettings.json.
• wwwroot/appsettings.{ENVIRONMENT}.json, wobei der Platzhalter {ENVIRONMENT} die Laufzeitumgebung der App ist.

Hinweis

Eine Protokollierungskonfiguration, die in eine App-Einstellungsdatei in wwwroot eingefügt wurde, wird nicht standardmäßig geladen. Weitere Informationen finden Sie im Abschnitt Konfiguration der Protokollierung weiter unten in diesem Artikel.

In einigen Szenarien, z. B. bei Azure-Diensten, ist es wichtig, ein Segment des Umgebungsdateinamens zu verwenden, das genau dem Umgebungsnamen entspricht. Verwenden Sie z. B. den Dateinamen appsettings.Staging.json mit einem Großbuchstaben „S“ für die Staging-Umgebung. Empfohlene Konventionen finden Sie in den öffnenden Anmerkungen zu ASP.NET CoreBlazor-Umgebungen.

Andere in der App registrierte Konfigurationsanbieter können auch Konfigurationen bereitstellen, aber nicht alle Anbieter und Anbieterfeatures sind geeignet:

• Azure Key Vault-Konfigurationsanbieter: Der Anbieter wird für Szenarien mit verwalteter Identität und Anwendungs-ID (Client-ID) mit geheimem Clientschlüssel nicht unterstützt. Eine Anwendungs-ID mit einem geheimen Clientschlüssel wird für ASP.NET Core-Apps nicht empfohlen, insbesondere nicht für clientseitige Apps, da der geheime Clientschlüssel nicht clientseitig für den Zugriff auf den Azure Key Vault-Dienst geschützt werden kann.
• Azure App Configuration-Anbieter: Der Anbieter ist für eine clientseitige App nicht geeignet, da die App nicht auf einem Server in Azure ausgeführt wird.

Weitere Informationen zu Konfigurationsanbietern finden Sie unter Konfiguration in ASP.NET Core.

Warnung

Die Konfigurations- und Einstellungsdateien im Webstamm (Ordner wwwroot) sind für die Benutzer auf dem Client sichtbar, und die Benutzer können die Daten manipulieren. Speichern Sie keine App-Geheimnisse, Anmeldeinformationen oder andere vertrauliche Daten in einer Webstammdatei.

Konfiguration von App-Einstellungen

Die Konfiguration in App-Einstellungsdateien wird standardmäßig geladen. Im folgenden Beispiel wird ein Benutzeroberflächen-Konfigurationswert in einer App-Einstellungsdatei gespeichert und automatisch vom Blazor-Framework geladen. Der Wert wird von einer Komponente gelesen.

wwwroot/appsettings.json:

{
    "h1FontSize": "50px"
}

Fügen Sie eine IConfiguration-Instanz in eine Komponente ein, um auf die Konfigurationsdaten zuzugreifen.

ConfigExample.razor:

@page "/config-example"
@inject IConfiguration Configuration

<PageTitle>Configuration</PageTitle>

<h1 style="font-size:@Configuration["h1FontSize"]">
    Configuration example (50px)
</h1>

Sicherheitseinschränkungen auf dem Client verhindern den direkten Zugriff auf Dateien über den Benutzercode, einschließlich Einstellungsdateien für die App-Konfiguration. Um Konfigurationsdateien zusätzlich zu appsettings.json/appsettings.{ENVIRONMENT}.json aus dem Ordner wwwroot in die Konfiguration zu lesen, verwenden Sie einen HttpClient.

Warnung

Die Konfigurations- und Einstellungsdateien im Webstamm (Ordner wwwroot) sind für die Benutzer auf dem Client sichtbar, und die Benutzer können die Daten manipulieren. Speichern Sie keine App-Geheimnisse, Anmeldeinformationen oder andere vertrauliche Daten in einer Webstammdatei.

Im folgenden Beispiel wird eine Konfigurationsdatei (cars.json) in die Konfiguration der App gelesen.

wwwroot/cars.json:

{
    "size": "tiny"
}

Fügen Sie den Namespace für Microsoft.Extensions.Configuration am Anfang der Program-Datei hinzu:

using Microsoft.Extensions.Configuration;

Ändern Sie die vorhandene HttpClient-Dienstregistrierung so, dass der Client zum Lesen der Datei verwendet wird:

var http = new HttpClient()
{
    BaseAddress = new Uri(builder.HostEnvironment.BaseAddress)
};

builder.Services.AddScoped(sp => http);

using var response = await http.GetAsync("cars.json");
using var stream = await response.Content.ReadAsStreamAsync();

builder.Configuration.AddJsonStream(stream);

Im vorherigen Beispiel wird die Basisadresse mit builder.HostEnvironment.BaseAddress (IWebAssemblyHostEnvironment.BaseAddress) festgelegt, wodurch die Basisadresse für die App abgerufen und in der Regel vom href-Wert des <base>-Tags auf der Hostseite abgeleitet wird.

Arbeitsspeicher als Konfigurationsquelle

Im folgenden Beispiel wird ein MemoryConfigurationSource-Element in der Program -Datei verwendet, um eine zusätzliche Konfiguration bereitzustellen.

Fügen Sie den Namespace für Microsoft.Extensions.Configuration.Memory am Anfang der Program-Datei hinzu:

using Microsoft.Extensions.Configuration.Memory;

In der Program-Datei:

var vehicleData = new Dictionary<string, string?>()
{
    { "color", "blue" },
    { "type", "car" },
    { "wheels:count", "3" },
    { "wheels:brand", "Blazin" },
    { "wheels:brand:type", "rally" },
    { "wheels:year", "2008" },
};

var memoryConfig = new MemoryConfigurationSource { InitialData = vehicleData };

builder.Configuration.Add(memoryConfig);

Fügen Sie eine IConfiguration-Instanz in eine Komponente ein, um auf die Konfigurationsdaten zuzugreifen.

MemoryConfig.razor:

@page "/memory-config"
@inject IConfiguration Configuration

<PageTitle>Memory Configuration</PageTitle>

<h1>Memory Configuration Example</h1>

<h2>General specifications</h2>

<ul>
    <li>Color: @Configuration["color"]</li>
    <li>Type: @Configuration["type"]</li>
</ul>

<h2>Wheels</h2>

<ul>
    <li>Count: @Configuration["wheels:count"]</li>
    <li>Brand: @Configuration["wheels:brand"]</li>
    <li>Type: @Configuration["wheels:brand:type"]</li>
    <li>Year: @Configuration["wheels:year"]</li>
</ul>

Rufen Sie einen Abschnitt der Konfiguration in C#-Code mit IConfiguration.GetSection ab. Im folgenden Beispiel wird der wheels-Abschnitt für die Konfiguration im vorherigen Beispiel abgerufen:

@code {
    protected override void OnInitialized()
    {
        var wheelsSection = Configuration.GetSection("wheels");

        ...
    }
}

Authentifizierungskonfiguration

Geben Sie eine öffentliche Authentifizierungskonfiguration in einer App-Einstellungsdatei an.

wwwroot/appsettings.json:

{
  "Local": {
    "Authority": "{AUTHORITY}",
    "ClientId": "{CLIENT ID}"
  }
}

Laden Sie die Konfiguration für einen Identity-Anbieter mit ConfigurationBinder.Bind in die Program-Datei. Im folgenden Beispiel wird die Konfiguration für einen OIDC-Anbieter geladen:

builder.Services.AddOidcAuthentication(options =>
    builder.Configuration.Bind("Local", options.ProviderOptions));

Warnung

Die Konfigurations- und Einstellungsdateien im Webstamm (Ordner wwwroot) sind für die Benutzer auf dem Client sichtbar, und die Benutzer können die Daten manipulieren. Speichern Sie keine App-Geheimnisse, Anmeldeinformationen oder andere vertrauliche Daten in einer Webstammdatei.

Konfiguration der Protokollierung

Dieser Abschnitt gilt für Apps, bei denen die Protokollierung über eine App-Einstellungsdatei im wwwroot-Ordner konfiguriert wird.

Fügen Sie der App das Paket Microsoft.Extensions.Logging.Configuration hinzu.

Hinweis

Einen Leitfaden zum Hinzufügen von Paketen zu .NET-Apps finden Sie in Installieren und Verwalten von Paketen unter Workflow der Nutzung von Paketen (NuGet-Dokumentation). Überprüfen Sie unter NuGet.org, ob die richtige Paketversion verwendet wird.

Geben Sie in der App-Einstellungsdatei die Protokollierungskonfiguration an. Die Protokollierungskonfiguration wird in die Program-Datei geladen.

wwwroot/appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

In der Program-Datei:

builder.Logging.AddConfiguration(
    builder.Configuration.GetSection("Logging"));

Konfiguration des Host-Generators

Lesen Sie die Hostbuilderkonfiguration aus WebAssemblyHostBuilder.Configuration in der Program-Datei:

var hostname = builder.Configuration["HostName"];

Zwischengespeicherte Konfiguration

Konfigurationsdateien werden zur Offlineverwendung zwischengespeichert. Bei progressiven Web-Apps (PWAs) können Sie Konfigurationsdateien nur beim Erstellen einer neuen Bereitstellung aktualisieren. Die Bearbeitung von Konfigurationsdateien zwischen Bereitstellungen hat aus folgenden Gründen keine Auswirkungen:

• Benutzer verfügen über zwischengespeicherte Versionen der Dateien, die sie weiterhin verwenden können.
• Die Dateien service-worker.js und service-worker-assets.js der PWA müssen bei der Kompilierung neu erstellt werden, wodurch der App beim nächsten Onlineaufruf des Benutzers signalisiert wird, dass die App neu bereitgestellt wurde.

Weitere Informationen zur Behandlung von Hintergrundupdates durch PWAs finden Sie unter ASP.NET Core Blazor-basierte progressive Web-Apps (PWAs).

Optionskonfiguration

Die Optionskonfiguration erfordert das Hinzufügen eines Paketverweises für das NuGet-Paket Microsoft.Extensions.Options.ConfigurationExtensions.

Hinweis

Einen Leitfaden zum Hinzufügen von Paketen zu .NET-Apps finden Sie in Installieren und Verwalten von Paketen unter Workflow der Nutzung von Paketen (NuGet-Dokumentation). Überprüfen Sie unter NuGet.org, ob die richtige Paketversion verwendet wird.

Beispiel:

builder.Services.Configure<MyOptions>(
    builder.Configuration.GetSection("MyOptions"));

Nicht alle ASP.NET Core Optionsfeatures werden in Razor Komponenten unterstützt. Beispielsweise werden IOptionsSnapshot<TOptions>- und IOptionsMonitor<TOptions>-Konfigurationen unterstützt, aber die Neuberechnung von Optionswerten für diese Schnittstellen wird nicht unterstützt, es sei denn, die Anwendung wird neu geladen, indem entweder die App auf einer neuen Browserregisterkarte angefordert wird oder die Schaltfläche zum neu Laden des Browsers ausgewählt wird. Das bloße Aufrufen von StateHasChanged aktualisiert Momentaufnahme- oder überwachte Optionswerte nicht, wenn sich die zugrunde liegende Konfiguration ändert.