Dela via

ASP.NET Core Blazor WebAssembly Fel vid cachelagring och integritetskontroll av .NET-paketet

Anmärkning

Det här är inte den senaste versionen av den här artikeln. För den nuvarande utgåvan, se .NET 9-versionen av den här artikeln .

Varning

Den här versionen av ASP.NET Core stöds inte längre. Mer information finns i .NET och .NET Core Support Policy. För den nuvarande utgåvan, se .NET 9-versionen av den här artikeln .

Viktigt!

Den här informationen gäller en förhandsversionsprodukt som kan ändras avsevärt innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som tillhandahålls här.

För den nuvarande utgåvan, se .NET 9-versionen av den här artikeln .

Den här artikeln beskriver cachelagring av tillgångar för Blazor WebAssembly och hur du diagnostiserar och löser integritetsfel.

När en Blazor WebAssembly app läses in i webbläsaren laddar appen ned startresurser från servern:

  • JavaScript-kod för att starta appen
  • .NET-körtid och samlingar
  • Platspecifika data

Startkonfigurationen Blazor , inlindad i dotnet.js, innehåller ett manifest med fingeravtryck för de filer som utgör appen som måste laddas ned tillsammans med en hash för varje fils innehåll. Appens filer förinstalleras och cachelagras av webbläsaren.

Anmärkning

†I .NET 10 eller senare blazor.boot.json finns inte längre manifestfilen. Om du uppgraderar en app som förlitar sig på manifestfilen för anpassad bearbetning rekommenderar vi att du samlar in informationen direkt från versionen.

När Blazor WebAssembly laddar ned en apps startfiler instrueras webbläsaren att utföra integritetskontroller av svaren. Blazor skickar SHA-256-hashvärden för DLL (.dll), WebAssembly (.wasm) och andra filer. Filhasharna för cachelagrade filer jämförs med hashvärdena i startkonfigurationen. Ett fel genereras av webbläsaren om någon nedladdad fils integritetskontroll misslyckas.

Mer information finns i följande avsnitt i artikeln Grunderna: Statiska filer :

BlazorFörutom startmanifestfilen (blazor.boot.json) cachelagras WebAssembly .NET-runtime- och appsamlingsfiler på klienter. Startkonfigurationen Blazor innehåller ett manifest för de filer som utgör appen som måste laddas ned tillsammans med en hash av filens innehåll som används för att identifiera om någon av startresurserna har ändrats. Blazor cachelagrar nedladdade filer med webbläsarens cache-API .

När Blazor WebAssembly laddar ned en apps startfiler instrueras webbläsaren att utföra integritetskontroller av svaren. Blazor skickar SHA-256-hashvärden för DLL (.dll), WebAssembly (.wasm) och andra filer i startkonfigurationen Blazor , som inte cachelagras på klienter. Filhasharna för cachelagrade filer jämförs med hashvärdena i startkonfigurationen Blazor . För cachelagrade filer med matchande hash använder Blazor de cachelagrade filerna. Annars begärs filer från servern. När en fil har laddats ned kontrolleras dess hash igen för integritetsverifiering. Ett fel genereras av webbläsaren om någon nedladdad fils integritetskontroll misslyckas.

Blazoralgoritm för hantering av filintegritet:

  • Säkerställer att appen inte riskerar att läsa in en inkonsekvent uppsättning filer, till exempel om en ny distribution tillämpas på webbservern medan användaren håller på att ladda ned programfilerna. Inkonsekventa filer kan resultera i en felaktig app.
  • Säkerställer att användarens webbläsare aldrig cachelagrar inkonsekventa eller ogiltiga svar, vilket kan hindra appen från att starta även om användaren uppdaterar sidan manuellt.
  • Gör det säkert att cacha svaren och inte kontrollera ändringar på serversidan tills de förväntade SHA-256-hashvärdena ändras, så att efterföljande sidinläsningar innebär färre begäranden och utförs snabbare.

Om webbservern returnerar svar som inte matchar de förväntade SHA-256-hashvärdena visas ett fel som liknar följande exempel i webbläsarens utvecklarkonsol:

Det gick inte att hitta en giltig sammanfattning i attributet "integritet" för resursenhttps://myapp.example.com/_framework/MyBlazorApp.dllmed den beräknade SHA-256-integriteten "IIa70iwvmEg5WiDV17OpQ5eCztNYqL186J56852RpJY=". Resursen har blockerats.

I de flesta fall indikerar varningen inte något problem med integritetskontroll. I stället innebär varningen vanligtvis att det finns något annat problem.

Information om Blazor WebAssemblystartreferenskälla finns i filen Boot.WebAssembly.ts i dotnet/aspnetcore GitHub-lagringsplatsen.

Anmärkning

Dokumentationslänkar till .NET-referenskällan läser vanligtvis in lagringsplatsens standardgren, vilket representerar den aktuella utvecklingen för nästa version av .NET. Om du vill välja en tagg för en specifik version använder du listrutan Välj bland grenar eller taggar. Mer information finns i Så här väljer du en versionstagg för ASP.NET Core-källkod (dotnet/AspNetCore.Docs #26205).

Diagnostisera integritetsproblem

När en app skapas beskriver det genererade startmanifestet SHA-256-hashvärden för startresurser när byggresultatet skapas. Integritetskontrollen godkänns så länge SHA-256-hashvärdena i startmanifestet matchar filerna som levereras till webbläsaren.

Vanliga orsaker till att detta misslyckas är:

  • Webbserverns svar är ett fel (till exempel ett 404 – Hittades inte eller en 500 – Internt serverfel) i stället för den fil som webbläsaren begärde. Detta rapporteras av webbläsaren som ett integritetskontrollfel och inte som ett svarsfel.
  • Något har ändrat innehållet i filerna mellan versionen och leveransen av filerna till webbläsaren. Detta kan inträffa:
    • Om du eller byggverktygen ändrar build-utdata manuellt.
    • Om någon aspekt av distributionsprocessen ändrade filerna. Om du till exempel använder en Git-baserad distributionsmekanism bör du tänka på att Git transparent konverterar radslut i Windows-stil till Unix-stil om du checkar in filer i Windows och checkar ut dem på Linux. Om du ändrar filradsslut ändras SHA-256-hashvärdena. Undvik det här problemet genom att använda .gitattributes för att behandla byggartefakter som binary filer.
    • Webbservern ändrar filinnehållet som en del av att betjäna dem. Vissa innehållsdistributionsnätverk (CDN) försöker till exempel automatiskt minimera HTML och därmed ändra det. Du kan behöva inaktivera sådana funktioner.
  • Startmanifestet kan inte läsas in korrekt eller cachelagras felaktigt på klienten. Vanliga orsaker är något av följande:
    • Felkonfigurerad eller trasig anpassad utvecklingskod.
    • Ett eller flera felkonfigurerade mellanliggande cachelagringslager.

Så här diagnostiserar du vilka av dessa som gäller i ditt fall:

  1. Observera vilken fil som utlöser felet genom att läsa felmeddelandet.
  2. Öppna webbläsarens utvecklarverktyg och titta på fliken Network. Om det behövs läser du in sidan igen för att se listan över begäranden och svar. Leta reda på filen som utlöser felet i listan.
  3. Kontrollera HTTP-statuskoden i svaret. Om servern returnerar något annat än 200 – OK (eller en annan 2xx-statuskod) har du ett problem på serversidan att diagnostisera. Statuskod 403 innebär till exempel att det finns ett auktoriseringsproblem, medan statuskod 500 innebär att servern misslyckas på ett ospecificerat sätt. Läs loggarna på serversidan för att diagnostisera och åtgärda appen.
  4. Om statuskoden är 200 – OK för resursen kan du titta på svarsinnehållet i webbläsarens utvecklarverktyg och kontrollera att innehållet matchar förväntade data. Ett vanligt problem är till exempel att felkonfigurera routning så att begäranden returnerar dina index.html data även för andra filer. Kontrollera att svar på .wasm begäranden är WebAssembly-binärfiler och att svar på .dll begäranden är .NET-sammansättningsbinärfiler. Annars har du ett problem med ruttning på serversidan som behöver diagnostiseras.
  1. Observera vilken fil som utlöser felet genom att läsa felmeddelandet.
  2. Öppna webbläsarens utvecklarverktyg och titta på fliken Network. Om det behövs läser du in sidan igen för att se listan över begäranden och svar. Leta reda på filen som utlöser felet i listan.
  3. Kontrollera HTTP-statuskoden i svaret. Om servern returnerar något annat än 200 – OK (eller en annan 2xx-statuskod) har du ett problem på serversidan att diagnostisera. Statuskod 403 innebär till exempel att det finns ett auktoriseringsproblem, medan statuskod 500 innebär att servern misslyckas på ett ospecificerat sätt. Läs loggarna på serversidan för att diagnostisera och åtgärda appen.
  4. Om statuskoden är 200 – OK för resursen kan du titta på svarsinnehållet i webbläsarens utvecklarverktyg och kontrollera att innehållet matchar förväntade data. Ett vanligt problem är till exempel att felkonfigurera routning så att begäranden returnerar dina index.html data även för andra filer. Kontrollera att svar på .wasm begäranden är WebAssembly-binärfiler och att svar på .dll begäranden är .NET-sammansättningsbinärfiler. Annars har du ett problem med ruttning på serversidan som behöver diagnostiseras.
  5. Försök att verifiera appens publicerade och distribuerade utdata med Felsöknings-integritet PowerShell-skriptet.

Om du bekräftar att servern returnerar rimligen korrekta data måste det finnas något annat som ändrar innehållet mellan bygget och leveransen av filen. Så här undersöker du detta:

  • Granska byggverktygskedjan och distributionsmekanismen om de ändrar filer när filerna har skapats. Ett exempel på detta är när Git omvandlar filradsslut, enligt beskrivningen tidigare.
  • Granska webbservern eller CDN-konfigurationen om de har konfigurerats för att ändra svar dynamiskt (till exempel försöker minimera HTML). Det är bra att webbservern implementerar HTTP-komprimering (till exempel returnerar content-encoding: br eller content-encoding: gzip), eftersom detta inte påverkar resultatet efter dekomprimering. Det är dock inte okej för webbservern att ändra okomprimerade data.

Felsöka PowerShell-skript för integritetskontroll

Använd powershell-skriptet integrity.ps1 för att verifiera en publicerad och distribuerad Blazor app. Skriptet tillhandahålls för PowerShell Core 7 eller senare som en startpunkt när appen har integritetsproblem som Blazor ramverket inte kan identifiera. Anpassning av skriptet kan krävas för dina appar, inklusive om det körs på version av PowerShell senare än version 7.2.0.

Skriptet kontrollerar filerna i mappen publish och de som har laddats ned från den distribuerade appen för att identifiera problem i de olika manifesten som innehåller integritetskontrollsummor. Dessa kontroller bör identifiera de vanligaste problemen:

  • Du har ändrat en fil i de publicerade utdata utan att inse det.
  • Appen distribuerades inte korrekt till distributionsmålet, eller så ändrades något i distributionsmålets miljö.
  • Det finns skillnader mellan den distribuerade appen och utdata från publiceringen av appen.

Anropa skriptet med följande kommando i ett PowerShell-kommandogränssnitt:

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

I följande exempel körs skriptet på en app som körs lokalt på https://localhost:5001/:

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

Platshållare:

  • {BASE URL}: URL:en för den distribuerade appen. Ett avslutande snedstreck (/) behövs.
  • {PUBLISH OUTPUT FOLDER}: Sökvägen till appens publish mapp eller plats där appen publiceras för distribution.

Anmärkning

När du klonar dotnet/AspNetCore.Docs GitHub-lagringsplatsen kan integrity.ps1-skriptet placeras i karantän av Bitdefender eller någon annan virusskanner som finns i systemet. Vanligtvis fångas filen av en virusskanners heuristisk genomsökning teknik, som bara letar efter mönster i filer som kan indikera förekomsten av skadlig kod. Om du vill förhindra att virusskannern quarantiar filen lägger du till ett undantag till virusskannern innan du klonar lagringsplatsen. Följande exempel är en typisk sökväg till skriptet i ett Windows-system. Justera sökvägen efter behov för andra system. Platshållaren {USER} är användarens sökvägssegment.

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

Varning: Att skapa undantag för virusskanner är farligt och bör endast utföras när du är säker på att filen är säker.

Att jämföra kontrollsumman för en fil med en giltig kontrollsumma garanterar inte filsäkerheten, men att ändra en fil på ett sätt som upprätthåller en kontrollsumma är inte trivialt för skadliga användare. Därför är kontrollsummor användbara som en generell säkerhetsmetod. Jämför kontrollsumman för den lokala integrity.ps1-filen med något av följande värden:

  • SHA256: 32c24cb667d79a701135cb72f6bae490d81703323f61b8af2c7e5e5dc0f0c2bb
  • MD5: 9cee7d7ec86ee809a329b5406fbf21a8

Hämta filens kontrollsumma i Windows OS med följande kommando. Ange sökvägen och filnamnet för platshållaren för {PATH AND FILE NAME} och ange vilken typ av kontrollsumma som ska skapas för platshållaren för {SHA512|MD5}, antingen SHA256 eller MD5:

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

Om du har anledning till oro för att verifieringen av kontrollsumman inte är tillräckligt säker i din miljö kan du kontakta organisationens säkerhetsledare för att få vägledning.

Mer information finns i Översikt över skydd mot hot av Microsoft Defender Antivirus.

Inaktivera integritetskontroll för icke-PWA-appar

I de flesta fall ska du inte inaktivera integritetskontroll. Inaktivering av integritetskontroll löser inte det underliggande problemet som har orsakat oväntade svar och resulterar i att de fördelar som anges tidigare går förlorade.

Det kan finnas fall där webbservern inte kan förlita sig på att returnera konsekventa svar och du inte har något annat val än att tillfälligt inaktivera integritetskontroller tills det underliggande problemet har lösts.

Om du vill inaktivera integritetskontroller läser du in startresurser på klientsidan manuellt och undviker att skicka parametern integrity till anropet fetch .

Om du vill inaktivera integritetskontroller lägger du till följande i en egenskapsgrupp i Blazor WebAssembly-appens projektfil (.csproj):

<BlazorCacheBootResources>false</BlazorCacheBootResources>

BlazorCacheBootResources inaktiverar också Blazorstandardbeteende för cachelagring av .dll, .wasmoch andra filer baserat på deras SHA-256-hashar eftersom egenskapen anger att SHA-256-hashvärdena inte kan förlita sig på korrekthet. Även med den här inställningen kan webbläsarens normala HTTP-cache fortfarande lagra dessa filer, men om detta händer beror på din webbserverkonfiguration och de cache-control headers som den hanterar.

Anmärkning

Egenskapen BlazorCacheBootResources inaktiverar inte integritetskontroller för progressiva webbapplikationer (PWA:er). Vägledning om PWA finns i avsnittet Inaktivera integritetskontroll för PWA:er.

Vi kan inte ange en fullständig lista över scenarier där inaktivering av integritetskontroll krävs. Servrar kan besvara en begäran på godtyckliga sätt utanför omfånget för det Blazor ramverket. Ramverket tillåter föregående metod för att göra appen körbar på bekostnad av att förlora en integritetsgaranti som appen kan tillhandahålla. Återigen rekommenderar vi inte att du inaktiverar integritetskontroll, särskilt inte för produktionsdistributioner. Utvecklare bör försöka lösa det underliggande integritetsproblem som gör att integritetskontroll misslyckas.

Några allmänna fall som kan orsaka integritetsproblem är:

  • Körs på HTTP där integritet inte kan kontrolleras.
  • Om distributionsprocessen ändrar filerna efter publiceringen på något sätt.
  • Om din värd ändrar filerna på något sätt.

Inaktivera integritetskontroll för PWA:er

BlazorPWA-mall (Progressive Web Application) innehåller en föreslagen service-worker.published.js fil som ansvarar för att hämta och lagra programfiler för offlineanvändning. Det här är en separat process från den normala appstartmekanismen och har en egen separat logik för integritetskontroll.

I filen service-worker.published.js finns följande rad:

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

Om du vill inaktivera integritetskontroll tar du bort parametern integrity genom att ändra raden till följande:

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

Återigen innebär inaktivering av integritetskontroll att du förlorar de säkerhetsgarantier som erbjuds av integritetskontroll. Det finns till exempel en risk att om användarens webbläsare cachelagrar appen exakt när du distribuerar en ny version kan den cachelagra vissa filer från den gamla distributionen och vissa från den nya distributionen. Om det händer fastnar appen i ett trasigt tillstånd tills du distribuerar ytterligare en uppdatering.