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 ASP.NET Core-Laufzeitumgebungen beschriebenen Ansätze für allgemeine ASP.NET Core-Apps.
• Jede Blazor-App: Blazor Konfiguration starten
• Eigenständig Blazor WebAssembly: <WasmApplicationEnvironmentName>-Eigenschaft

Auf dem Client wird die Umgebung für ein Blazor Web Appvom Server über einen HTML-Kommentar bestimmt, mit dem die Entwickler nicht interagieren:

<!--Blazor-WebAssembly:{"environmentName":"Development", ...}-->

Legen Sie für eine eigenständige Blazor WebAssembly App die Umgebung mit der <WasmApplicationEnvironmentName> MSBuild-Eigenschaft in der Projektdatei der App (.csproj) fest. Das folgende Beispiel setzt die Umgebung Staging :

<WasmApplicationEnvironmentName>Staging</WasmApplicationEnvironmentName>

Die Standardumgebungen sind Development für build und Production für publish.

Es gibt mehrere Ansätze zum Festlegen der Umgebung in einer eigenständigen Blazor WebAssembly App während Build-/Veröffentlichungsvorgängen und einen Ansatz für das Starten oder Ausführen einer App auf dem Client:

• Legen Sie den Eigenschaftswert fest, wenn dotnet build oder dotnet publish ausgeführt wird. Im folgenden Beispiel wird die Umgebung auf Staging festgelegt, wenn eine App veröffentlicht wird.

  dotnet publish -p:WasmApplicationEnvironmentName=Staging
  

• Legen Sie die Eigenschaft während der Erstellung oder Veröffentlichung basierend auf der Konfiguration der App in Visual Studio fest. Die folgenden Eigenschaftengruppen können in der Projektdatei der App oder in einer Veröffentlichungskonfigurationsdatei (.pubxml) verwendet werden. Fügen Sie zusätzliche Eigenschaftengruppen für andere verwendete Buildkonfigurationen hinzu.

  <PropertyGroup Condition="'$(Configuration)' == 'Debug'">
    <WasmApplicationEnvironmentName>Development</WasmApplicationEnvironmentName>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(Configuration)' == 'Release'">
    <WasmApplicationEnvironmentName>Production</WasmApplicationEnvironmentName>
  </PropertyGroup>
  

• Die Umgebung kann basierend auf der Verwendung eines Veröffentlichungsprofils festgelegt werden. Im folgenden Beispiel legt die erste Bedingung die Umgebung fest Development , wenn kein Veröffentlichungsprofil verwendet wird (gilt sowohl für Build- als auch Veröffentlichungsvorgänge ohne Profil), während die zweite Bedingung das Festlegen der Umgebung Production abdeckt, wenn ein Veröffentlichungsprofil verwendet wird:

  <PropertyGroup Condition="'$(PublishProfile)' == ''">
    <WasmApplicationEnvironmentName>Development</WasmApplicationEnvironmentName>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(PublishProfile)' != ''">
    <WasmApplicationEnvironmentName>Production</WasmApplicationEnvironmentName>
  </PropertyGroup>
  

• Erstellen Sie einen benutzerdefinierten serverseitigen Web-API-Endpunkt. Die eigenständige Blazor WebAssembly App fordert ihre Umgebung von der Web-API entweder beim Starten der App oder bei Bedarf an, während sie ausgeführt wird. Der Wert sollte an WebAssemblyStartOptions übergeben oder mit withApplicationEnvironment genutzt werden.

  Hinweis

  Dokumentationslinks zur .NET-Referenzquelle laden in der Regel die Standard-Branch des Repositorys, die die aktuelle Entwicklung der nächsten Version von .NET darstellt. Um ein Tag für ein bestimmtes Release auszuwählen, wählen Sie diesen mit der Dropdownliste Switch branches or tags (Branches oder Tags wechseln) aus. Weitere Informationen finden Sie unter How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Auswählen eines Versionstags von ASP.NET Core-Quellcode (dotnet/AspNetCore.Docs #26205)).

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 webAssembly -Konfiguration die >environmentBlazor.start -Eigenschaft setzen, ist es ratsam, die serverseitige Umgebung mit der in der environment -Eigenschaft gesetzten Umgebung abzugleichen. Andernfalls wird die Vordarstellung auf dem Server unter einer anderen Umgebung ausgeführt als das Rendern auf dem Client, was zu beliebigen Effekten führt. Allgemeine Anleitungen zum Festlegen der Umgebung für eine Blazor Web App, finden Sie unter ASP.NET Core-Laufzeitumgebungen.

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.

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.

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. Weitere Informationen und eine Beispielimplementierung finden Sie in der Benutzerdefinierten Dienstimplementierung im Serverabschnitt des Artikels "Prerendering ", der weiter unten in der Blazor Dokumentation angezeigt wird.

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
• ASP.NET Core-Laufzeitumgebungen
• Blazor-Beispiele im GitHub-Repository (dotnet/blazor-samples) (Herunterladen)