Delen via

ASP.NET Core Blazor WebAssembly .NET-bundelcaching en integriteitscontrolefouten

Opmerking

Dit is niet de nieuwste versie van dit artikel. Zie de .NET 9-versie van dit artikelvoor de huidige release.

Waarschuwing

Deze versie van ASP.NET Core wordt niet meer ondersteund. Zie de .NET- en .NET Core-ondersteuningsbeleidvoor meer informatie. Zie de .NET 9-versie van dit artikelvoor de huidige release.

Belangrijk

Deze informatie heeft betrekking op een pre-releaseproduct dat aanzienlijk kan worden gewijzigd voordat het commercieel wordt uitgebracht. Microsoft geeft geen garanties, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt verstrekt.

Zie de .NET 9-versie van dit artikelvoor de huidige release.

Dit artikel legt assetcaching uit voor Blazor WebAssembly en hoe u integriteitsproblemen kunt identificeren en verhelpen.

Wanneer een Blazor WebAssembly app in de browser wordt geladen, downloadt de app opstartbronnen van de server:

  • JavaScript-code om de app te bootstrapen
  • .NET runtime en assemblies
  • Locatie-specifieke gegevens

De Blazor opstartconfiguratie, inline geïntegreerd in dotnet.js, bevat een manifest met vingerafdrukken van de bestanden waaruit de app bestaat, dat samen met een hash van de inhoud van elk bestand moet worden gedownload. De bestanden van de app worden vooraf geladen en in de cache opgeslagen in de browser.

Opmerking

†In .NET 10 of hoger is het blazor.boot.json manifestbestand niet meer aanwezig. Als u een app bijwerken die afhankelijk is van het manifestbestand voor aangepaste verwerking, raden we u aan de gegevens rechtstreeks vanuit de build te verzamelen.

Wanneer Blazor WebAssembly de opstartbestanden van een app downloadt, wordt de browser geïnstrueerd om integriteitscontroles uit te voeren op de antwoorden. Blazor verzendt SHA-256-hashwaarden voor DLL (.dll), WebAssembly (.wasm) en andere bestanden. De bestands-hashes van bestanden in de cache worden vergeleken met de hashes in de opstartconfiguratie. Er wordt een fout gegenereerd door de browser als de integriteitscontrole van een gedownload bestand mislukt.

Zie de volgende secties van het artikel Fundamentals: Static files voor meer informatie:

Met uitzondering van Blazorhet opstartmanifestbestand (blazor.boot.json), worden WebAssembly .NET Runtime- en app-bundelbestanden in de cache opgeslagen op clients. De Blazor opstartconfiguratie bevat een manifest van de bestanden waaruit de app bestaat die moet worden gedownload, samen met een hash van de inhoud van het bestand die wordt gebruikt om te detecteren of een van de opstartbronnen is gewijzigd. Blazor plaatst gedownloade bestanden in de cache met behulp van de Cache-API van de browser.

Wanneer Blazor WebAssembly de opstartbestanden van een app downloadt, wordt de browser geïnstrueerd om integriteitscontroles uit te voeren op de antwoorden. Blazor verzendt SHA-256-hashwaarden voor DLL (.dll), WebAssembly (.wasm) en andere bestanden in de opstartconfiguratie, die niet in de Blazor cache worden opgeslagen op clients. De bestands-hashes van bestanden in de cache worden vergeleken met de hashes in de Blazor opstartconfiguratie. Voor bestanden in de cache met een overeenkomende hash gebruikt Blazor de bestanden in de cache. Anders worden bestanden aangevraagd vanaf de server. Nadat een bestand is gedownload, wordt de hash opnieuw gecontroleerd op integriteitsvalidatie. Er wordt een fout gegenereerd door de browser als de integriteitscontrole van een gedownload bestand mislukt.

Blazoralgoritme voor het beheren van bestandsintegriteit:

  • Zorgt ervoor dat de app geen inconsistente set bestanden laadt, bijvoorbeeld als er een nieuwe implementatie wordt toegepast op uw webserver terwijl de gebruiker bezig is met het downloaden van de toepassingsbestanden. Inconsistente bestanden kunnen leiden tot een defecte app.
  • Zorgt ervoor dat de browser van de gebruiker nooit inconsistente of ongeldige antwoorden in de cache opgeslagen, waardoor de app niet kan worden gestart, zelfs als de gebruiker de pagina handmatig vernieuwt.
  • Maakt het veilig om de antwoorden in de cache op te slaan en niet te controleren op wijzigingen aan de serverzijde totdat de verwachte SHA-256-hashes zelf veranderen, zodat de volgende paginabelastingen minder aanvragen omvatten en sneller worden voltooid.

Als de webserver antwoorden retourneert die niet overeenkomen met de verwachte SHA-256-hashes, wordt er een fout weergegeven die lijkt op het volgende voorbeeld in de ontwikkelaarsconsole van de browser:

Kan geen geldige samenvatting vinden in het kenmerk 'integriteit' voor resource https://myapp.example.com/_framework/MyBlazorApp.dll met berekende SHA-256-integriteit 'IIa70iwvmEg5WiDV17OpQ5eCztNYqL186J56852RpJY='. De resource is geblokkeerd.

In de meeste gevallen geeft de waarschuwing geen probleem aan met integriteitscontrole. In plaats daarvan betekent de waarschuwing meestal dat er een ander probleem bestaat.

Voor de opstartreferentiebron van Blazor WebAssembly, zie het bestand Boot.WebAssembly.ts in de GitHub-opslagplaats dotnet/aspnetcore.

Opmerking

Documentatiekoppelingen naar .NET-referentiebron laden meestal de standaardbranch van de opslagplaats, die de huidige ontwikkeling vertegenwoordigt voor de volgende release van .NET. Als u een tag voor een specifieke release wilt selecteren, gebruikt u de Switch branches of tags vervolgkeuzelijst. Zie Een versietag selecteren van ASP.NET Core-broncode (dotnet/AspNetCore.Docs #26205)voor meer informatie.

Integriteitsproblemen diagnosticeren

Wanneer een app is gebouwd, beschrijft het gegenereerde opstartmanifest de SHA-256-hashes van opstartbronnen op het moment dat de build-uitvoer wordt geproduceerd. De integriteitscontrole slaagt zolang de SHA-256-hashes in het opstartmanifest overeenkomen met de bestanden die aan de browser worden geleverd.

Veelvoorkomende redenen waarom dit mislukt, zijn onder andere:

  • Het antwoord van de webserver is een fout (bijvoorbeeld een 404 - Niet gevonden of een 500 - Interne serverfout) in plaats van het bestand dat de browser heeft aangevraagd. Dit wordt door de browser gerapporteerd als een integriteitscontrolefout en niet als reactiefout.
  • Er is iets veranderd in de inhoud van de bestanden tussen de build en levering van de bestanden in de browser. Dit kan gebeuren:
    • Als u of de hulpprogramma's de build-uitvoer handmatig wijzigen.
    • Als een bepaald aspect van het implementatieproces de bestanden heeft gewijzigd. Als u bijvoorbeeld een implementatiemechanisme op basis van Git gebruikt, moet u er rekening mee houden dat Git transparant lijneinden van Windows-stijl converteert naar unix-stijl lijneinden als u bestanden doorvoert in Windows en ze uitcheckt in Linux. Als u de einden van de bestandslijn wijzigt, worden de SHA-256-hashes gewijzigd. U kunt dit probleem voorkomen door gebruik te maken van .gitattributes om buildartefacten te behandelen als binary bestanden.
    • De webserver wijzigt de bestandsinhoud als onderdeel van het leveren ervan. Sommige CDN's (Content Delivery Networks) proberen bijvoorbeeld automatisch HTML te verkleinen (minify), waardoor deze wordt aangepast. Mogelijk moet u dergelijke functies uitschakelen.
  • Het opstartmanifest kan niet correct worden geladen of wordt onjuist opgeslagen in de cache op de client. Veelvoorkomende oorzaken zijn een van de volgende:
    • Aangepaste ontwikkelaarscode is onjuist geconfigureerd of defect.
    • Een of meer verkeerd geconfigureerde tussenliggende cachelagen.

Ga als volgt te werk om te diagnosticeren welke van deze van toepassing is in uw geval:

  1. Let op welk bestand de fout activeert door het foutbericht te lezen.
  2. Open de ontwikkelhulpprogramma's van uw browser en kijk op het tabblad Network. Laad de pagina zo nodig opnieuw om de lijst met aanvragen en antwoorden weer te geven. Zoek het bestand dat de fout in die lijst activeert.
  3. Controleer de HTTP-statuscode in het antwoord. Als de server iets anders retourneert dan 200 - OK (of een andere 2xx-statuscode), hebt u een probleem aan de serverzijde om te diagnosticeren. Statuscode 403 betekent bijvoorbeeld dat er een autorisatieprobleem is, terwijl statuscode 500 betekent dat de server op een niet-opgegeven manier mislukt. Raadpleeg de logboeken aan de serverzijde om de app vast te stellen en op te lossen.
  4. Als de statuscode is 200 - OK voor de resource, bekijkt u de antwoordinhoud in de ontwikkelhulpprogramma's van de browser en controleert u of de inhoud overeenkomt met de verwachte gegevens. Een veelvoorkomend probleem is bijvoorbeeld het onjuist configureren van routering, zodat aanvragen uw index.html gegevens retourneren, zelfs voor andere bestanden. Zorg ervoor dat antwoorden op .wasm aanvragen binaire webassembly-bestanden zijn en dat antwoorden op .dll aanvragen binaire .NET-assemblybestanden zijn. Zo niet, dan hebt u een routeringsprobleem aan de serverzijde dat gediagnosticeerd moet worden.
  1. Let op welk bestand de fout activeert door het foutbericht te lezen.
  2. Open de ontwikkelhulpprogramma's van uw browser en kijk op het tabblad Network. Laad de pagina zo nodig opnieuw om de lijst met aanvragen en antwoorden weer te geven. Zoek het bestand dat de fout in die lijst activeert.
  3. Controleer de HTTP-statuscode in het antwoord. Als de server iets anders retourneert dan 200 - OK (of een andere 2xx-statuscode), hebt u een probleem aan de serverzijde om te diagnosticeren. Statuscode 403 betekent bijvoorbeeld dat er een autorisatieprobleem is, terwijl statuscode 500 betekent dat de server op een niet-opgegeven manier mislukt. Raadpleeg de logboeken aan de serverzijde om de app vast te stellen en op te lossen.
  4. Als de statuscode is 200 - OK voor de resource, bekijkt u de antwoordinhoud in de ontwikkelhulpprogramma's van de browser en controleert u of de inhoud overeenkomt met de verwachte gegevens. Een veelvoorkomend probleem is bijvoorbeeld het onjuist configureren van routering, zodat aanvragen uw index.html gegevens retourneren, zelfs voor andere bestanden. Zorg ervoor dat antwoorden op .wasm aanvragen binaire webassembly-bestanden zijn en dat antwoorden op .dll aanvragen binaire .NET-assemblybestanden zijn. Zo niet, dan hebt u een routeringsprobleem aan de serverzijde dat gediagnosticeerd moet worden.
  5. Probeer de gepubliceerde en geïmplementeerde uitvoer van de app te valideren met de Integriteitsproblemen met powerShell-script oplossen.

Als u bevestigt dat de server plausibel juiste gegevens retourneert, moet er iets anders zijn dat de inhoud wijzigt tussen het bouwen en leveren van het bestand. Ga als volgt te werk om dit te onderzoeken:

  • Bekijk de build toolchain en het implementatiemechanisme voor het geval ze bestanden wijzigen nadat de bestanden zijn gemaakt. Een voorbeeld hiervan is wanneer Git bestandslijneinden transformeert, zoals eerder is beschreven.
  • Bekijk de webserver- of CDN-configuratie voor het geval ze zijn ingesteld om reacties dynamisch te wijzigen (bijvoorbeeld om HTML te minificeren). Het is prima voor de webserver om HTTP-compressie te implementeren (bijvoorbeeld het retourneren van content-encoding: br of content-encoding: gzip), omdat dit geen invloed heeft op het resultaat na decomprimatie. Het is echter niet goed dat de webserver de niet-gecomprimeerde gegevens wijzigt.

Problemen met integriteit van PowerShell-script oplossen

Gebruik het integrity.ps1 PowerShell-script om een gepubliceerde en geïmplementeerde Blazor-app te valideren. Het script wordt geleverd voor PowerShell Core 7 of hoger als uitgangspunt wanneer de app integriteitsproblemen heeft die het Blazor framework niet kan identificeren. Aanpassing van het script is mogelijk vereist voor uw apps, inclusief als het wordt uitgevoerd op een versie van PowerShell hoger dan versie 7.2.0.

Het script controleert de bestanden in de map publish en de bestanden die zijn gedownload van de geïmplementeerde app om problemen te detecteren in de verschillende manifesten die integriteitshashes bevatten. Deze controles moeten de meest voorkomende problemen detecteren:

  • U hebt een bestand in de gepubliceerde uitvoer gewijzigd zonder dit te realiseren.
  • De app is niet correct geïmplementeerd op het implementatiedoel of er is iets gewijzigd in de omgeving van het implementatiedoel.
  • Er zijn verschillen tussen de ingezette app en de uitvoer van het publiceren ervan.

Roep het script aan met de volgende opdracht in een PowerShell-opdrachtshell:

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

In het volgende voorbeeld wordt het script uitgevoerd op een lokaal uitgevoerde app op https://localhost:5001/:

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

Plaatsaanduidingen

  • {BASE URL}: de URL van de geïmplementeerde app. Er is een slash aan het eind (/) vereist.
  • {PUBLISH OUTPUT FOLDER}: het pad naar de publish map of locatie van de app waar de app is gepubliceerd voor implementatie.

Opmerking

Bij het klonen van de dotnet/AspNetCore.Docs GitHub-opslagplaats kan het integrity.ps1 script in quarantaine worden geplaatst door Bitdefender of een andere virusscanner die aanwezig is op het systeem. Meestal wordt het bestand gevangen door de heuristiek scannen van een virusscanner technologie, die alleen zoekt naar patronen in bestanden die de aanwezigheid van malware kunnen aangeven. Als u wilt voorkomen dat de virusscanner het bestand in quarantaine krijgt, voegt u een uitzondering toe aan de virusscanner voordat u de opslagplaats kloont. Het volgende voorbeeld is een typisch pad naar het script op een Windows-systeem. Pas het pad zo nodig aan voor andere systemen. De plaatsaanduiding {USER} is het padsegment van de gebruiker.

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

Waarschuwing: Het maken van virusscanner-uitzonderingen is gevaarlijk en mag alleen worden uitgevoerd wanneer u zeker weet dat het bestand veilig is.

Het vergelijken van de controlesom van een bestand met een geldige controlesomwaarde garandeert geen bestandsveiligheid, maar het wijzigen van een bestand op een manier die een controlesomwaarde onderhoudt, is niet triviaal voor kwaadwillende gebruikers. Daarom zijn controlesommen nuttig als algemene beveiligingsbenadering. Vergelijk de controlesom van het lokale integrity.ps1-bestand met een van de volgende waarden:

  • SHA256: 32c24cb667d79a701135cb72f6bae490d81703323f61b8af2c7e5e5dc0f0c2bb
  • MD5: 9cee7d7ec86ee809a329b5406fbf21a8

Haal de controlesom van het bestand op in het Windows-besturingssysteem met de volgende opdracht. Geef het pad en de bestandsnaam op voor de {PATH AND FILE NAME} tijdelijke aanduiding en geef het type controlesom aan dat je wil genereren voor de {SHA512|MD5} tijdelijke aanduiding: SHA256 of MD5.

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

Als u zorgen hebt dat de controlesomvalidatie niet veilig genoeg is in uw omgeving, raadpleegt u het beveiligingsbeheer van uw organisatie voor hulp.

Zie Overzicht van bedreigingsbeveiliging door Microsoft Defender Antivirusvoor meer informatie.

Integriteitscontrole uitschakelen voor niet-PWA-apps

Schakel in de meeste gevallen de integriteitscontrole niet uit. Het uitschakelen van integriteitscontrole lost het onderliggende probleem dat de onverwachte reacties heeft veroorzaakt niet op en leidt ertoe dat de eerder vermelde voordelen verloren gaan.

Er kunnen gevallen zijn waarin de webserver niet kan worden vertrouwd om consistente antwoorden te retourneren en u geen keuze hebt om integriteitscontroles tijdelijk uit te schakelen totdat het onderliggende probleem is opgelost.

Als u integriteitscontroles wilt uitschakelen, laadt u opstartresources aan de clientzijde handmatig en vermijdt u het doorgeven van de integrity parameter aan de fetch aanroep.

Als u integriteitscontroles wilt uitschakelen, voegt u het volgende toe aan een eigenschapsgroep in het projectbestand van de Blazor WebAssembly-app (.csproj):

<BlazorCacheBootResources>false</BlazorCacheBootResources>

BlazorCacheBootResources schakelt ook het standaardgedrag van Blazorvoor het opslaan van de .dll, .wasmen andere bestanden uit op basis van hun SHA-256-hashes, omdat de eigenschap aangeeft dat de SHA-256-hashes niet kunnen worden vertrouwd op juistheid. Zelfs met deze instelling kan de normale HTTP-cache van de browser deze bestanden nog steeds in de cache opslaan, maar of dit gebeurt, is afhankelijk van de configuratie van uw webserver en de cache-control headers die deze dient.

Opmerking

Met de eigenschap BlazorCacheBootResources worden integriteitscontroles voor Progressive Web Applications (PBA's)niet uitgeschakeld. Zie de sectie Integriteitscontrole uitschakelen voor PWA's voor richtlijnen met betrekking tot PWA's.

We kunnen geen volledige lijst met scenario's opgeven waarin het uitschakelen van integriteitscontrole is vereist. Servers kunnen een aanvraag op willekeurige manieren beantwoorden buiten het bereik van het Blazor framework. Het framework staat toe dat de voorgaande benadering de app uitvoerbaar maakt, maar dit gaat ten koste van het verlies van garantie op integriteit die de app kan bieden. We raden u ook niet aan integriteitscontrole uit te schakelen, met name voor productie-implementaties. Ontwikkelaars moeten proberen het onderliggende integriteitsprobleem op te lossen waardoor integriteitscontrole mislukt.

Enkele algemene gevallen die integriteitsproblemen kunnen veroorzaken, zijn:

  • Wordt uitgevoerd op HTTP waar integriteit niet kan worden gecontroleerd.
  • Als uw implementatieproces de bestanden wijzigt nadat het op een of andere manier is gepubliceerd.
  • Als uw host de bestanden op een of andere manier wijzigt.

Integriteitscontrole voor PWA's uitschakelen

BlazorPWA-sjabloon (Progressive Web Application) bevat een voorgesteld service-worker.published.js-bestand dat verantwoordelijk is voor het ophalen en opslaan van toepassingsbestanden voor offlinegebruik. Dit is een afzonderlijk proces van het normale opstartmechanisme voor apps en heeft een eigen afzonderlijke logica voor integriteitscontrole.

In het service-worker.published.js-bestand is de volgende regel aanwezig:

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

Als u integriteitscontrole wilt uitschakelen, verwijdert u de parameter integrity door de regel te wijzigen in het volgende:

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

Als u integriteitscontrole uitschakelt, verliest u de veiligheidsgaranties die worden geboden door integriteitscontrole. Er bestaat bijvoorbeeld een risico dat als de browser van de gebruiker de app op het exacte moment dat u een nieuwe versie implementeert, bepaalde bestanden van de oude implementatie en sommige bestanden uit de nieuwe implementatie in de cache opslaat. Als dat gebeurt, loopt de app vast in een verbroken status totdat u een verdere update implementeert.