ASP.NET core Blazor WebAssembly runtime .NET e memorizzazione nella cache del bundle dell'app

Nota

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Importante

Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Quando un'app Blazor WebAssembly viene caricata nel browser, l'app scarica le risorse di avvio dal server:

• Codice JavaScript per avviare l'app
• Runtime e assembly .NET
• Dati specifici delle impostazioni locali

BlazorAd eccezione del file di risorse di avvio (blazor.boot.json), il runtime .NET WebAssembly e i file bundle dell'app vengono memorizzati nella cache nei client. Il blazor.boot.json file contiene un manifesto dei file che costituiscono l'app che deve essere scaricata insieme a un hash del contenuto del file usato per rilevare se una delle risorse di avvio è stata modificata. Blazormemorizza nella cache i file scaricati usando l'API cache del browser.

Quando Blazor WebAssembly scarica i file di avvio di un'app, indica al browser di eseguire controlli di integrità sulle risposte. Blazor invia i valori hash SHA-256 per DLL (.dll), WebAssembly (.wasm) e altri file nel blazor.boot.json file. Gli hash dei file memorizzati nella cache vengono confrontati con gli hash nel blazor.boot.json file. Per i file memorizzati nella cache con un hash corrispondente, Blazor usa i file memorizzati nella cache. In caso contrario, i file vengono richiesti dal server. Dopo il download di un file, il relativo hash viene nuovamente controllato per la convalida dell'integrità. Se il controllo di integrità di un file scaricato non riesce, viene generato un errore dal browser.

BlazorAlgoritmo per la gestione dell'integrità dei file:

• Assicura che l'app non rischi di caricare un set di file incoerente, ad esempio se una nuova distribuzione viene applicata al server Web mentre l'utente sta scaricando i file dell'applicazione. I file incoerenti possono causare un malfunzionamento dell'app.
• Assicura che il browser dell'utente non memorizza mai nella cache risposte non coerenti o non valide, impedendo l'avvio dell'app anche se l'utente aggiorna manualmente la pagina.
• Rende sicuro memorizzare nella cache le risposte e non verificare la presenza di modifiche sul lato server fino a quando non cambiano gli hash SHA-256 previsti, quindi i caricamenti di pagina successivi comportano un minor numero di richieste e completano più velocemente.

Se il server Web restituisce risposte che non corrispondono agli hash SHA-256 previsti, viene visualizzato un errore simile all'esempio seguente nella console per sviluppatori del browser:

Impossibile trovare un digest valido nell'attributo 'integrity' per la risorsa 'https://myapp.example.com/_framework/MyBlazorApp.dll' con integrità SHA-256 calcolata 'IIa70iwvmEg5WiDV17OpQ5eCztNYqL186J5652RpJY='. La risorsa è stata bloccata.

Nella maggior parte dei casi, l'avviso non indica un problema con il controllo dell'integrità. L'avviso indica in genere che esiste un altro problema.

Nota

I collegamenti della documentazione all'origine del riferimento .NET in genere caricano il ramo predefinito del repository, che rappresenta lo sviluppo corrente per la versione successiva di .NET. Per selezionare un tag per una versione specifica, usare l'elenco a discesa Switch branches or tags. Per altre informazioni, vedere How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Come selezionare un tag di versione del codice sorgente di ASP.NET - dotnet/AspNetCore.Docs #26205).

Diagnosi dei problemi di integrità

Quando viene compilata un'app, il manifesto generato blazor.boot.json descrive gli hash SHA-256 delle risorse di avvio al momento della produzione dell'output di compilazione. Il controllo di integrità passa fino a quando gli hash SHA-256 corrispondono blazor.boot.json ai file recapitati al browser.

I motivi comuni per cui questo errore non riesce includono:

• La risposta del server Web è un errore (ad esempio, 404 - Non trovato o 500 - Errore interno del server) anziché il file richiesto dal browser. Questo errore viene segnalato dal browser come errore di controllo dell'integrità e non come errore di risposta.
• È stato modificato il contenuto dei file tra la compilazione e il recapito dei file nel browser. Questo problema può verificarsi:
  • Se si o si compilano strumenti manualmente, modificare l'output di compilazione.
  • Se alcuni aspetti del processo di distribuzione hanno modificato i file. Ad esempio, se si usa un meccanismo di distribuzione basato su Git, tenere presente che Git converte in modo trasparente le terminazioni di riga in stile Windows in terminazioni di riga in stile Unix se si esegue il commit di file in Windows e le si estrae in Linux. La modifica delle terminazioni di riga del file modifica gli hash SHA-256. Per evitare questo problema, è consigliabile usare .gitattributes per considerare gli artefatti di compilazione come binary file.
  • Il server Web modifica il contenuto del file come parte della loro gestione. Ad esempio, alcune reti di distribuzione del contenuto (rete CDN) tentano automaticamente di minificare il codice HTML, modificandolo. Potrebbe essere necessario disabilitare tali funzionalità.
• Il blazor.boot.json file non viene caricato correttamente o non viene memorizzato correttamente nella cache nel client. Le cause comuni includono una delle seguenti:
  • Codice per sviluppatori personalizzato non configurato o non funzionante.
  • Uno o più livelli intermedi di memorizzazione nella cache non configurati correttamente.

Per diagnosticare quali di queste si applicano nel caso in uso:

1. Si noti il file che attiva l'errore leggendo il messaggio di errore.
2. Aprire gli strumenti di sviluppo del browser e cercare nella scheda Rete . Se necessario, ricaricare la pagina per visualizzare l'elenco di richieste e risposte. Trovare il file che attiva l'errore in tale elenco.
3. Controllare il codice di stato HTTP nella risposta. Se il server restituisce un valore diverso da 200 - OK (o un altro codice di stato 2xx), si è verificato un problema sul lato server da diagnosticare. Ad esempio, il codice di stato 403 indica che si è verificato un problema di autorizzazione, mentre il codice di stato 500 indica che il server ha esito negativo in modo non specificato. Consultare i log lato server per diagnosticare e correggere l'app.
4. Se il codice di stato è 200 - OK per la risorsa, esaminare il contenuto della risposta negli strumenti di sviluppo del browser e verificare che il contenuto corrisponda ai dati previsti. Ad esempio, un problema comune consiste nel configurare erroneamente il routing in modo che le richieste restituisca i index.html dati anche per altri file. Assicurarsi che le risposte alle .wasm richieste siano file binari WebAssembly e che le risposte alle .dll richieste siano file binari di assembly .NET. In caso contrario, si verifica un problema di routing lato server da diagnosticare.
5. Cercare di convalidare l'output pubblicato e distribuito dell'app con lo script di PowerShell Risolvere i problemi di integrità.

Se si conferma che il server restituisce dati plausibilmente corretti, è necessario modificare il contenuto tra la compilazione e il recapito del file. Per analizzare quanto segue:

• Esaminare la toolchain di compilazione e il meccanismo di distribuzione nel caso in cui modifichi i file dopo la compilazione dei file. Un esempio è quando Git trasforma le terminazioni di riga del file, come descritto in precedenza.
• Esaminare il server Web o rete CDN configurazione nel caso in cui siano configurati per modificare le risposte in modo dinamico, ad esempio cercando di minificare HTML. È consigliabile che il server Web implementi la compressione HTTP(ad esempio, restituendo content-encoding: br o content-encoding: gzip), perché questo non influisce sul risultato dopo la decompressione. Tuttavia, non è consigliabile che il server Web modifichi i dati non compressi.

Risolvere i problemi relativi all'integrità dello script di PowerShell

Usare lo integrity.ps1 script di PowerShell per convalidare un'app pubblicata e distribuita Blazor . Lo script viene fornito per PowerShell Core 7 o versione successiva come punto di partenza quando l'app presenta problemi di integrità che il Blazor framework non è in grado di identificare. La personalizzazione dello script potrebbe essere necessaria per le app, incluso se in esecuzione nella versione di PowerShell successiva alla versione 7.2.0.

Lo script controlla i file nella publish cartella e scaricati dall'app distribuita per rilevare i problemi nei diversi manifesti che contengono hash di integrità. Questi controlli devono rilevare i problemi più comuni:

• È stato modificato un file nell'output pubblicato senza renderlo conto.
• L'app non è stata distribuita correttamente nella destinazione di distribuzione o qualcosa è cambiato nell'ambiente della destinazione di distribuzione.
• Esistono differenze tra l'app distribuita e l'output della pubblicazione dell'app.

Richiamare lo script con il comando seguente in una shell dei comandi di PowerShell:

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

Nell'esempio seguente lo script viene eseguito in un'app in esecuzione in locale in https://localhost:5001/:

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

Segnaposto:

• {BASE URL}: URL dell'app distribuita. È necessaria una barra finale (/).
• {PUBLISH OUTPUT FOLDER}: percorso della cartella o del percorso dell'app publish in cui l'app viene pubblicata per la distribuzione.

Nota

Durante la clonazione del dotnet/AspNetCore.Docs repository GitHub, lo integrity.ps1 script potrebbe essere messo in quarantena da Bitdefender o da un altro scanner di virus presente nel sistema. In genere, il file è intrappolato dalla tecnologia euristica di scansione euristica di uno scanner di virus, che cerca semplicemente modelli nei file che potrebbero indicare la presenza di malware. Per impedire al virus scanner di mettere in quarantena il file, aggiungere un'eccezione allo scanner di virus prima di clonare il repository. L'esempio seguente è un percorso tipico dello script in un sistema Windows. Modificare il percorso in base alle esigenze per altri sistemi. Il segnaposto {USER} è il segmento di percorso dell'utente.

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

Avviso: la creazione di eccezioni dello scanner di virus è pericolosa e deve essere eseguita solo quando si è certi che il file sia sicuro.

Il confronto tra il checksum di un file e un valore di checksum valido non garantisce la sicurezza dei file, ma la modifica di un file in modo da mantenere un valore di checksum non è semplice per gli utenti malintenzionati. Pertanto, i checksum sono utili come approccio di sicurezza generale. Confrontare il checksum del file locale integrity.ps1 con uno dei valori seguenti:

• SHA256: 32c24cb667d79a701135cb72f6bae490d81703323f61b8af2c7e5e5dc0f0c2bb
• MD5: 9cee7d7ec86ee809a329b5406fbf21a8

Ottenere il checksum del file nel sistema operativo Windows con il comando seguente. Specificare il percorso e il nome del file per il {PATH AND FILE NAME} segnaposto e indicare il tipo di checksum da produrre per il {SHA512|MD5} segnaposto, SHA256 o MD5:

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

Se si ha qualche motivo di preoccupazione per cui la convalida del checksum non è abbastanza sicura nell'ambiente in uso, consultare la leadership della sicurezza dell'organizzazione per indicazioni.

Per altre informazioni, vedere Panoramica della protezione dalle minacce per Antivirus Microsoft Defender.

Disabilitare la memorizzazione nella cache delle risorse e i controlli di integrità per le app non PWA

Nella maggior parte dei casi, non disabilitare il controllo dell'integrità. La disabilitazione del controllo dell'integrità non risolve il problema sottostante che ha causato le risposte impreviste e comporta la perdita dei vantaggi elencati in precedenza.

In alcuni casi non è possibile fare affidamento sul server Web per restituire risposte coerenti e non è possibile scegliere se disabilitare temporaneamente i controlli di integrità fino a quando il problema sottostante non viene risolto.

Per disabilitare i controlli di integrità, aggiungere quanto segue a un gruppo di proprietà nel Blazor WebAssembly file di progetto dell'app (.csproj):

<BlazorCacheBootResources>false</BlazorCacheBootResources>

BlazorCacheBootResources disabilita Blazoranche il .dllcomportamento predefinito della memorizzazione nella cache di , .wasme altri file in base ai relativi hash SHA-256 perché la proprietà indica che gli hash SHA-256 non possono essere basati sulla correttezza. Anche con questa impostazione, la normale cache HTTP del browser può comunque memorizzare nella cache tali file, ma indipendentemente dal fatto che ciò avvenga dipende dalla configurazione del server Web e dalle cache-control intestazioni che serve.

Nota

La BlazorCacheBootResources proprietà non disabilita i controlli di integrità per le applicazioni Web progressive (PWA). Per indicazioni sulle pwa, vedere la sezione Disabilitare il controllo dell'integrità per pwa.

Non è possibile fornire un elenco completo degli scenari in cui è necessario disabilitare il controllo dell'integrità. I server possono rispondere a una richiesta in modi arbitrari al di fuori dell'ambito del Blazor framework. Il framework fornisce l'impostazione BlazorCacheBootResources per rendere l'app eseguibile al costo di perdere una garanzia di integrità che l'app può fornire. Anche in questo caso, non è consigliabile disabilitare il controllo dell'integrità, soprattutto per le distribuzioni di produzione. Gli sviluppatori devono cercare di risolvere il problema di integrità sottostante che causa l'esito negativo del controllo dell'integrità.

Alcuni casi generali che possono causare problemi di integrità sono:

• In esecuzione su HTTP in cui non è possibile controllare l'integrità.
• Se il processo di distribuzione modifica i file dopo la pubblicazione in qualsiasi modo.
• Se l'host modifica i file in qualsiasi modo.

Disabilitare la memorizzazione nella cache delle risorse e i controlli di integrità per gli pwa

BlazorIl modello progressive web application (PWA) contiene un file suggerito service-worker.published.js responsabile del recupero e dell'archiviazione dei file dell'applicazione per l'uso offline. Si tratta di un processo separato dal normale meccanismo di avvio dell'app e ha la propria logica di controllo dell'integrità separata.

All'interno del file è presente la service-worker.published.js riga seguente:

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

Per disabilitare il controllo dell'integrità, rimuovere il integrity parametro modificando la riga nel modo seguente:

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

Anche in questo caso, la disabilitazione del controllo dell'integrità significa che si perdono le garanzie di sicurezza offerte dal controllo dell'integrità. Ad esempio, esiste il rischio che se il browser dell'utente memorizza nella cache l'app nel momento esatto in cui si distribuisce una nuova versione, potrebbe memorizzare nella cache alcuni file dalla distribuzione precedente e alcuni dalla nuova distribuzione. In questo caso, l'app rimane bloccata in uno stato interrotto fino a quando non si distribuisce un ulteriore aggiornamento.

Risorse aggiuntive

Caricamento delle risorse di avvio