Freigeben über

ASP.NET Core Blazor WebAssembly-.NET-Runtime- und App Bundle-Zwischenspeicherung

  • Artikel

Hinweis

Dies ist nicht die neueste Version dieses Artikels. Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Warnung

Diese Version von ASP.NET Core wird nicht mehr unterstützt. Weitere Informationen finden Sie in der .NET- und .NET Core-Supportrichtlinie. Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Wichtig

Diese Informationen beziehen sich auf ein Vorabversionsprodukt, das vor der kommerziellen Freigabe möglicherweise noch wesentlichen Änderungen unterliegt. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen.

Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Wenn eine Blazor WebAssembly-App im Browser geladen wird, lädt die App Startressourcen vom Server herunter:

  • JavaScript-Code zum Bootstrap der App
  • .NET-Runtime und Assemblys
  • Gebietsschemaspezifische Daten

Mit Ausnahme der Startressourcendatei (blazor.boot.json) von Blazor werden WebAssembly-.NET-Runtime- und App Bundle-Dateien auf Clients zwischengespeichert. Die blazor.boot.json-Datei enthält ein Manifest der Dateien, aus denen die App besteht, die zusammen mit einem Hash des Dateiinhalts heruntergeladen werden muss, der verwendet wird, um zu erkennen, ob sich eine der Startressourcen geändert hat. Blazor speichert heruntergeladene Dateien mithilfe der Browser-Cache-API zwischen.

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 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.

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 Ressourcenzwischenspeicherung und Integritätsüberprüfungen 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 Ressourcenzwischenspeicherung und Integritätsüberprüfungen 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.

Zusätzliche Ressourcen

Startressource wird geladen