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

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.

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

<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 eingeführt hat, 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 das 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>

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>

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;
}

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

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)