Hosten und Bereitstellen von ASP.NET Core Blazor WebAssembly

In diesem Artikel wird erläutert, wie Sie Blazor WebAssembly-Apps hosten und bereitstellen.

Mit dem Blazor WebAssembly-Hostingmodell:

• Die Blazor-App, ihre Abhängigkeiten und die .NET-Runtime werden parallel im Browser heruntergeladen.
• Die App wird direkt im UI-Thread des Browsers ausgeführt.

Dieser Artikel gilt für das Bereitstellungsszenario, in dem die Blazor-App sich auf einem Webserver oder Webservice für statisches Hosting befindet, und .NET nicht zur Unterstützung der Blazor-App verwendet wird. Diese Strategie wird im Abschnitt "Eigenständige Bereitstellung " und anderen Artikeln in diesem Knoten für IIS, Azure-Dienste, Apache, Nginx und GitHub-Seiten behandelt.

Hosten von Unterdomänen und IIS-Unteranwendungen

Für das Unterdomänenhosting ist keine spezielle Konfiguration der App erforderlich. Sie müssen nicht den App-Basispfad (das <base>-Tag in wwwroot/index.html) konfigurieren, um die App in einer Unterdomäne zu hosten.

Für das IIS-Unteranwendungshosting müssen Sie den App-Basispfad festlegen. Weitere Informationen und Links zu weiteren Leitfäden zum IIS-Unteranwendungshosting finden Sie unter Hosten und Bereitstellen mit ASP.NET Core Blazor.

Verringern der maximalen Heapgröße für Browser auf einigen mobilen Geräten

Beim Erstellen einer Blazor-App, die auf dem Client (.Client-Projekt einer Blazor Web App oder einer eigenständigen Blazor WebAssembly-App) ausgeführt wird und auf Browser mobiler Geräte ausgerichtet ist (insbesondere Safari unter iOS), kann es erforderlich sein, den maximalen Arbeitsspeicher für die App mit der MSBuild-Eigenschaft EmccMaximumHeapSize zu reduzieren. Der Standardwert von 2.147.483.648 Byte ist möglicherweise zu groß und könnte zu einem Absturz der App führen, wenn diese versucht, mehr Arbeitsspeicher zuzuweisen, und der Browser dies nicht durchführt. Im folgenden Beispiel wird der Wert in der Datei Program auf 268.435.456 Byte festgelegt:

<EmccMaximumHeapSize>268435456</EmccMaximumHeapSize>

Weitere Informationen zu Mono-/WebAssembly-MSBuild-Eigenschaften und -Zielen finden Sie unter WasmApp.Common.targets (im GitHub-Repository dotnet/runtime).

Webcil-Verpackungsformat für .NET-Assemblies

Webcil ist ein webfreundliches Paketformat für .NET-Assemblys, das die Verwendung von Blazor WebAssembly in restriktiven Netzwerkumgebungen ermöglicht. Webcil-Dateien verwenden einen standardmäßigen WebAssembly-Wrapper, bei dem die Assemblys als WebAssembly-Dateien bereitgestellt werden, die die Standarddateierweiterung .wasm verwenden.

Webcil ist das Standardpaketformat, wenn Sie eine Blazor WebAssembly-App veröffentlichen. Um die Verwendung von Webcil zu deaktivieren, legen Sie die folgende MS Build-Eigenschaft in der Projektdatei der App fest:

<PropertyGroup>
  <WasmEnableWebcil>false</WasmEnableWebcil>
</PropertyGroup>

Anpassen, wie Startressourcen geladen werden

Passen Sie an, wie Startressourcen mithilfe der loadBootResource-API geladen werden. Weitere Informationen finden Sie unter Starten von ASP.NET CoreBlazor.

Komprimierung

Wenn eine Blazor WebAssembly-App veröffentlicht wird, wird die Ausgabe bei der Veröffentlichung statisch komprimiert, um die App-Größe zu verringern und den Aufwand für eine Laufzeitkomprimierung zu beseitigen. Die folgenden Komprimierungsalgorithmen werden verwendet:

• Brotli (höchste Stufe)
• Gzip

Blazor stützt sich darauf, dass der Host die entsprechenden komprimierten Dateien bereitstellt. Beim Hosten einer eigenständigen Blazor WebAssembly-App sind möglicherweise zusätzliche Schritte erforderlich, um sicherzustellen, dass die statisch komprimierten Dateien bereitgestellt werden:

• Informationen zur Komprimierungskonfiguration der Datei web.config von IIS finden Sie im Abschnitt IIS: Brotli- und Gzip-Komprimierung.
• Beim Hosten über statische Hostinglösungen, die die Inhaltsaushandlung für statisch komprimierte Dateien nicht unterstützen, sollten Sie die App so konfigurieren, dass sie die in das Brotli-Format komprimierten Dateien abruft und decodiert:

Rufen Sie den JavaScript Brotli-Decoder aus dem GitHub-Repository google/brotli ab. Die verkleinerte Decoderdatei heißt decode.min.js und befindet sich im Ordner js des Repositorys.

Hinweis

Wenn die verkleinerte Version des decode.js-Skripts (decode.min.js) fehlschlägt, sollten Sie stattdessen versuchen, die nicht verkleinerte Version (decode.js) zu verwenden.

Aktualisieren Sie die App zur Verwendung des Decoders.

Legen Sie wwwroot/index.html in der autostartDatei im false-Tag von Blazor auf <script> fest:

<script src="_framework/blazor.webassembly.js" autostart="false"></script>

Fügen Sie nach dem Blazor-Tag von <script> und vor dem schließenden </body>-Tag den folgenden JavaScript-<script>-Codeblock hinzu. Die folgende Funktion ruft fetch mit cache: 'no-cache' auf, um den Cache des Browsers auf dem neuesten Stand zu halten.

Blazor Web App:

<script type="module">
  import { BrotliDecode } from './decode.min.js';
  Blazor.start({
    webAssembly: {
      loadBootResource: function (type, name, defaultUri, integrity) {
        if (type !== 'dotnetjs' && location.hostname !== 'localhost' && type !== 'configuration' && type !== 'manifest') {
          return (async function () {
            const response = await fetch(defaultUri + '.br', { cache: 'no-cache' });
            if (!response.ok) {
              throw new Error(response.statusText);
            }
            const originalResponseBuffer = await response.arrayBuffer();
            const originalResponseArray = new Int8Array(originalResponseBuffer);
            const decompressedResponseArray = BrotliDecode(originalResponseArray);
            const contentType = type === 
              'dotnetwasm' ? 'application/wasm' : 'application/octet-stream';
            return new Response(decompressedResponseArray, 
              { headers: { 'content-type': contentType } });
          })();
        }
      }
    }
  });
</script>

Blazor WebAssembly eigenständig:

<script type="module">
  import { BrotliDecode } from './decode.min.js';
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      if (type !== 'dotnetjs' && location.hostname !== 'localhost' && type !== 'configuration') {
        return (async function () {
          const response = await fetch(defaultUri + '.br', { cache: 'no-cache' });
          if (!response.ok) {
            throw new Error(response.statusText);
          }
          const originalResponseBuffer = await response.arrayBuffer();
          const originalResponseArray = new Int8Array(originalResponseBuffer);
          const decompressedResponseArray = BrotliDecode(originalResponseArray);
          const contentType = type === 
            'dotnetwasm' ? 'application/wasm' : 'application/octet-stream';
          return new Response(decompressedResponseArray, 
            { headers: { 'content-type': contentType } });
        })();
      }
    }
  });
</script>

Weitere Informationen zum Laden von Startressourcen finden Sie unter Starten von ASP.NET CoreBlazor.

Um die Komprimierung zu deaktivieren, fügen Sie der Projektdatei der App die CompressionEnabled MSBuild-Eigenschaft hinzu, und setzen Sie den Wert auf false:

<PropertyGroup>
  <CompressionEnabled>false</CompressionEnabled>
</PropertyGroup>

Die CompressionEnabled-Eigenschaft kann an den dotnet publish-Befehl mit der folgenden Syntax in einer Befehlsshell übergeben werden:

dotnet publish -p:CompressionEnabled=false

Neu Schreiben von URLs für korrektes Routing

Routinganforderungen für Seitenkomponenten in einer Blazor WebAssembly-App sind nicht so unkompliziert wie Routinganforderungen in einer Blazor Server-App. Betrachten wir eine Blazor WebAssembly-App mit zwei Komponenten:

• Main.razor: Wird im Stammverzeichnis der App geladen und enthält einen Link zur About-Komponente (href="About").
• About.razor: About-Komponente.

Wenn das Standarddokument der App über die Adressleiste des Browsers (z. B. https://www.contoso.com/) angefordert wird, geschieht Folgendes:

1. Der Browser sendet eine Anforderung.
2. Die Standardseite wird zurückgegeben, in der Regel index.html.
3. index.html initialisiert die App.
4. Die Router-Komponente wird geladen, und die RazorMain-Komponente wird gerendert.

Auf der Seite „Main“ kann der Link zur About-Komponente auf dem Client ausgewählt werden, da der Blazor-Router dafür sorgt, dass der Browser im Internet keine Anforderung für www.contoso.com an About sendet, und stattdessen die gerenderte About-Komponente selbst bereitstellt. Alle Anforderungen von internen Endpunkten innerhalb der Blazor WebAssembly-App funktionieren auf dieselbe Weise: Durch Anforderungen werden keine browserbasierten Anforderungen an serverseitig gehostete Ressourcen im Internet ausgelöst. Der Router verarbeitet Anforderungen intern.

Wenn eine Anforderung für www.contoso.com/About über die Adressleiste des Browsers gesendet wird, tritt bei der Anforderung ein Fehler auf. Diese Ressource ist im Internethost der App nicht vorhanden. Daher wird die Antwort 404 Nicht gefunden zurückgegeben.

Da Browser Anforderungen für clientseitige Seiten an internetbasierte Hosts senden, müssen Webserver und Hostingdienste alle Anforderungen für Ressourcen, die sich nicht physisch auf dem Server befinden, auf der Seite index.html erneut generieren. Wenn index.html zurückgegeben wird, übernimmt der Blazor-Router der App und antwortet mit der richtigen Ressource.

Wenn Sie die Bereitstellung auf einem IIS-Server durchführen, können Sie das URL-Rewrite-Modul mit der veröffentlichten web.config-Datei der App verwenden. Weitere Informationen finden Sie unter Hosten und Bereitstellen von ASP.NET Core Blazor WebAssembly mit IIS.

Eigenständige Bereitstellung

Bei einer eigenständigen Bereitstellung wird die Blazor WebAssembly-App in Form von statischen Dateien bereitgestellt, die von Clients direkt angefordert werden. Jeder Server für statische Dateien kann die Blazor-App bedienen.

Eigenständige Bereitstellungsressourcen werden entweder im /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot-Ordner oder im bin/Release/{TARGET FRAMEWORK}/browser-wasm/publish-Ordner veröffentlicht, wobei der {TARGET FRAMEWORK}-Platzhalter das Ziel-Framework ist.

Azure App Service

Blazor WebAssembly Apps können in Azure App Services unter Windows bereitgestellt werden, die die App in IIS hosten.

Die Bereitstellung einer eigenständigen Blazor WebAssembly-App in Azure App Service für Linux wird derzeit nicht unterstützt. Wir empfehlen, eine eigenständige Blazor WebAssembly App mit Azure Static Web Apps zu hosten, was dieses Szenario unterstützt.

Eigenständig mit Docker

Eine eigenständige Blazor WebAssembly-App wird als Satz statischer Dateien für das Hosting durch einen statischen Dateiserver veröffentlicht.

So hosten Sie die App in Docker

• Wählen Sie einen Docker-Container mit Webserverunterstützung aus, z. B. Nginx oder Apache.
• Kopieren Sie die Ressourcen im Ordner publish in einen Ordner, der auf dem Webserver für die Bereitstellung statischer Dateien definiert ist.
• Wenden Sie nach Bedarf zusätzliche Konfiguration für die Blazor WebAssembly-App an.

Einen Leitfaden zur Konfiguration finden Sie in den folgenden Ressourcen:

• Artikel zu Nginx oder Apache
• Docker-Dokumentation

Hostkonfigurationswerte

Blazor WebAssembly-Apps können die folgenden Hostkonfigurationswerte als Befehlszeilenargumente während der Laufzeit in Entwicklungsumgebungen akzeptieren.

Inhaltsstammverzeichnis

Mit dem Argument --contentroot wird der absolute Pfad zum Verzeichnis festgelegt, das die Inhaltsdateien (das Inhaltsstammverzeichnis) der App enthält. In den folgenden Beispielen ist /content-root-path der Stammpfad für Inhalte der App.

• Geben Sie das Argument beim lokalen Ausführen der App in einer Eingabeaufforderung ein. Führen Sie den folgenden Befehl über das Verzeichnis der App aus:

  dotnet watch --contentroot=/content-root-path
  

• Fügen Sie der Datei launchSettings.json der App im Profil IIS Express einen Eintrag hinzu. Diese Einstellung wird verwendet, wenn die Anwendung mit dem Visual Studio-Debugger und von einer Eingabeaufforderung aus mit dotnet watch (oder dotnet run) ausgeführt wird.

  "commandLineArgs": "--contentroot=/content-root-path"
  

• Geben Sie in Visual Studio das Argument in Eigenschaften>Debuggen>Anwendungsargumente ein. Wenn Sie das Argument auf der Visual Studio-Eigenschaftenseite festlegen, wird das Argument der Datei launchSettings.json hinzugefügt.

  --contentroot=/content-root-path
  

Basispfad

Mit dem Argument --pathbase wird der Basispfad für eine App festgelegt, die lokal mit einem relativen URL-Pfad ausgeführt wird, der sich nicht im Stammverzeichnis befindet (d. h. das <base>-Tag href wird für das Staging und die Produktion auf einen anderen Pfad als / festgelegt). In den folgenden Beispielen ist /relative-URL-path die Pfadbasis der App. Weitere Informationen finden Sie unter ASP.NET Core-App-BasispfadBlazor.

Von großer Bedeutung

Im Gegensatz zu dem Pfad, der für href des <base>-Tags bereitgestellt wird, wird beim Übergeben des /-Argumentwerts kein Schrägstrich (--pathbase) nachgestellt. Wenn der Basispfad einer App im <base>-Tag als <base href="/CoolApp/"> (mit nachgestelltem Schrägstrich) bereitgestellt wird, wird der Argumentwert in der Befehlszeile als --pathbase=/CoolApp (ohne nachgestellten Schrägstrich) übergeben.

• Geben Sie das Argument beim lokalen Ausführen der App in einer Eingabeaufforderung ein. Führen Sie den folgenden Befehl über das Verzeichnis der App aus:

  dotnet watch --pathbase=/relative-URL-path
  

• Fügen Sie der Datei launchSettings.json der App im Profil IIS Express einen Eintrag hinzu. Diese Einstellung wird verwendet, wenn die App mit dem Visual Studio-Debugger und von einer Eingabeaufforderung mit dotnet watch (oder dotnet run) ausgeführt wird.

  "commandLineArgs": "--pathbase=/relative-URL-path"
  

• Geben Sie in Visual Studio das Argument in Eigenschaften>Debuggen>Anwendungsargumente ein. Wenn Sie das Argument auf der Visual Studio-Eigenschaftenseite festlegen, wird das Argument der Datei launchSettings.json hinzugefügt.

  --pathbase=/relative-URL-path
  

Weitere Informationen finden Sie unter ASP.NET Core-App-BasispfadBlazor.

URLs

Mit dem Argument --urls werden die IP- oder Hostadressen zusammen mit Ports und Protokollen festgelegt, auf denen Anfragen entgegengenommen werden sollen.

• Geben Sie das Argument beim lokalen Ausführen der App in einer Eingabeaufforderung ein. Führen Sie den folgenden Befehl über das Verzeichnis der App aus:

  dotnet watch --urls=http://127.0.0.1:0
  

• Fügen Sie der Datei launchSettings.json der App im Profil IIS Express einen Eintrag hinzu. Diese Einstellung wird verwendet, wenn die App mit dem Visual Studio-Debugger und von einer Eingabeaufforderung mit dotnet watch (oder dotnet run) ausgeführt wird.

  "commandLineArgs": "--urls=http://127.0.0.1:0"
  

• Geben Sie in Visual Studio das Argument in Eigenschaften>Debuggen>Anwendungsargumente ein. Wenn Sie das Argument auf der Visual Studio-Eigenschaftenseite festlegen, wird das Argument der Datei launchSettings.json hinzugefügt.

  --urls=http://127.0.0.1:0
  

Konfigurieren des Trimmers

Blazor führt bei jedem Release-Build eine IL-Trimmung (Intermediate Language) durch, um nicht benötigte IL aus den Ausgabe-Assemblys zu entfernen. Weitere Informationen finden Sie unter Konfigurieren des Trimmers für Blazor in ASP.NET Core.

Beschädigung durch Dateien aus einer früheren Bereitstellung

Typisch bei Bereitstellungen:

• Nur die geänderten Dateien werden ersetzt, was in der Regel zu einer schnelleren Bereitstellung führt.
• Vorhandene Dateien, die nicht Teil der neuen Bereitstellung sind, bleiben für die Verwendung durch die neue Bereitstellung erhalten.

In seltenen Fällen kann eine neue Bereitstellung durch veraltete Dateien aus einer vorherigen Bereitstellung beschädigt werden. Wenn Sie die vorhandene Bereitstellung (oder die lokal veröffentlichte App vor der Bereitstellung) vollständig löschen, wird das Problem mit einer beschädigten Bereitstellung möglicherweise behoben. Häufig reicht es aus, die vorhandene Bereitstellung einmal zu löschen, um das Problem auch bei einer DevOps-Build- und -Bereitstellungspipeline zu beheben.

Wenn Sie feststellen, dass das Löschen einer vorherigen Bereitstellung immer erforderlich ist, wenn eine DevOps-Build- und -Bereitstellungspipeline verwendet wird, können Sie der Buildpipeline vorübergehend einen Schritt hinzufügen, um die vorherige Bereitstellung für jede neue Bereitstellung zu löschen, bis Sie die genaue Ursache der Beschädigung behoben haben.