ASP.NET Core Blazor-Umgebungen

In diesem Artikel wird erläutert, wie Sie die Umgebung in einerBlazor-App konfigurieren und lesen.

Wenn eine App lokal ausgeführt wird, wird die Umgebung standardmäßig auf Development festgelegt. Wenn eine App lokal ausgeführt wird, wird die Umgebung standardmäßig auf Production festgelegt.

Empfohlene Konventionen:

• Verwenden Sie für die lokale Entwicklung immer den Umgebungsnamen Development. Das ASP.NET Core-Framework erwartet genau diesen Namen, wenn die App und die Tools für die lokale Entwicklung einer App konfiguriert werden.

• Für Test-, Staging- und Produktionsumgebungen sollte die App immer veröffentlicht und bereitgestellt werden. Sie können ein beliebiges Umgebungsbenennungsschema für veröffentlichte Apps verwenden. Verwenden Sie aber immer App-Einstellungsdateinamen mit einer Groß-/Kleinschreibung des Umgebungssegments, die exakt mit dem Umgebungsnamen übereinstimmt. Verwenden Sie für die Stagingumgebung Staging (mit großem „S“) als Umgebungsname, und benennen Sie die App-Einstellungsdatei entsprechend (appsettings.Staging.json). Verwenden Sie für die Produktionsumgebung Production (mit großem „P“) als Umgebungsname, und benennen Sie die App-Einstellungsdatei entsprechend (appsettings.Production.json).

Festlegen der Umgebung

Verwenden Sie zum Einrichten der Umgebung einen der folgenden Ansätze:

• Blazor-Web-App: Verwenden Sie alle unter Verwenden von mehreren Umgebungen in ASP.NET Core beschriebenen Ansätze für allgemeine ASP.NET Core-Apps.
• Blazor-Web-App oder eigenständige Blazor WebAssembly-App: Blazor-Startkonfiguration
• Eigenständige Blazor WebAssembly-App: blazor-environment-Header
• Blazor-Web-App oder eigenständige Blazor WebAssembly-App: Azure App Service

Auf dem Client für eine Blazor-Web-App wird die Umgebung vom Server festgelegt. Dazu teilt eine Middleware die Umgebung mithilfe eines Headers namens blazor-environment dem Browser mit. Der Header legt die Umgebung fest, wenn der WebAssemblyHost in der clientseitigen Program-Datei (WebAssemblyHostBuilder.CreateDefault) erstellt wird.

Wird eine eigenständige Blazor WebAssembly-App lokal ausgeführt, fügt der Entwicklungsserver den blazor-environment-Header hinzu.

Bei Apps, die lokal in der Entwicklung ausgeführt werden, verwendet die App standardmäßig die Development-Umgebung. Beim Veröffentlichen der App wird die Umgebung standardmäßig auf Production festgelegt.

Festlegen der clientseitigen Umgebung per Blazor-Startkonfiguration

Im folgenden Beispiel wird Blazor in der Staging-Umgebung gestartet, wenn der Hostname localhost enthält. Andernfalls wird die Umgebung auf den Standardwert festgelegt.

Blazor Web-App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      webAssembly: {
        environment: "Staging"
      }
    });
  } else {
    Blazor.start();
  }
</script>

Im vorangegangenen Beispiel entspricht der {BLAZOR SCRIPT}-Platzhalter dem Pfad und Dateinamen des Blazor-Skripts. Informationen zum Speicherort des Skripts finden Sie unter Projektstruktur für ASP.NET Core Blazor.

Hinweis

Für Blazor-Web-Apps, die die Eigenschaft webAssembly>environment in der Konfiguration Blazor.start festlegen, empfiehlt es sich, die serverseitige Umgebung mit der Eigenschaft abzugleichen, die in der Eigenschaft environment festgelegt ist. Andernfalls wird für das Prerendering auf dem Server eine andere Umgebung verwendet als für das Rendern auf dem Client, was unvorhersehbare Auswirkungen hat. Weitere Informationen zum Festlegen der Umgebung für eine Blazor-Web-App finden Sie unter Verwenden von mehreren Umgebungen in ASP.NET Core.

Blazor WebAssembly eigenständig:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      environment: "Staging"
    });
  } else {
    Blazor.start();
  }
</script>

Im vorangegangenen Beispiel entspricht der {BLAZOR SCRIPT}-Platzhalter dem Pfad und Dateinamen des Blazor-Skripts. Informationen zum Speicherort des Skripts finden Sie unter Projektstruktur für ASP.NET Core Blazor.

Die Verwendung der environment-Eigenschaft überschreibt die durch den blazor-environment-Header festgelegte Umgebung.

Beim obigen Ansatz wird die Umgebung des Clients festgelegt, ohne den Wert des Headers blazor-environment zu ändern, und auch die serverprojektspezifische Konsolenprotokollierung der Startumgebung für eine Blazor-Web-App, die das globale interaktive WebAssembly-Rendering verwendet, wird nicht geändert.

Wenn Sie die Umgebung entweder in einem eigenständigen Blazor WebAssembly-Projekt oder im .Client-Projekt einer Blazor-Web-App in der Konsole protokollieren möchten, müssen Sie in der Datei Program den folgenden C#-Code platzieren, und zwar nach der Erstellung von WebAssemblyHost mit WebAssemblyHostBuilder.CreateDefault und vor der Zeile, die Projekt erstellt und ausführt (await builder.Build().RunAsync();):

Console.WriteLine(
    $"Client Hosting Environment: {builder.HostEnvironment.Environment}");

Weitere Informationen zum Start von Blazor finden Sie unter Starten von ASP.NET Core Blazor.

Festlegen der clientseitigen Umgebung per Header

Blazor WebAssembly-Apps können die Umgebung mit dem blazor-environment-Header festlegen.

Im folgenden Beispiel für IIS wird der benutzerdefinierte Header (blazor-environment) zu der veröffentlichten web.config-Datei hinzugefügt. Die web.config-Datei befindet sich im Ordner bin/Release/{TARGET FRAMEWORK}/publish, wobei der Platzhalter {TARGET FRAMEWORK} für das Zielframework steht:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>

    ...

    <httpProtocol>
      <customHeaders>
        <add name="blazor-environment" value="Staging" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>
</configuration>

Hinweis

Informationen zum Verwenden einer benutzerdefinierten Datei web.config für IIS, die nicht überschrieben wird, wenn die App im Ordner publish veröffentlicht wird, finden Sie unter Hosten und Bereitstellen von Blazor WebAssembly in ASP.NET Core.

Das Blazor-Framework gibt den Headernamen zwar vollständig in Kleinbuchstaben aus (blazor-environment), Sie können aber eine beliebige Groß-/Kleinschreibung verwenden. Beispielsweise werden auch Headernamen unterstützt, in denen jedes Wort mit einem Großbuchstaben beginnt (Blazor-Environment).

Festlegen der Umgebung für Azure App Service

Für eigenständige Blazor WebAssembly-Apps können Sie die Umgebung manuell über die Startkonfiguration oder den blazor-environment-Header festlegen.

Legen Sie für eine serverseitige App die Umgebung über eine ASPNETCORE_ENVIRONMENT-App-Einstellung in Azure fest:

1. Vergewissern Sie sich, dass die Groß-/Kleinschreibung von Umgebungssegmenten in Dateinamen der App-Einstellungen genau mit der Groß-/Kleinschreibung ihres Umgebungsnamens übereinstimmt. Der übereinstimmende Dateiname der App-Einstellungen für die Staging-Umgebung lautet beispielsweise appsettings.Staging.json. Wenn der Dateiname appsettings.staging.json lautet (mit kleinem s), wird die Datei nicht gefunden, und die Einstellungen in der Datei werden in der Staging-Umgebung nicht verwendet.

2. Vergewissern Sie sich bei einer Visual Studio-Bereitstellung, dass die App im richtigen Bereitstellungsslot bereitgestellt wird. Bei einer App mit dem Namen BlazorAzureAppSample wird die App im Staging-Bereitstellungsslot bereitgestellt.

3. Legen Sie im Azure-Portal für den Bereitstellungsslot der Umgebung die Umgebung mit der ASPNETCORE_ENVIRONMENT-App-Einstellung fest. Bei einer App mit dem Namen BlazorAzureAppSample erhält der Staging-Slot von App Service den Namen BlazorAzureAppSample/Staging. Erstellen Sie für die Konfiguration des Staging-Slots eine App-Einstellung für ASPNETCORE_ENVIRONMENT mit dem Wert Staging. Bereitstellungssloteinstellung ist für diese Einstellung aktiviert.

Bei Anforderung in einem Browser wird die BlazorAzureAppSample/Staging-App in die Staging-Umgebung unter https://blazorazureappsample-staging.azurewebsites.net geladen.

Beim Laden der App in den Browser wird in der Antwortheadersammlung für blazor.boot.json angegeben, dass der blazor-environment-Headerwert Staging lautet.

App-Einstellungen aus der Datei appsettings.{ENVIRONMENT}.json werden durch die App geladen, wobei der Platzhalter {ENVIRONMENT} für die Umgebung der App steht. Im vorherigen Beispiel werden Einstellungen aus der Datei appsettings.Staging.json geladen.

Lesen der Umgebung in einer Blazor WebAssembly-App

Rufen Sie die Umgebung der App in einer Komponente ab, indem Sie IWebAssemblyHostEnvironment einfügen und die Environment-Eigenschaft lesen.

ReadEnvironment.razor:

@page "/read-environment"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IWebAssemblyHostEnvironment Env

<h1>Environment example</h1>

<p>Environment: @Env.Environment</p>

Clientseitiges Lesen der Umgebung in einer Blazor-Web-App

Sofern das Prerendering nicht für eine Komponente oder für die App deaktiviert ist, wird eine Komponente im .Client-Projekt auf dem Server vorab gerendert. Da der Server über keinen registrierten Dienst vom Typ IWebAssemblyHostEnvironment verfügt, ist es nicht möglich, den Dienst einzufügen und während des serverseitigen Prerenderings die hostumgebungsspezifischen Erweiterungsmethoden und Eigenschaften der Dienstimplementierung zu verwenden. Wenn der Dienst in eine Komponente vom Typ „WebAssembly (interaktiv)“ oder „Auto (interaktiv)“ eingefügt wird, tritt folgender Laufzeitfehler auf:

There is no registered service of type 'Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment'.

Erstellen Sie zur Behebung dieses Fehlers auf dem Server eine benutzerdefinierte Dienstimplementierung für IWebAssemblyHostEnvironment. Fügen Sie dem Serverprojekt die folgende Klasse hinzu:

ServerHostEnvironment.cs:

using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Microsoft.AspNetCore.Components;

public class ServerHostEnvironment(IWebHostEnvironment env, NavigationManager nav) : 
    IWebAssemblyHostEnvironment
{
    public string Environment => env.EnvironmentName;
    public string BaseAddress => nav.BaseUri;
}

Registrieren Sie den Dienst in der Datei Program des Serverprojekts:

builder.Services.TryAddScoped<IWebAssemblyHostEnvironment, ServerHostEnvironment>();

Nun kann der IWebAssemblyHostEnvironment-Dienst in eine Komponente vom Typ „WebAssembly (interaktiv)“ oder „Auto (interaktiv)“ eingefügt und so verwendet werden, wie im Abschnitt Lesen der Umgebung in einer Blazor WebAssembly-App gezeigt.

Das vorangehende Beispiel zeigt gegebenenfalls, dass sich die Serverumgebung von der Clientumgebung unterscheiden kann. Dies wird jedoch nicht empfohlen und kann zu unvorhersehbaren Ergebnissen führen. Beim Festlegen der Umgebung in einer Blazor-Web-App empfiehlt es sich, die serverseitige Projektumgebung und die .Client-Projektumgebung aufeinander abzustimmen. Sehen Sie sich das folgende Szenario in einer Test-App an:

• Implementieren Sie die clientseitige (webassembly) Umgebungseigenschaft mit der Staging-Umgebung über Blazor.start. Ein Beispiel finden Sie im Abschnitt Festlegen der clientseitigen Umgebung per Startkonfiguration.
• Lassen Sie die serverseitige Datei Properties/launchSettings.json unverändert. Lassen Sie den Abschnitt environmentVariables mit der Umgebungsvariablen ASPNETCORE_ENVIRONMENT auf Development festgelegt.

Auf der Benutzeroberfläche können Sie sehen, wie sich der Wert der Eigenschaft IWebAssemblyHostEnvironment.Environment ändert.

Wenn das Prerendering auf dem Server erfolgt, wird die Komponente in der Development-Umgebung gerendert:

Environment: Development

Wenn die Komponente ein bis zwei Sekunden später erneut gerendert wird, ändern sich die Werte, nachdem das Blazor-Paket heruntergeladen und die Blazor WebAssembly-Runtime aktiviert wurde, um zu zeigen, dass der Client in der Staging-Umgebung auf dem Client ausgeführt wird:

Environment: Staging

Das obige Beispiel zeigt, warum empfohlen wird, die Serverumgebung für Entwicklungs-, Test- und Produktionsbereitstellungen so festzulegen, dass sie mit der Clientumgebung übereinstimmt.

Weitere Informationen finden Sie im Abschnitt Fehler beim Auflösen clientseitiger Dienste während des Prerenderings des Artikels ASP.NET Core Blazor-Rendermodi weiter unten in der Blazor-Dokumentation.

Lesen der clientseitigen Umgebung beim Start

Während des Starts macht WebAssemblyHostBuilder die Schnittstelle IWebAssemblyHostEnvironment über die HostEnvironment -Eigenschaft verfügbar, die umgebungsspezifische Logik im Code des Host-Generators ermöglicht.

Gehen Sie in der Program-Datei folgendermaßen vor:

if (builder.HostEnvironment.Environment == "Custom")
{
    ...
};

Die folgenden benutzerfreundlichen, von WebAssemblyHostEnvironmentExtensions bereitgestellten Erweiterungsmethoden ermöglichen die Überprüfung der aktuellen Umgebung auf die Namen Development, Production, Staging sowie auf benutzerdefinierte Umgebungsnamen:

• IsDevelopment
• IsProduction
• IsStaging
• IsEnvironment

Gehen Sie in der Program-Datei folgendermaßen vor:

if (builder.HostEnvironment.IsStaging())
{
    ...
};

if (builder.HostEnvironment.IsEnvironment("Custom"))
{
    ...
};

Die IWebAssemblyHostEnvironment.BaseAddress-Eigenschaft kann während des Starts verwendet werden, wenn der NavigationManager-Dienst nicht verfügbar ist.

Zusätzliche Ressourcen

• Starten von ASP.NET Core Blazor
• Verwenden von mehreren Umgebungen in ASP.NET Core
• GitHub-Repository mit Blazor-Beispielen (dotnet/blazor-samples) (Informationen zum Herunterladen)