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 oder Blazor Server: Verwenden Sie einen der in Mehrere Umgebungen in ASP.NET Core verwenden beschriebenen Ansätze für allgemeine ASP.NET Core-Anwendungen.
• Jede Blazor App:
  • Blazor Konfiguration starten
  • Azure App Service
• Blazor WebAssembly: Blazor-Environment Kopfzeile

Auf dem Client für ein Blazor Web Appwird die Umgebung vom Server über eine Middleware ermittelt, die die Umgebung über eine Kopfzeile namens Blazor-Environmentan den Browser übermittelt. Der Header legt die Umgebung fest, wenn der WebAssemblyHost in der clientseitigen Program-Datei (WebAssemblyHostBuilder.CreateDefault) erstellt wird.

Bei einer eigenständigen Blazor WebAssembly -Anwendung, die lokal ausgeführt wird, fügt der Entwicklungsserver den Blazor-Environment -Header mit dem von der Hosting-Umgebung erhaltenen Umgebungsnamen hinzu. Die Hosting-Umgebung setzt die Umgebung aus der Umgebungsvariablen ASPNETCORE_ENVIRONMENT , die in der Datei Properties/launchSettings.json des Projekts festgelegt wurde. Der Standardwert der Umgebungsvariable in einem Projekt, das mit der Projektvorlage Blazor WebAssembly erstellt wurde, ist Development. Weitere Informationen finden Sie im Abschnitt Setzen der clientseitigen Umgebung per Header .

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 in der Blazor.start -Konfiguration die webAssembly>environment -Eigenschaft setzen, ist es ratsam, die serverseitige Umgebung mit der in der environment -Eigenschaft gesetzten Umgebung abzugleichen. 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. Eine allgemeine Anleitung zum Festlegen der Umgebung für ein Blazor Web Appfinden Sie unter Verwenden mehrerer 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 Eigenschaft environment setzt die durch den Blazor-Environment -Headerfestgelegte Umgebung außer Kraft.

Der vorstehende Ansatz legt die Client-Umgebung fest, ohne den Wert des Blazor-Environment -Headers zu ändern, und ändert auch nicht die Konsolenprotokollierung der Startumgebung des Serverprojekts für ein Blazor Web App , das das globale interaktive WebAssembly-Rendering übernommen hat.

Um die Umgebung in einer eigenständigen Blazor WebAssembly -Anwendung oder im .Client -Projekt eines Blazor Web Appauf der Konsole zu protokollieren, fügen Sie den folgenden C#-Code in die Program -Datei ein, nachdem das WebAssemblyHost mit WebAssemblyHostBuilder.CreateDefault erstellt wurde und vor der Zeile, die das Projekt baut 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. Insbesondere muss der Antwort-Header für die _framework/blazor.boot.json-Datei gesetzt werden, aber es schadet nicht, den Header in den Dateiserver-Antworten für andere Blazor-Dateianforderungn oder den gesamten Blazor-Einsatz zu setzen.

Obwohl das Blazor -Framework den Header-Namen in Groß- und Kleinschreibung mit gemischten Buchstaben ausgibt (Blazor-Environment), können Sie auch die Groß- und Kleinschreibung verwenden (blazor-environment, BLAZOR-ENVIRONMENT).

Bei lokalen Entwicklungsläufen mit dem eingebauten Entwicklungsserver von Blazorkönnen Sie den Wert des Blazor-Environment -Headers steuern, indem Sie den Wert der Umgebungsvariablen ASPNETCORE_ENVIRONMENT in der Properties/launchSettings.json -Datei des Projekts setzen. Wenn Sie lokal mit dem Entwicklungsserver arbeiten, ist die Rangfolge für die Bestimmung der Umgebung der App Blazor.start Konfiguration (environment Schlüssel)>Blazor-Environment Antwort-Header (blazor.boot.json Datei) >ASPNETCORE_ENVIRONMENT Umgebungsvariable (launchSettings.json). Sie können den Ansatz der ASPNETCORE_ENVIRONMENT Umgebungsvariablen (launchSettings.json) nicht für eine eingesetzte Blazor WebAssembly App verwenden. Die Technik funktioniert nur mit dem Entwicklungsserver bei lokalen Ausführungen der Anwendung.

IIS

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

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    ...
    <httpProtocol>
      <customHeaders>
        <add name="Blazor-Environment" value="Staging" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>
</configuration>

Hinweis

Um eine benutzerdefinierte web.config -Datei für IIS zu verwenden, die nicht überschrieben wird, wenn die App im Ordner publish veröffentlicht wird, lesen Sie Hosting und Bereitstellung von ASP.NET Core Blazor WebAssembly mit IIS.

Nginx

Für Nginx-Server verwenden Sie die Direktive add_header aus dem ngx_http_headers_module:

http {
    server {
        ...
        location / {
            ...
            add_header Blazor-Environment "Staging";
        }
    }
}

Weitere Informationen finden Sie in den folgenden Ressourcen:

• Nginx-Dokumentation
• Hosten und Bereitstellen von ASP.NET Core Blazor WebAssembly mit Nginx

Apache

Für Apache-Server verwenden Sie die Direktive Header aus dem Modul mod_headers :

<VirtualHost *:80>
    ...
    Header set Blazor-Environment "Staging"
    ...
</VirtualHost>

Weitere Informationen finden Sie in den folgenden Ressourcen:

• Apache-Dokumentation (suchen Sie in der neuesten Version nach „mod_headers“)
• Hosten und Bereitstellen von ASP.NET Core Blazor WebAssembly mit Apache

Festlegen der Umgebung für Azure App Service

Für eine eigenständige Blazor WebAssembly App können Sie die Umgebung manuell über Startkonfiguration oder den Blazor-Environment Headereinstellen.

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

1. Stellen Sie sicher, dass die Umhüllung der Umgebungssegmente in den Namen der App-Einstellungsdateien genau mit der Umhüllung der Umgebungsnamen ü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. Die Einstellung des Einsatzplatzes ist für die 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>

Lesen Sie die Umgebung auf der Client-Seite in einem 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. Wenn Sie die Umgebung in einem Blazor Web Appeinstellen, ist es am besten, wenn Sie die Server- und .Client -Projektumgebungen aufeinander abstimmen. 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 nur ein oder zwei Sekunden später erneut gerendert wird, nachdem das Blazor-Bündel heruntergeladen und die .NET WebAssembly-Runtime aktiviert wurde, ändern sich die Werte, um zu zeigen, dass der Client in der Staging-Umgebung auf dem Client arbeitet:

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.

In der Program-Datei:

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

In der Program-Datei:

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.

Weitere Ressourcen

• AASP.NET Core Blazor startup
• Mehrere Umgebungen in ASP.NET Core verwenden
• Blazor-Beispiele im GitHub-Repository (dotnet/blazor-samples) (Herunterladen)