Hosten und Bereitstellen von ASP.NET Core Blazor WebAssembly

In diesem Artikel wird erläutert, wie Sie eine Blazor WebAssembly-App mithilfe von ASP.NET Core, Content Delivery Networks (CDNs), Dateiservern und GitHub-Seiten hosten und bereitstellen.

Achtung

In diesem Artikel wird auf CentOS verwiesen, eine Linux-Distribution, die sich dem Status „Ende der Lebensdauer“ (End Of Life, EOL) nähert. Sie sollten Ihre Nutzung entsprechend planen. Weitere Informationen finden Sie im Abschnitt CentOS in diesem Artikel.

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 behandelt, der Informationen zum Hosten einer Blazor WebAssembly-App als untergeordnete IIS-App enthält.

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 eigenständige 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-Paketerstellungsformat für .NET-Assemblys

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 des Ladens von Startressourcen

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

Für Blazor muss der Host die entsprechenden komprimierten Dateien bereitstellen. 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 autostart in der wwwroot/index.htmlDatei im <script>-Tag von Blazor auf false fest:

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

Fügen Sie nach dem <script>-Tag von Blazor und vor dem schließenden </body>-Tag den folgenden JavaScript-<script>-Codeblock hinzu.

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

Erneutes Generieren von URLs für ein ordnungsgemäßes 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 startet 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 About an www.contoso.com 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 im Abschnitt 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 im Ordner /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot veröffentlicht.

Azure App Service

Blazor WebAssembly-Apps können in Azure App Service unter Windows bereitgestellt werden. Dort wird die App auf IIS gehostet.

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.

Azure Static Web Apps

Stellen Sie eine Blazor WebAssembly-App für Azure Static Web Apps mit einem der folgenden Ansätze bereit:

• Bereitstellen aus Visual Studio
• Bereitstellung aus GitHub

Bereitstellen aus Visual Studio

Erstellen Sie zum Bereitstellen über Visual Studio ein Veröffentlichungsprofil für Azure Static Web Apps:

1. Speichern Sie alle nicht gespeicherten Arbeiten im Projekt, da während des Prozesses möglicherweise ein Neustart von Visual Studio erforderlich ist.

2. Wählen Sie auf der Benutzeroberfläche Veröffentlichen in Visual Studio Ziel>Azure>Bestimmtes Ziel>Azure Static Web Apps aus, um ein Veröffentlichungsprofil zu erstellen.

3. Wenn die Azure WebJobs Tools-Komponente für Visual Studio nicht installiert ist, wird eine Aufforderung zum Installieren der ASP.NET- und Webentwicklungskomponente angezeigt. Befolgen Sie die Anweisungen, um die Tools mithilfe des Visual Studio-Installers zu installieren. Visual Studio wird während der Installation der Tools automatisch geschlossen und wieder geöffnet. Nachdem die Tools installiert wurden, beginnen Sie mit dem ersten Schritt, um das Veröffentlichungsprofil zu erstellen.

4. Geben Sie in der Konfiguration des Veröffentlichungsprofils den Namen des Abonnements an. Wählen Sie eine vorhandene Instanz aus, oder wählen Sie Neue Instanz erstellen aus. Legen Sie beim Erstellen einer neuen Instanz auf der Benutzeroberfläche Statische Web-App erstellen im Azure-Portal Bereitstellungsdetails>Quelle auf Andere fest. Warten Sie, bis die Bereitstellung im Azure-Portal abgeschlossen ist, bevor Sie fortfahren.

5. Wählen Sie in der Konfiguration des Veröffentlichungsprofils die Azure Static Web Apps-Instanz aus der Ressourcengruppe der Instanz aus. Wählen Sie Fertig stellen aus, um das Veröffentlichungsprofil zu erstellen. Wenn Visual Studio zur Installation der Static Web Apps CLI (SWA) auffordert, installieren Sie die CLI, indem Sie die Aufforderungen befolgen. Für die SWA CLI ist NPM/Node.js (Visual Studio-Dokumentation) erforderlich.

Nachdem das Veröffentlichungsprofil erstellt wurde, stellen Sie die App in der Azure Static Web Apps-Instanz mithilfe des Veröffentlichungsprofils bereit, indem Sie die Schaltfläche Veröffentlichen auswählen.

Bereitstellen über GitHub

Informationen zum Bereitstellen über ein GitHub-Repository finden Sie unter Tutorial: Erstellen einer statischen Web-App mit Blazor in Azure Static Web Apps.

IIS

IIS ist ein leistungsfähiger Server für statische Dateien für Blazor-Apps. Informationen zum Konfigurieren von IIS zum Hosten von Blazor finden Sie unter Build a Static Website on IIS (Erstellen einer statischen Website unter IIS).

Veröffentlichte Ressourcen werden im Ordner /bin/Release/{TARGET FRAMEWORK}/publish oder bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish erstellt, je nachdem, welche Version des SDK verwendet wird und wo der Platzhalter {TARGET FRAMEWORK} das Zielframework ist. Die Inhalte des Ordners publish werden auf dem Webserver oder über den Hostingdienst gehostet.

web.config

Beim Veröffentlichen eines Blazor-Projekts wird eine web.config-Datei mit der folgenden IIS-Konfiguration erstellt:

• MIME-Typen
• Für die folgenden MIME-Typen wird die HTTP-Komprimierung aktiviert:
  • application/octet-stream
  • application/wasm
• URL-Rewrite-Modul-Regeln werden eingerichtet:
  • Stellen Sie das Unterverzeichnis bereit, in dem sich die statischen Objekte der App befinden (wwwroot/{PATH REQUESTED}).
  • Richten Sie ein SPA-Fallbackrouting ein, sodass Anforderungen für nicht dateibasierte Objekte an das Standarddokument der App im entsprechenden Ordner für statische Objekte (wwwroot/index.html) umgeleitet werden.

Verwenden einer benutzerdefinierten web.config-Datei

So verwenden Sie eine benutzerdefinierte web.config-Datei:

1. Speichern Sie die benutzerdefinierte web.config-Datei im Stammverzeichnis des Projekts.
2. Veröffentlichen Sie das Projekt. Weitere Informationen finden Sie unter Hosten und Bereitstellen von Blazor in ASP.NET Core.

Wenn die Generierung oder Transformation von web.config durch das SDK während der Veröffentlichung entweder die Datei nicht in die veröffentlichten Ressourcen im Ordner publish verschiebt oder die benutzerdefinierte Konfiguration in Ihrer benutzerdefinierten Datei web.config ändert, greifen Sie je nach Bedarf auf einen der folgenden Ansätze zurück, um die volle Kontrolle über den Prozess zu übernehmen:

• Wenn das SDK die Datei nicht generiert, z. B. in einer eigenständigen Blazor WebAssembly-App in /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot oder bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish, je nachdem, welche Version des SDK verwendet wird und wo der Platzhalter {TARGET FRAMEWORK} das Zielframework angibt, legen Sie in der Projektdatei (.csproj) die Eigenschaft <PublishIISAssets> auf true fest. Für eigenständige WebAsssembly-Apps ist dies in der Regel die einzige erforderliche Einstellung, um eine benutzerdefinierte web.config-Datei zu verschieben und die Transformation der Datei durch das SDK zu verhindern.

  <PropertyGroup>
    <PublishIISAssets>true</PublishIISAssets>
  </PropertyGroup>
  

• Deaktivieren Sie die web.config-Transformation des SDK in der Projektdatei (.csproj):

  <PropertyGroup>
    <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
  </PropertyGroup>
  

• Fügen Sie der Projektdatei (.csproj) ein benutzerdefiniertes Ziel hinzu, um eine benutzerdefinierte web.config-Datei zu verschieben. Im folgenden Beispiel wird die benutzerdefinierte web.config-Datei vom Entwickler im Stammverzeichnis des Projekts platziert. Wenn sich die web.config-Datei an anderer Stelle befindet, geben Sie in SourceFiles den Pfad zur Datei an. Das folgende Beispiel gibt den Ordner publish mit $(PublishDir) an, stellt aber für einen benutzerdefinierten Ausgabespeicherort einen Pfad zu DestinationFolder bereit.

  <Target Name="CopyWebConfig" AfterTargets="Publish">
    <Copy SourceFiles="web.config" DestinationFolder="$(PublishDir)" />
  </Target>
  

Installieren des URL-Rewrite-Moduls

Das URL-Rewrite-Modul wird zum Umschreiben von URLs benötigt. Das Modul wird nicht standardmäßig installiert und ist für die Installation als Webserver (IIS)-Rollendienstfunktion nicht verfügbar. Das Modul muss von der IIS-Website heruntergeladen werden. Verwenden Sie den Webplattform-Installer zur Installation des Moduls:

1. Navigieren Sie lokal zur URL-Rewrite-Module-Downloadseite. Wählen Sie zum Herunterladen der englischen Version des WebPI-Installers WebPI aus. Wählen Sie zum Herunterladen des Installers in einer anderen Sprache die entsprechende Architektur für den Server (x86/x64) aus.
2. Kopieren Sie den Installer auf den Server. Führen Sie den Installer aus. Klicken Sie auf die Schaltfläche Installieren, und stimmen Sie den Lizenzbedingungen zu. Der Server muss nach Abschluss der Installation nicht neu gestartet werden.

Konfigurieren der Website

Legen Sie für den physischen Pfad der Website den Ordner der App fest. Der Ordner enthält Folgendes:

• Die Datei web.config, die von IIS zum Konfigurieren der Website verwendet wird, einschließlich der erforderlichen Umleitungsregeln und Dateiinhaltstypen
• Den Ordner der App für statische Objekte

Hosten als IIS-untergeordnete App

Wenn eine eigenständige App als IIS-untergeordnete App gehostet wird, führen Sie einen der folgenden Schritte aus:

• Deaktivieren Sie den vererbten ASP.NET Core Module-Handler.

  Entfernen Sie den Handler in der veröffentlichen Datei web.config der Blazor-App, indem Sie dem <system.webServer>-Abschnitt der Datei einen <handlers>-Abschnitt hinzufügen:

  <handlers>
    <remove name="aspNetCore" />
  </handlers>
  

• Deaktivieren Sie die Vererbung des <system.webServer>-Abschnitts der Stammanwendung (d. h. der übergeordneten Anwendung), indem Sie ein <location>-Element verwenden, bei dem inheritInChildApplications auf false festgelegt ist:

  <?xml version="1.0" encoding="utf-8"?>
  <configuration>
    <location path="." inheritInChildApplications="false">
      <system.webServer>
        <handlers>
          <add name="aspNetCore" ... />
        </handlers>
        <aspNetCore ... />
      </system.webServer>
    </location>
  </configuration>
  

  Hinweis

  Die Deaktivierte Vererbung des Abschnitts <system.webServer> der Stamm-App (übergeordneten App) ist die Standardkonfiguration für veröffentlichte App, bei denen das .NET SDK verwendet wird.

Das Entfernen des Handlers bzw. das Deaktivieren der Vererbung wird zusätzlich zur Konfiguration des Basispfads der App durchgeführt. Legen Sie den Basispfad der App in der Datei index.html der App auf den IIS-Alias fest, der beim Konfigurieren der untergeordneten App in IIS verwendet wird.

Konfigurieren Sie den Basispfad der App, indem Sie den Anweisungen im Host folgen und ASP.NET Core-Artikel Blazor bereitstellen.

Brotli- und Gzip-Komprimierung

Dieser Abschnitt gilt nur für eigenständige Blazor WebAssembly-Apps.

IIS kann über web.config so konfiguriert werden, dass mit Brotli oder Gzip komprimierte Blazor-Ressourcen für eigenständige Blazor WebAssembly-Apps bereitgestellt werden. Eine Beispielkonfigurationsdatei finden Sie unter web.config.

In den folgenden Szenarien kann eine zusätzliche Konfiguration der Beispieldatei web.config erforderlich sein:

• Die Spezifikation der App erfordert eine der folgenden Aktionen:
  • Bereitstellung komprimierter Dateien, die nicht durch die Beispieldatei web.config konfiguriert sind.
  • Bereitstellung komprimierter Dateien, die durch die Beispieldatei web.config in einem nicht komprimierten Format konfiguriert sind.
• Die IIS-Konfiguration des Servers (z. B. applicationHost.config) stellt IIS-Standardwerte auf Serverebene bereit. Je nach Konfiguration auf Serverebene erfordert die App möglicherweise eine andere IIS-Konfiguration als diejenige, die in der Beispieldatei web.config enthalten ist.

Weitere Informationen zu benutzerdefinierten web.config-Dateien finden Sie im Abschnitt Verwenden einer benutzerdefinierten web.config-Datei.

Problembehandlung

Wenn die Fehlermeldung 500: Interner Serverfehler angezeigt wird und IIS-Manager beim Zugriff auf die Konfiguration der Website eine Fehlermeldung anzeigt, überprüfen Sie, ob das URL-Rewrite-Modul installiert ist. Wenn das Modul nicht installiert ist, kann die Datei web.config nicht von IIS analysiert werden. Dadurch wird verhindert, dass die Konfiguration der Website vom IIS-Manager geladen wird, und dass die statischen Blazor-Dateien auf der Website bereitgestellt werden.

Weitere Informationen zur Problembehandlung bei Bereitstellungen in IIS finden Sie unter Problembehandlung bei ASP.NET Core in Azure App Service und IIS.

Azure Storage

Das Hosten statischer Dateien von Azure Storage ermöglicht das serverlose Blazor-App-Hosting. Benutzerdefinierte Domänennamen, das Azure Content Delivery Network (CDN) und HTTPS werden unterstützt.

Wenn der Blobdienst für das Hosten von statischen Websites in einem Speicherkonto aktiviert ist, gehen Sie folgendermaßen vor:

• Legen Sie den Namen des Indexdokuments auf index.html fest.
• Legen Sie den Pfad des Fehlerdokuments auf index.html fest. Razor-Komponenten und andere Endpunkte, bei denen es sich nicht um Dateien handelt, befinden sich nicht in physischen Pfaden in dem statischen Inhalt, der vom Blobdienst gespeichert wird. Wenn eine Anforderung für eine dieser Ressourcen empfangen wird, die vom Blazor-Router verarbeitet werden soll, leitet der vom Blob-Dienst generierte Fehler 404 – Nicht gefunden die Anforderung an den Pfad des Fehlerdokuments weiter. Das Blob index.html wird zurückgegeben, und der Blazor-Router lädt und verarbeitet den Pfad.

Wenn Dateien aufgrund ungeeigneter MIME-Typen im Content-Type-Headern der Dateien nicht zur Laufzeit geladen werden, führen Sie eine der folgenden Aktionen durch:

• Konfigurieren Sie die Tools so, dass beim Bereitstellen der Dateien die richtigen MIME-Typen (Content-Type-Header) bereitgestellt werden.

• Ändern Sie nach Bereitstellung der App die MIME-Typen (Content-Type-Header) für die Dateien.

  Führen Sie im Storage-Explorer (Azure-Portal) für jede Datei folgende Schritte aus:

  1. Klicken Sie mit der rechten Maustaste auf die Datei, und wählen Sie Eigenschaften aus.
  2. Legen Sie ContentType- fest, und klicken Sie auf die Schaltfläche Speichern

Weitere Informationen finden Sie unter Hosten von statischen Websites in Azure Storage.

Nginx

Die folgende Datei nginx.conf wurde vereinfacht, um zu zeigen, wie Nginx so konfiguriert wird, dass die Datei index.html gesendet wird, wenn auf der Festplatte keine entsprechende Datei gefunden wird.

events { }
http {
    server {
        listen 80;

        location / {
            root      /usr/share/nginx/html;
            try_files $uri $uri/ /index.html =404;
        }
    }
}

Wenn Sie limit_req für das NGINX-Burstratenlimit festlegen, erfordern Blazor WebAssembly-Apps möglicherweise einen größeren burst-Parameterwert, um die relativ große Anzahl an Anforderungen zu erfüllen, die eine App stellen kann. Legen Sie den Wert zunächst auf 60 fest:

http {
    server {
        ...

        location / {
            ...

            limit_req zone=one burst=60 nodelay;
        }
    }
}

Erhöhen Sie den Wert, wenn Browserentwicklertools oder Netzwerkdatenverkehrstools angeben, dass für Anforderungen der Statuscode 503 – Dienst nicht verfügbar zurückgegeben wird.

Weitere Informationen zur Nginx-Webserverkonfiguration für die Produktion finden Sie unter Creating NGINX Plus and NGINX Configuration Files (Erstellen von Konfigurationsdateien für NGINX Plus und NGINX).

CentOS

Am 30. Juni 2024 erreicht CentOS den Status „End Of Life (EOL)“ und wird nicht mehr mit Webservern für Blazor WebAssembly -Hosting unterstützt. Weitere Informationen finden Sie in den folgenden Ressourcen:

• CentOS Stream: Eine innovative Zukunft für Enterprise Linux
• CentOS End-of-Life-Anleitung

Apache

So stellen Sie eine Blazor WebAssembly-App für CentOS 7 oder höher bereit:

1. Erstellen Sie die Apache-Konfigurationsdatei. Das folgenden Beispiel zeigt eine vereinfachte Konfigurationsdatei (blazorapp.config):

<VirtualHost *:80>
    ServerName www.example.com
    ServerAlias *.example.com

    DocumentRoot "/var/www/blazorapp"
    ErrorDocument 404 /index.html

    AddType application/wasm .wasm

    <Directory "/var/www/blazorapp">
        Options -Indexes
        AllowOverride None
    </Directory>

    <IfModule mod_deflate.c>
        AddOutputFilterByType DEFLATE text/css
        AddOutputFilterByType DEFLATE application/javascript
        AddOutputFilterByType DEFLATE text/html
        AddOutputFilterByType DEFLATE application/octet-stream
        AddOutputFilterByType DEFLATE application/wasm
        <IfModule mod_setenvif.c>
      BrowserMatch ^Mozilla/4 gzip-only-text/html
      BrowserMatch ^Mozilla/4.0[678] no-gzip
      BrowserMatch bMSIE !no-gzip !gzip-only-text/html
  </IfModule>
    </IfModule>

    ErrorLog /var/log/httpd/blazorapp-error.log
    CustomLog /var/log/httpd/blazorapp-access.log common
</VirtualHost>

1. Platzieren Sie die Apache-Konfigurationsdatei in das /etc/httpd/conf.d/-Verzeichnis, das das standardmäßige Apache-Konfigurationsverzeichnis in CentOS 7 ist.

2. Platzieren Sie die Dateien der App in das /var/www/blazorapp-Verzeichnis (den Speicherort, der für DocumentRoot in der Konfigurationsdatei angegeben ist).

3. Starten Sie den Apache-Dienst neu.

Weitere Informationen finden Sie unter mod_mime und mod_deflate.

GitHub-Seiten

Die GitHub-Standardaktion, mit der Seiten bereitgestellt werden, überspringt die Bereitstellung von Ordnern, deren Namen mit einem Unterstrich beginnen, z. B. den Ordner _framework. Um Ordner bereitzustellen, deren Namen mit einem Unterstrich beginnen, fügen Sie dem Git-Branch eine leere Datei .nojekyll hinzu.

Git behandelt JavaScript-Dateien (JS-Dateien) wie blazor.webassembly.js als Text und konvertiert in der Bereitstellungspipeline Zeilenenden aus CRLF (Wagenrücklauf) in LF (Zeilenvorschub). Diese Änderungen an JS-Dateien generieren andere Dateihashes als Blazor an den Client in der Datei blazor.boot.json sendet. Die Konflikte führen zu Fehlern der Integritätsprüfung auf dem Client. Ein Ansatz zum Beheben dieses Problems besteht darin, eine .gitattributes-Datei mit einer Zeile *.js binary hinzuzufügen, bevor die Ressourcen der App dem Git-Branch hinzugefügt werden. Die Zeile *.js binary konfiguriert Git so, dass JS-Dateien als Binärdateien behandelt werden, wodurch die Verarbeitung der Dateien in der Bereitstellungspipeline vermieden wird. Die Dateihashes der nicht verarbeiteten Dateien stimmen mit den Einträgen in der Datei blazor.boot.json überein, und clientseitige Integritätsprüfungen werden bestanden. Weitere Informationen finden Sie unter ASP.NET Core Blazor WebAssembly .NET Runtime und App Bundle-Zwischenspeicherung.

Fügen Sie zum Verarbeiten von URL-Umschreibungen eine wwwroot/404.html-Datei mit einem Skript hinzu, mit dem die Umleitung der Anforderung an die Seite index.html verarbeitet wird. Ein Beispiel finden Sie im GitHub-Repository SteveSandersonMS/BlazorOnGitHubPages:

• wwwroot/404.html
• Livewebsite

Wenn Sie anstelle einer Organisationswebsite eine Projektwebsite verwenden, aktualisieren Sie das <base>-Tag in wwwroot/index.html. Legen Sie den Wert des href-Attributs auf den Namen des GitHub-Repositorys mit einem nachfolgenden Schrägstrich fest (z. B. /my-repository/). Im GitHub-Repository SteveSandersonMS/BlazorOnGitHubPageswird die href-Basis bei der Veröffentlichung durch die .github/workflows/main.yml-Konfigurationsdatei aktualisiert.

Hinweis

Das GitHub-Repository SteveSandersonMS/BlazorOnGitHubPages befindet sich nicht im Besitz der .NET Foundation oder von Microsoft und wird auch nicht von diesen verwaltet oder 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. Ngnix 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:

• Abschnitt Nginx oder Apache im vorliegenden Artikel
• Docker-Dokumentation

Hostkonfigurationswerte

Blazor WebAssembly-Apps können die folgenden Hostkonfigurationswerte als Befehlszeilenargumente zur Runtime in der Entwicklungsumgebung 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.

• Das Argument wird beim lokalen Ausführen der App bei einer Eingabeaufforderung übergeben. Führen Sie den folgenden Befehl über das Verzeichnis der App aus:

  dotnet run --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 an einer Eingabeaufforderung mit 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 Basispfad einer App.

Wichtig

Im Gegensatz zu dem Pfad, der für href des <base>-Tags bereitgestellt wird, wird beim Übergeben des --pathbase-Argumentwerts kein Schrägstrich (/) 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.

• Das Argument wird beim lokalen Ausführen der App bei einer Eingabeaufforderung übergeben. Führen Sie den folgenden Befehl über das Verzeichnis der App aus:

  dotnet run --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 Anwendung mit dem Visual Studio-Debugger und an einer Eingabeaufforderung mit 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
  

URLs

Mit dem Argument --urls werden die IP-oder Hostadressen mit Ports und Protokollen festgelegt, die auf Anforderungen lauschen sollen.

• Das Argument wird beim lokalen Ausführen der App bei einer Eingabeaufforderung übergeben. Führen Sie den folgenden Befehl über das Verzeichnis der App aus:

  dotnet run --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 Anwendung mit dem Visual Studio-Debugger und an einer Eingabeaufforderung mit 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 auf jedem Releasebuild eine IL-Kürzung (Intermediate Language, Zwischensprache) durch, um nicht benötigte Zwischensprache aus den Ausgabeassemblys zu entfernen. Weitere Informationen finden Sie unter Konfigurieren des Trimmers für Blazor in ASP.NET Core.

Ändern der Dateinamenerweiterung von DLL-Dateien

Dieser Abschnitt gilt für ASP.NET Core 6.x und 7.x. In ASP.NET Core mit .NET 8 oder höher werden .NET-Assemblys als WebAssembly-Dateien (.wasm) im Webcil-Dateiformat bereitgestellt. In ASP.NET Core mit .NET 8 oder höher gilt dieser Abschnitt nur, wenn das Webcil-Dateiformat in der Projektdatei der App deaktiviert wurde.

Wenn eine Firewall, ein Antivirenprogramm oder eine Netzwerksicherheitsappliance die Übertragung der DLL-Dateien (.dll, Dynamic Link Library) der App blockiert, können Sie die Anleitung in diesem Abschnitt befolgen, um die Dateinamenerweiterungen der veröffentlichten DLL-Dateien der App zu ändern.

Hinweis

Das Ändern der Dateinamenerweiterungen der DLL-Dateien der App löst das Problem möglicherweise nicht, da viele Sicherheitssysteme den Inhalt der Dateien der App und nicht nur Dateierweiterungen überprüfen.

Verwenden Sie für einen robusteren Ansatz in Umgebungen, die das Herunterladen oder Ausführen von DLL-Dateien blockieren, ASP.NET Core mit .NET 8 oder höher. Dort werden .NET-Assemblys standardmäßig als WebAssembly-Dateien (.wasm) im Webcil-Dateiformat gepackt. Weitere Informationen finden Sie im Abschnitt Webcil-Paketerstellungsformat für .NET-Assemblys in 8.0 oder einer höheren Version dieses Artikels.

Es gibt Ansätze von Drittanbietern, dieses Problem zu lösen. Weitere Informationen finden Sie in den Ressourcen unter Awesome Blazor.

Verwenden Sie nach Veröffentlichen der App ein Shellskript oder eine DevOps-Buildpipeline, um .dll-Dateien umzubenennen, damit sie eine andere Dateierweiterung im Verzeichnis der von der App veröffentlichten Ausgabe verwenden.

In den folgenden Beispielen:

• Zum Aktualisieren der Dateierweiterungen wird PowerShell (PS) verwendet.
• .dll Dateien werden umbenannt, um die .bin Dateierweiterung aus der Befehlszeile zu verwenden.
• Dateien, die in der veröffentlichten blazor.boot.json Datei mit einer .dll Dateierweiterung aufgelistet sind, werden auf die .bin Dateierweiterung aktualisiert.
• Wenn auch Service-Worker-Ressourcen verwendet werden, aktualisiert ein PowerShell-Befehl die .dll Dateien, welche in der service-worker-assets.js Datei aufgelistet sind, auf die .bin Dateierweiterung.

Um eine andere Dateierweiterung als .bin zu verwenden, ersetzen Sie .bin in den folgenden Befehlen mit der gewünschten Dateierweiterung.

Unter Windows:

dir {PATH} | rename-item -NewName { $_.name -replace ".dll\b",".bin" }
((Get-Content {PATH}\blazor.boot.json -Raw) -replace '.dll"','.bin"') | Set-Content {PATH}\blazor.boot.json

Der {PATH} Platzhalter ist Im vorherigen Befehl der Pfad zum veröffentlichten _framework Ordner (z. B. .\bin\Release\net6.0\browser-wasm\publish\wwwroot\_framework aus dem Stammordner des Projekts).

Wenn auch Service-Worker-Ressourcen verwendet werden:

((Get-Content {PATH}\service-worker-assets.js -Raw) -replace '.dll"','.bin"') | Set-Content {PATH}\service-worker-assets.js

Der {PATH} Platzhalter ist im vorherigen Befehl der Pfad zur veröffentlichten service-worker-assets.js Datei.

Unter Linux oder macOS:

for f in {PATH}/*; do mv "$f" "`echo $f | sed -e 's/\.dll/.bin/g'`"; done
sed -i 's/\.dll"/.bin"/g' {PATH}/blazor.boot.json

Der {PATH} Platzhalter ist Im vorherigen Befehl der Pfad zum veröffentlichten _framework Ordner (z. B. .\bin\Release\net6.0\browser-wasm\publish\wwwroot\_framework aus dem Stammordner des Projekts).

Wenn auch Service-Worker-Ressourcen verwendet werden:

sed -i 's/\.dll"/.bin"/g' {PATH}/service-worker-assets.js

Der {PATH} Platzhalter ist im vorherigen Befehl der Pfad zur veröffentlichten service-worker-assets.js Datei.

Um die komprimierten Dateien blazor.boot.json.gz und blazor.boot.json.br zu verarbeiten, wenden Sie einen der folgenden Ansätze an:

• Entfernen Sie die komprimierten Dateien blazor.boot.json.gz und blazor.boot.json.br. Bei diesem Ansatz ist die Komprimierung deaktiviert.
• Komprimieren Sie die aktualisierte Datei blazor.boot.json erneut.

Der vorausgehende Leitfaden für die komprimierte blazor.boot.json Datei gilt auch, wenn Service-Worker-Ressourcen verwendet werden. Entfernen Sie die Dateien service-worker-assets.js.br und service-worker-assets.js.gz, oder komprimieren Sie diese erneut. Andernfalls treten bei Dateiintegritätsprüfungen im Browser Fehler auf.

Im folgenden Windows-Beispiel für .NET 6 wird ein PowerShell-Skript verwendet, das sich im Stammverzeichnis des Projekts befindet. Das folgende Skript, welches die Komprimierung deaktiviert, ist die Basis für weitere Änderungen, wenn Sie die blazor.boot.json Datei erneut komprimieren möchten.

ChangeDLLExtensions.ps1::

param([string]$filepath,[string]$tfm)
dir $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework | rename-item -NewName { $_.name -replace ".dll\b",".bin" }
((Get-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\blazor.boot.json -Raw) -replace '.dll"','.bin"') | Set-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\blazor.boot.json
Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\blazor.boot.json.gz
Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\blazor.boot.json.br

Wenn auch Service Worker-Assets verwendet werden, fügen Sie die folgenden Befehle hinzu:

((Get-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\service-worker-assets.js -Raw) -replace '.dll"','.bin"') | Set-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\wwwroot\service-worker-assets.js
Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\wwwroot\service-worker-assets.js.gz
Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\wwwroot\service-worker-assets.js.br

In der Projektdatei wird das Skript nach Veröffentlichung der App für die Release Konfiguration ausgeführt:

<Target Name="ChangeDLLFileExtensions" AfterTargets="AfterPublish" Condition="'$(Configuration)'=='Release'">
  <Exec Command="powershell.exe -command &quot;&amp; { .\ChangeDLLExtensions.ps1 '$(SolutionDir)' '$(TargetFramework)'}&quot;" />
</Target>

Hinweis

Wenn Sie dieselben Assemblys umbenennen und verzögert laden, lesen Sie die Anleitung unter Verzögertes Laden von Assemblys in Blazor WebAssembly in ASP.NET Core.

Normalerweise erfordert der Server der App die Konfiguration einer statischen Ressource, um den Dateien die aktualisierte Erweiterung bereitzustellen. Für eine von IIS gehostete App fügen Sie in einer benutzerdefinierten Datei web.config im Abschnitt mit statischem Inhalt (<staticContent>) einen MIME-Zuordnungseintrag (<mimeMap>) für die neue Dateierweiterung hinzu. Im folgenden Beispiel wird davon ausgegangen, dass die Dateierweiterung von .dll in .bin geändert wird:

<staticContent>
  ...
  <mimeMap fileExtension=".bin" mimeType="application/octet-stream" />
  ...
</staticContent>

Schließen Sie ein Update für komprimierte Dateien ein, wenn eine Komprimierung verwendet wird:

<mimeMap fileExtension=".bin.br" mimeType="application/octet-stream" />
<mimeMap fileExtension=".bin.gz" mimeType="application/octet-stream" />

Entfernen Sie den Eintrag für die Dateierweiterung .dll:

- <mimeMap fileExtension=".dll" mimeType="application/octet-stream" />

Entfernen Sie die Einträge für komprimierte .dll-Dateien, wenn eine Komprimierung verwendet wird:

- <mimeMap fileExtension=".dll.br" mimeType="application/octet-stream" />
- <mimeMap fileExtension=".dll.gz" mimeType="application/octet-stream" />

Weitere Informationen zu benutzerdefinierten web.config-Dateien finden Sie im Abschnitt Verwenden einer benutzerdefinierten web.config-Datei.

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.

Lösen von Fehlern bei der Integritätsprüfung

Wenn Blazor WebAssembly die Startdateien einer App herunterlädt, wird der Browser angewiesen, Integritätsprüfungen der Antworten auszuführen. Blazor sendet SHA-256 Hash-Werte für DLL- (.dll), WebAssembly- (.wasm) und andere Dateien in der Datei blazor.boot.json, die auf Clients nicht zwischengespeichert wird. Die Dateihashes zwischengespeicherter Dateien werden mit den Hashes in der Datei blazor.boot.json verglichen. Für zwischengespeicherte Dateien mit einem übereinstimmenden Hashwert verwendet Blazor die zwischengespeicherten Dateien. Andernfalls werden Dateien vom Server angefordert. Nach dem Herunterladen einer Datei wird ihr Hash erneut auf Integrität geprüft. Der Browser generiert eine Fehlermeldung, wenn die Integritätsprüfung einer heruntergeladenen Datei fehlschlägt.

Der Algorithmus von Blazor zur Verwaltung der Integrität von Dateien:

• Stellt sicher, dass kein inkonsistenter Satz von Dateien geladen wird, wenn z. B. eine neue Bereitstellung auf den Webserver angewendet wird, während der Benutzer gerade die Anwendungsdateien herunterlädt. Inkonsistente Dateien können zu einer fehlerhaften App führen.
• Stellt sicher, dass der Browser des Benutzers keine inkonsistenten oder ungültigen Antworten zwischenspeichert, wodurch der Start der App verhindert werden kann, selbst wenn der Benutzer die Seite manuell aktualisiert.
• Ermöglicht eine sichere Zwischenspeicherung der Antworten und prüft erst dann auf serverseitige Änderungen, wenn sich die erwarteten SHA-256-Hashes selbst ändern, sodass nachfolgende Seitenladevorgänge weniger Anforderungen umfassen und schneller abgeschlossen werden.

Wenn der Webserver Antworten zurückgibt, die nicht den erwarteten SHA-256-Hashwerten entsprechen, wird in der Entwicklerkonsole des Browsers eine Fehlermeldung angezeigt, die dem folgenden Beispiel ähnelt:

Fehler bei der Suche nach einem gültigen Digest im Attribut 'integrity' für die Ressource 'https://myapp.example.com/_framework/MyBlazorApp.dll' mit berechneter SHA-256-Integrität'IIa70iwvmEg5WiDV17OpQ5eCztNYqL186J56852RpJY='. The resource has been blocked. (Fehler beim Ermitteln eines gültigen Hashs im 'integrity'-Attribut für die Ressource 'https://myapp.example.com/_framework/MyBlazorApp.dll' mit der berechneten SHA-256-Integrität 'IIa70iwvmEg5WiDV17OpQ5eCztNYqL186J56852RpJY='. Die Ressource wurde blockiert.)

In den meisten Fällen gibt die Warnung kein Problem mit der Integritätsprüfung an. Stattdessen bedeutet die Warnung normalerweise, dass ein anderes Problem vorliegt.

Den Verweis auf die Startquelle von Blazor WebAssembly finden Sie in der Datei Boot.WebAssembly.ts im dotnet/aspnetcore GitHub-Repository.

Hinweis

Dokumentationslinks zur .NET-Referenzquelle laden in der Regel den Standardbranch des Repositorys, der die aktuelle Entwicklung für das nächste Release 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)).

Diagnostizieren von Integritätsproblemen

Wenn eine App erstellt wird, beschreibt das generierte blazor.boot.json-Manifest die SHA-256-Hashwerte der Startressourcen zum Zeitpunkt der Erstellung der Buildausgabe. Die Integritätsprüfung wird durchgeführt, solange die SHA-256-Hashwerte in blazor.boot.json mit den Dateien, die an den Browser übermittelt werden, übereinstimmen.

Häufige Ursachen für Fehler sind unter anderem:

• Die Antwort des Webservers ist eine Fehlermeldung (z. B. 404 – nicht gefunden oder 500 – Interner Serverfehler) anstelle der vom Browser angeforderten Datei. Dies wird vom Browser als Fehler bei der Integritätsprüfung gemeldet, nicht als Antwortfehler.
• Der Inhalt der Dateien wurde zwischen dem Build und der Übermittlung der Dateien an den Browser geändert. Dies kann vorkommen:
  • Wenn Sie oder Buildtools die Buildausgabe manuell ändern.
  • Wenn ein Aspekt des Bereitstellungsprozesses die Dateien geändert hat. Wenn Sie z. B. einen Bereitstellungsmechanismus auf Git-Basis verwenden, bedenken Sie, dass Git die Zeilenenden im Windows-Format transparent in UNIX-Zeilenenden konvertiert, wenn Sie Dateien unter Windows übertragen und unter Linux auschecken. Durch das Ändern von Dateizeilenenden werden die SHA-256-Hashwerte geändert. Um dieses Problem zu vermeiden, sollten Sie die Verwendung von .gitattributes erwägen, um Buildartefakte als binary-Dateien zu behandeln.
  • Der Webserver ändert Dateiinhalte im Rahmen ihrer Bereitstellung. Einige Content Distribution Networks (CDNs) versuchen z. B. automatisch, HTML zu minimieren und damit zu ändern. Sie müssen diese Features möglicherweise deaktivieren.
• Die Datei blazor.boot.json wird nicht ordnungsgemäß geladen oder ist auf dem Client nicht richtig zwischengespeichert. Es folgen die häufigsten Ursachen:
  • Falsch konfigurierter oder fehlerhafter benutzerdefinierter Entwicklercode.
  • Eine oder mehrere falsch konfigurierte Zwischencacheebenen.

So diagnostizieren Sie, was davon in Ihrem Fall zutrifft:

1. Beachten Sie, welche Datei den Fehler auslöst, indem Sie die Fehlermeldung lesen.
2. Öffnen Sie die Entwicklertools Ihres Browsers, und sehen Sie sich die Registerkarte Netzwerk an. Laden Sie ggf. die Seite erneut, um die Liste der Anforderungen und Antworten anzuzeigen. Suchen Sie die Datei, die den in dieser Liste ausgeführten Fehler auslöst.
3. Überprüfen Sie den HTTP-Statuscode in der Antwort. Wenn der Server etwas anderes als 200 – OK (oder einen anderen 2xx-Statuscode) zurückgibt, müssen Sie ein serverseitiges Problem diagnostizieren. Der Statuscode 403 bedeutet beispielsweise, dass ein Autorisierungsproblem vorliegt, während der Statuscode 500 bedeutet, dass ein nicht angegebener Serverfehler aufgetreten ist. Untersuchen Sie serverseitige Protokolle, um die App zu diagnostizieren und zu korrigieren.
4. Wenn der Statuscode für die Ressource 200 – OK lautet, sehen Sie sich den Antwortinhalt in den Entwicklertools des Browsers an, und überprüfen Sie, ob der Inhalt mit den erwarteten Daten übereinstimmt. Ein häufiges Problem ist beispielsweise die falsche Konfiguration des Routings, sodass Anforderungen Ihre index.html-Daten auch für andere Dateien zurückgeben. Stellen Sie sicher, dass Antworten auf .wasm-Anforderungen WebAssembly-Binärdateien und Antworten auf .dll-Anforderungen .NET-Assembly-Binärdateien sind. Wenn dies nicht der Fall ist, müssen Sie ein serverseitiges Routingproblem diagnostizieren.
5. Überprüfen Sie die veröffentlichte und bereitgestellte Ausgabe der App mithilfe des PowerShell-Skripts für die Behebung von Problemen bei der Integrität.

Wenn Sie sich vergewissert haben, dass der Server überzeugend korrekte Daten zurückgibt, muss irgendetwas anderes zwischen Build und Übermittlung der Datei den Inhalt ändern. So ermitteln Sie dies:

• Untersuchen Sie die Buildtoolkette und den Bereitstellungsmechanismus darauf hin, ob sie Dateien nach dem Erstellen ändern. Dies ist beispielsweise der Fall, wenn Git wie zuvor beschrieben Dateizeilenenden transformiert.
• Untersuchen Sie den Webserver oder die CDN-Konfiguration darauf hin, ob sie so eingerichtet sind, dass Antworten dynamisch geändert werden (z. B. der Versuch, HTML zu minimieren). Es ist in Ordnung, dass der Webserver die HTTP-Komprimierung implementiert (z. B. Rückgabe von content-encoding: br oder content-encoding: gzip), da dies das Ergebnis nach der Dekomprimierung nicht beeinträchtigt. Es ist jedoch nicht in Ordnung, dass der Webserver die nicht komprimierten Daten ändert.

PowerShell-Skript für die Behebung von Problemen bei der Integrität

Verwenden Sie das PowerShell-Skript integrity.ps1 zum Überprüfen einer veröffentlichten und bereitgestellten Blazor-App. Das Skript wird für PowerShell Core 7 oder höher als Startpunkt zur Behebung von Integritätsproblemen mit der App bereitgestellt, die vom Blazor-Framework nicht identifiziert werden können. Möglicherweise ist eine Anpassung des Skripts für Ihre Apps erforderlich, z. B. bei der Ausführung unter einer Version von PowerShell höher als Version 7.2.0.

Das Skript überprüft die Dateien im Ordner publish sowie die von der bereitgestellten App heruntergeladenen Dateien, um Probleme in den verschiedenen Manifesten zu erkennen, die Integritätshashes enthalten. Mit diesen Prüfungen sollten sich die häufigsten Probleme erkennen lassen:

• Sie haben eine Datei in der veröffentlichten Ausgabe geändert, ohne es zu bemerken.
• Die App wurde nicht ordnungsgemäß im Bereitstellungsziel bereitgestellt, oder etwas hat sich in der Umgebung des Bereitstellungsziels geändert.
• Es gibt Unterschiede zwischen der bereitgestellten App und der Ausgabe der Veröffentlichung der App.

Rufen Sie das Skript mit dem folgenden Befehl in einer PowerShell-Befehlsshell auf:

.\integrity.ps1 {BASE URL} {PUBLISH OUTPUT FOLDER}

Im folgenden Beispiel wird das Skript für eine lokal ausgeführte App unter https://localhost:5001/ ausgeführt:

.\integrity.ps1 https://localhost:5001/ C:\TestApps\BlazorSample\bin\Release\net6.0\publish\

Platzhalter:

• {BASE URL}: Die URL der bereitgestellten App. Ein nachgestellter Schrägstrich (/) ist erforderlich.
• {PUBLISH OUTPUT FOLDER}: Der Pfad zum publish-Ordner der App oder zu dem Speicherort, in dem die App für die Bereitstellung veröffentlicht wurde.

Hinweis

Beim Klonen GitHub-Repositorys dotnet/AspNetCore.Docs wird das integrity.ps1-Skript möglicherweise durch Bitdefender oder einen anderen Virenscanner im System unter Quarantäne gestellt. In der Regel wird die Datei von der heuristischen Scanfunktion eines Virenscanners abgefangen, die lediglich nach Mustern in Dateien sucht, die auf das Vorhandensein von Schadsoftware hinweisen können. Fügen Sie dem Virenscanner vor dem Klonen des Repositorys eine Ausnahme hinzu, um zu verhindern, dass der Virenscanner die Datei unter Quarantäne stellt. Das folgende Beispiel enthält einen typischen Pfad zum Skript in einem Windows-System. Passen Sie den Pfad je nach Bedarf für andere Systeme an. Der Platzhalter {USER} steht für das Pfadsegment des Benutzers.

C:\Users\{USER}\Documents\GitHub\AspNetCore.Docs\aspnetcore\blazor\host-and-deploy\webassembly\_samples\integrity.ps1

Warnung:Das Erstellen von Virenscanner-Ausnahmen ist gefährlich und sollte nur ausgeführt werden, wenn Sie sicher sind, dass die Datei sicher ist.

Der Vergleich der Prüfsumme einer Datei mit einem gültigen Prüfsummenwert garantiert nicht, dass eine Datei sicher ist. Die Änderung einer Datei, sodass der Prüfsummenwert beibehalten wird, ist allerdings für böswillige Benutzer nicht trivial. Daher sind Prüfsummen als allgemeine Sicherheitsmethode nützlich. Vergleichen Sie die Prüfsumme der lokalen integrity.ps1-Datei mit einem der folgenden Werte:

• SHA256: 32c24cb667d79a701135cb72f6bae490d81703323f61b8af2c7e5e5dc0f0c2bb
• MD5: 9cee7d7ec86ee809a329b5406fbf21a8

Ermitteln Sie die Prüfsumme der Datei im Windows-Betriebssystem mit dem folgenden Befehl. Geben Sie für den {PATH AND FILE NAME}-Platzhalter den Pfad und den Dateinamen an, und geben Sie für den Platzhalter {SHA512|MD5} den Typ der Prüfsumme an, die erzeugt werden soll (SHA256 oder MD5):

CertUtil -hashfile {PATH AND FILE NAME} {SHA256|MD5}

Wenden Sie sich an den Sicherheitsbeauftragten Ihrer Organisation, wenn Sie Bedenken haben, dass die Prüfsummenüberprüfung in Ihrer Umgebung nicht sicher genug ist.

Weitere Informationen finden Sie unter Übersicht über den Bedrohungsschutz durch Microsoft Defender Antivirus.

Deaktivieren der Integritätsprüfung für Nicht-PWA-Apps

Deaktivieren Sie die Integritätsprüfung in den meisten Fällen nicht. Das Deaktivieren der Integritätsprüfung löst nicht das zugrunde liegende Problem, das die unerwarteten Antworten verursacht hat, und führt zu einem Verlust der zuvor aufgeführten Vorteile.

Es kann vorkommen, dass Sie sich nicht darauf verlassen können, dass der Webserver konsistente Antworten zurückgibt, und Sie keine andere Wahl haben, als die Integritätsprüfungen vorübergehend zu deaktivieren, bis das zugrunde liegende Problem behoben ist.

Um die Integritätsprüfungen zu deaktivieren, fügen Sie einer Eigenschaftsgruppe in der Projektdatei der App Blazor WebAssembly (.csproj) Folgendes hinzu:

<BlazorCacheBootResources>false</BlazorCacheBootResources>

BlazorCacheBootResources deaktiviert auch das Standardverhalten von Blazor beim Zwischenspeichern der .dll-, .wasm- und anderer Dateien auf der Grundlage ihrer SHA-256-Hashwerte, da die Eigenschaft angibt, dass die Richtigkeit der SHA-256-Hashwerte nicht verlässlich ist. Auch mit dieser Einstellung kann der normale HTTP-Cache des Browsers diese Dateien weiterhin zwischenspeichern. Ob dies der Fall ist, hängt von der Konfiguration Ihres Webservers und den cache-control-Headern ab, die er bedient.

Hinweis

Die BlazorCacheBootResources-Eigenschaft deaktiviert keine Integritätsprüfungen für progressive Webanwendungen (Progressive Web Applications, PWAs). Anleitungen zu PWAs finden Sie im Abschnitt Deaktivieren der Integritätsprüfung für PWAs.

Wir können keine vollständige Liste der Szenarien erstellen, in denen eine Deaktivierung der Integritätsprüfung erforderlich ist. Server können eine Anforderung auf beliebige Weise außerhalb des Geltungsbereichs des Blazor-Frameworks beantworten. Das Framework bietet die Einstellung BlazorCacheBootResources, um die App ausführbar zu machen, allerdings um den Preis des Verlusts einer Integritätsgarantie, die die App bieten kann. Auch hier raten wir davon ab, die Integritätsprüfung zu deaktivieren, insbesondere bei Bereitstellungen in der Produktion. Entwickler sollten versuchen, das zugrunde liegende Integritätsproblem zu lösen, das dazu führt, dass die Integritätsprüfung fehlschlägt.

Es folgen einige allgemeine Fälle, die Integritätsprobleme verursachen können:

• Ausführung über HTTP, wobei keine Integritätsprüfung durchgeführt werden kann.
• Wenn Ihr Bereitstellungsprozess die Dateien nach der Veröffentlichung in beliebiger Weise modifiziert.
• Wenn Ihr Host die Dateien in beliebiger Weise modifiziert.

Deaktivieren der Integritätsprüfung für PWAs

Die Vorlage für progressive Webanwendungen (Progressive Web Applications, PWAs) von Blazor enthält eine vorgeschlagene service-worker.published.js-Datei, die für das Abrufen und Speichern von Anwendungsdateien für die Offlineverwendung zuständig ist. Dabei handelt es sich um einen vom normalen App-Startmechanismus separaten Prozess, der über eine eigene, separate Logik zur Integritätsprüfung verfügt.

Die service-worker.published.js-Datei enthält folgende Zeile:

.map(asset => new Request(asset.url, { integrity: asset.hash }));

Entfernen Sie zum Deaktivieren der Integritätsprüfung den integrity-Parameter, indem Sie die Zeile wie folgt ändern:

.map(asset => new Request(asset.url));

Noch einmal: Das Deaktivieren der Integritätsprüfung bedeutet, dass Sie die Sicherheitsgarantien verlieren, die die Integritätsprüfung bietet. Beispielsweise besteht folgendes Risiko: Wenn der Browser des Benutzers genau in dem Moment, in dem Sie eine neue Version bereitstellen, die App zwischenspeichert, könnte er einige Dateien aus der alten und einige aus der neuen Bereitstellung zwischenspeichern. Wenn dies der Fall ist, bleibt die App in einem defekten Zustand, bis Sie ein weiteres Update bereitstellen.