Ospitare e distribuire ASP.NET Core Blazor WebAssembly

Questo articolo illustra come ospitare e distribuire Blazor WebAssembly usando ASP.NET Core, rete per la distribuzione di contenuti (RETE CDN), file server e GitHub Pages.

Con il Blazor WebAssembly modello di hosting:

• L'app Blazor , le relative dipendenze e il runtime .NET vengono scaricati nel browser in parallelo.
• L'app viene eseguita direttamente nel thread dell'interfaccia utente del browser.

Sottodominio e hosting di sotto-applicazioni IIS

L'hosting del sottodominio non richiede una configurazione speciale dell'app. Non è necessario configurare il percorso di base dell'app (il <base> tag in wwwroot/index.html) per ospitare l'app in un sottodominio.

L'hosting di sotto-applicazioni IIS richiede di impostare il percorso di base dell'app. Per altre informazioni e collegamenti incrociati per altre indicazioni sull'hosting di applicazioni secondarie IIS, vedere Ospitare e distribuire ASP.NET Core Blazor.

Ridurre le dimensioni massime dell'heap per alcuni browser di dispositivi mobili

<EmccMaximumHeapSize>268435456</EmccMaximumHeapSize>

Per altre informazioni sulle proprietà e le destinazioni di MSBuild Mono/WebAssembly, vedere WasmApp.Common.targets (dotnet/runtime repository GitHub).

<PropertyGroup>
  <WasmEnableWebcil>false</WasmEnableWebcil>
</PropertyGroup>

Personalizzare la modalità di caricamento delle risorse di avvio

Personalizzare la modalità di caricamento delle risorse di avvio tramite l'API loadBootResource . Per altre informazioni, vedere Blazor di Core.

Compressione

Quando un'app Blazor WebAssembly viene pubblicata, l'output viene compresso in modo statico durante la pubblicazione per ridurre le dimensioni dell'app e rimuovere il sovraccarico per la compressione in fase di esecuzione. Vengono usati gli algoritmi di compressione seguenti:

• Brotli (livello più alto)
• Gzip

• Per la configurazione della compressione IIS web.config , vedere la sezione IIS: Brotli e Gzip compression ( Compressione IIS: Brotli e Gzip).
• Quando si ospita in soluzioni di hosting statiche che non supportano la negoziazione del contenuto di file compressi in modo statico, è consigliabile configurare l'app per recuperare e decodificare i file compressi Brotli:

Ottenere il decodificatore Brotli JavaScript dal google/brotli repository GitHub. Il file del decodificatore minimizzato è denominato decode.min.js e si trova nella cartellajs repository.

Aggiornare l'app per usare il decodificatore.

wwwroot/index.html Nel file impostare su autostartfalse sul Blazortag 's<script>:

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

Dopo Blazoril tag e prima del tag di <script> chiusura </body> , aggiungere il blocco di codice <script> JavaScript seguente. La funzione seguente chiama fetch con cache: 'no-cache' per mantenere aggiornata la cache del browser.

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

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

Per altre informazioni sul caricamento delle risorse di avvio, vedere Blazor di Core.

<PropertyGroup>
  <CompressionEnabled>false</CompressionEnabled>
</PropertyGroup>

dotnet publish -p:CompressionEnabled=false

<PropertyGroup>
  <BlazorEnableCompression>false</BlazorEnableCompression>
</PropertyGroup>

dotnet publish -p:BlazorEnableCompression=false

Riscrivere gli URL per il routing corretto

Il routing delle richieste per i componenti di pagina in un'app Blazor WebAssembly non è semplice quanto il routing delle richieste in un'app Blazor Server . Si consideri un'app Blazor WebAssembly con due componenti:

• Main.razor: carica nella radice dell'app e contiene un collegamento al About componente (href="About").
• About.razor: About componente.

Quando viene richiesto il documento predefinito dell'app usando la barra degli indirizzi del browser (ad esempio, https://www.contoso.com/):

1. Il browser invia una richiesta.
2. Viene restituita la pagina predefinita, che in genere index.htmlè .
3. index.html avvia l'app.
4. Router viene caricato il componente e viene eseguito il rendering del RazorMain componente.

Nella pagina Principale selezionare il collegamento al About componente funziona sul client perché il Blazor router impedisce al browser di effettuare una richiesta su Internet per www.contoso.comAbout e gestisce il componente di cui è stato About eseguito il rendering. Tutte le richieste di endpoint interni all'interno dell'app Blazor WebAssembly funzionano allo stesso modo: le richieste non attivano richieste basate su browser alle risorse ospitate nel server su Internet. Le richieste vengono gestite internamente dal router.

Se una richiesta viene effettuata usando la barra degli indirizzi del browser per www.contoso.com/About, la richiesta ha esito negativo. La risorsa non esiste nell'host Internet dell'app, quindi viene restituita la risposta 404 non trovato.

Poiché i browser effettuano richieste agli host basati su Internet per le pagine lato client, i server Web e i servizi di hosting devono riscrivere tutte le richieste di risorse non fisicamente nel server nella index.html pagina. Quando index.html viene restituito, il router dell'app Blazor acquisisce e risponde con la risorsa corretta.

Quando si esegue la distribuzione in un server IIS, è possibile usare il modulo di riscrittura URL con il file pubblicato web.config dell'app. Per altre informazioni, vedere la sezione IIS .

<SelfContained>false</SelfContained>

<RuntimeIdentifier>{RID}</RuntimeIdentifier>

<SelfContained>false</SelfContained>

Distribuzione autonoma

Una distribuzione autonoma funge da Blazor WebAssembly set di file statici richiesti direttamente dai client. Qualsiasi file server statico è in grado di gestire l'app Blazor .

Gli asset di distribuzione autonomi vengono pubblicati nella /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot cartella o bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish\ (a seconda della versione di .NET SDK in uso), in cui il {TARGET FRAMEWORK} segnaposto è il framework di destinazione.

Servizio app di Azure

Blazor WebAssemblyLe app possono essere distribuite in servizi di app Azure in Windows, che ospita l'app in IIS.

La distribuzione di un'app autonoma Blazor WebAssembly nel servizio app Azure per Linux non è attualmente supportata. È consigliabile ospitare un'app autonoma Blazor WebAssembly usando App Web statiche di Azure, che supporta questo scenario.

App Web statiche di Azure

Usare uno degli approcci seguenti per distribuire un'app Blazor WebAssembly in App Web statiche di Azure:

• Distribuire da Visual Studio
• Distribuire da Visual Studio Code
• Eseguire la distribuzione da GitHub

Eseguire la distribuzione da Visual Studio

Per eseguire la distribuzione da Visual Studio, creare un profilo di pubblicazione per App Web statiche di Azure:

1. Salvare eventuali operazioni non salvate nel progetto, perché potrebbe essere necessario riavviare Visual Studio durante il processo.

2. Nell'interfaccia utente pubblica di Visual Studio selezionare Destinazione>> per creare un profilo di pubblicazione.

3. Se il componente Strumenti processi Web di Azure per Visual Studio non è installato, viene visualizzato un prompt per installare il componente di sviluppo web e ASP.NET. Seguire le istruzioni per installare gli strumenti usando il Programma di installazione di Visual Studio. Visual Studio chiude e riapre automaticamente durante l'installazione degli strumenti. Dopo aver installato gli strumenti, iniziare al primo passaggio per creare il profilo di pubblicazione.

4. Nella configurazione del profilo di pubblicazione specificare il nome della sottoscrizione. Selezionare un'istanza esistente o selezionare Crea una nuova istanza. Quando si crea una nuova istanza nell'interfaccia utente crea app Web statica di portale di Azure, impostare Origine > distribuzione su Altro. Attendere il completamento della distribuzione nel portale di Azure prima di procedere.

5. Nella configurazione del profilo di pubblicazione selezionare l'istanza App Web statiche di Azure dal gruppo di risorse dell'istanza. Selezionare Fine per creare il profilo di pubblicazione. Se Visual Studio richiede di installare l'interfaccia della riga di comando di App Web statiche (SWA), installare l'interfaccia della riga di comando seguendo i prompt. L'interfaccia della riga di comando di SWA richiede NPM/Node.js (documentazione di Visual Studio).

Dopo aver creato il profilo di pubblicazione, distribuire l'app nell'istanza di App Web statiche di Azure usando il profilo di pubblicazione selezionando il pulsante Pubblica.

Eseguire la distribuzione da Visual Studio Code

Per eseguire la distribuzione da Visual Studio Code, vedere Avvio rapido: Creare il primo sito statico con App Web statiche di Azure.

Eseguire la distribuzione da GitHub

Per eseguire la distribuzione da un repository GitHub, vedere Esercitazione: Creazione di un'app Web statica con Blazor in App Web statiche di Azure.

IIS

IIS è un file server statico in grado di supportare le Blazor app. Per configurare IIS per ospitare Blazor, vedere Creare un sito Web statico in IIS.

Gli asset pubblicati vengono creati nella /bin/Release/{TARGET FRAMEWORK}/publish cartella o bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish , a seconda della versione dell'SDK usata e della posizione in cui il {TARGET FRAMEWORK} segnaposto è il framework di destinazione. Ospitare il contenuto della publish cartella nel server Web o nel servizio di hosting.

web.config

Quando viene pubblicato un Blazor progetto, viene creato un web.config file con la configurazione IIS seguente:

• MIME (tipi)
• La compressione HTTP è abilitata per i tipi MIME seguenti:
  • application/octet-stream
  • application/wasm
• Vengono stabilite le regole del modulo di riscrittura URL:
  • Gestire la sottodirectory in cui risiedono gli asset statici dell'app (wwwroot/{PATH REQUESTED}).
  • Creare il routing di fallback spa in modo che le richieste di asset non di file vengano reindirizzate al documento predefinito dell'app nella cartella degli asset statici (wwwroot/index.html).

Usare un oggetto personalizzato web.config

Per usare un file personalizzato web.config :

Se la generazione o la trasformazione dell'SDK web.config durante la pubblicazione non sposta il file negli asset pubblicati nella publish cartella o modifica la configurazione personalizzata nel file personalizzato web.config , usare uno degli approcci seguenti in base alle esigenze per assumere il controllo completo del processo:

• Se l'SDK non genera il file, ad esempio, in un'app autonoma in o , a seconda della versione dell'SDK usata e in cui il Blazor WebAssembly segnaposto è il framework di destinazione, impostare la /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot proprietà su bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish nel file di progetto ({TARGET FRAMEWORK}).<PublishIISAssets>true.csproj In genere per le app WebAssembly autonome, questa è l'unica impostazione necessaria per spostare un file personalizzato web.config e impedire la trasformazione del file da parte dell'SDK.

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

• Disabilitare la trasformazione dell'SDK nel file di web.config progetto (.csproj):

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

• Aggiungere una destinazione personalizzata al file di progetto (.csproj) per spostare un file personalizzato web.config . Nell'esempio seguente il file personalizzato web.config viene inserito dallo sviluppatore nella radice del progetto. Se il web.config file si trova altrove, specificare il percorso del file in SourceFiles. Nell'esempio seguente viene specificata la publish cartella con $(PublishDir), ma viene fornito un percorso per DestinationFolder un percorso di output personalizzato.

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

Installare URL Rewrite Module

URL Rewrite Module è necessario per riscrivere gli URL. Il modulo non viene installato per impostazione predefinita e non è disponibile per l'installazione come funzionalità del servizio ruolo Server Web (IIS). Il modulo deve essere scaricato dal sito Web IIS. Usare Installazione guidata piattaforma Web per installare il modulo:

1. In locale, passare alla pagina di download di URL Rewrite Module. Per la versione in lingua inglese selezionare WebPI per scaricare il programma di installazione di Installazione guidata piattaforma Web. Per altre lingue, selezionare l'architettura appropriata per il server (x86 o x64) per scaricare il programma di installazione.
2. Copiare il programma di installazione nel server. Eseguire il programma di installazione. Selezionare il pulsante Installa e accettare le condizioni di licenza. Al termine dell'installazione non è necessario un riavvio del server.

Configurare il sito Web

Impostare il percorso fisico del sito Web sulla cartella dell'app. La cartella contiene:

• File web.config usato da IIS per configurare il sito Web, incluse le regole di reindirizzamento e i tipi di contenuto di file necessari.
• Cartella degli asset statici dell'app.

Ospitare come sotto-app IIS

Se un'app autonoma è ospitata come sotto-app IIS, eseguire una delle operazioni seguenti:

• Disabilitare il gestore del modulo core ASP.NET ereditato.

  Rimuovere il gestore nel Blazor file pubblicato web.config dell'app aggiungendo una <handlers> sezione alla <system.webServer> sezione del file:

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

• Disabilitare l'ereditarietà della sezione dell'app <system.webServer> radice (padre) usando un <location> elemento con inheritInChildApplications impostato su false:

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

  Nota

  La disabilitazione dell'ereditarietà della sezione radice (padre) dell'app <system.webServer> è la configurazione predefinita per le app pubblicate tramite .NET SDK.

La rimozione del gestore o la disabilitazione dell'ereditarietà viene eseguita oltre alla configurazione del percorso di base dell'app. Impostare il percorso di base dell'app nel file dell'app index.html sull'alias IIS usato durante la configurazione dell'app secondaria in IIS.

Configurare il percorso di base dell'app seguendo le indicazioni riportate nell'articolo Host e distribuire ASP.NET Core Blazor .

Compressione Brotli e Gzip

IIS può essere configurato tramite web.config per gestire gli asset compressi Blazor Brotli o Gzip per le app autonome Blazor WebAssembly . Per un file di configurazione di esempio, vedere web.config.

Potrebbe essere necessaria una configurazione aggiuntiva del file di esempio web.config negli scenari seguenti:

• La specifica dell'app richiede uno dei seguenti elementi:
  • Gestione di file compressi non configurati dal file di esempio web.config .
  • Gestione di file compressi configurati dal file di esempio web.config in un formato non compresso.
• La configurazione IIS del server ,ad esempio , applicationHost.configfornisce le impostazioni predefinite iis a livello di server. A seconda della configurazione a livello di server, l'app potrebbe richiedere una configurazione IIS diversa da quella contenuta nel file di esempio web.config .

Per altre informazioni sui file personalizzati web.config , vedere la sezione Usare un file personalizzato web.config .

Risoluzione dei problemi

Se si riceve un errore interno del server 500 e Gestione IIS genera errori durante il tentativo di accedere alla configurazione del sito Web, verificare che sia installato URL Rewrite Module. Quando il modulo non è installato, il web.config file non può essere analizzato da IIS. Ciò impedisce a Gestione IIS di caricare la configurazione del sito Web e il sito Web di gestire Blazori file statici.

Per altre informazioni sulla risoluzione dei problemi relativi alle distribuzioni in IIS, vedere Risolvere i problemi di ASP.NET Core nel servizio app Azure e IIS.

Archiviazione di Azure

Archiviazione di Azure hosting di file statici consente l'hosting di app serverlessBlazor. Sono supportati nomi di dominio personalizzati, la rete per la distribuzione di contenuti (rete CDN) di Azure e HTTPS.

Quando il servizio BLOB è abilitato per l'hosting di siti Web statici in un account di archiviazione:

• Impostare Nome del documento di indice su index.html.
• Impostare Percorso del documento di errore su index.html. Razor i componenti e altri endpoint non file non risiedono nei percorsi fisici nel contenuto statico archiviato dal servizio BLOB. Quando viene ricevuta una richiesta per una di queste risorse che il Blazor router deve gestire, l'errore 404 - Non trovato generato dal servizio BLOB instrada la richiesta al percorso del documento errore. Il index.html BLOB viene restituito e il Blazor router carica ed elabora il percorso.

Se i file non vengono caricati in fase di esecuzione a causa di tipi MIME inappropriati nelle intestazioni dei Content-Type file, eseguire una delle azioni seguenti:

• Configurare gli strumenti per impostare i tipi MIME corretti (Content-Type intestazioni) quando vengono distribuiti i file.

• Modificare i tipi MIME (Content-Type intestazioni) per i file dopo la distribuzione dell'app.

  In Storage Explorer (portale di Azure) per ogni file:

  1. Fare clic con il pulsante destro del mouse sul file e selezionare Proprietà.
  2. Impostare ContentType e selezionare il pulsante Salva.

Per altre informazioni, vedere Hosting di siti Web statici in Archiviazione di Azure.

Nginx

Il file seguente nginx.conf è semplificato per mostrare come configurare Nginx per inviare il index.html file ogni volta che non riesce a trovare un file corrispondente su disco.

events { }
http {
    server {
        listen 80;

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

Quando si imposta il limite di velocità di burst NGINX con limit_req, Blazor WebAssembly le app possono richiedere un valore di parametro di grandi dimensioni burst per supportare il numero relativamente elevato di richieste effettuate da un'app. Inizialmente, impostare il valore su almeno 60:

http {
    server {
        ...

        location / {
            ...

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

Aumentare il valore se gli strumenti di sviluppo del browser o uno strumento di traffico di rete indicano che le richieste ricevono un codice di stato 503 - Servizio non disponibile .

Per altre informazioni sulla configurazione del server Web Nginx in ambiente di produzione, vedere Creating NGINX Plus and NGINX Configuration Files (Creazione di file di configurazione NGINX Plus e NGINX).

Apache

Per distribuire un'app Blazor WebAssembly in Apache:

1. Posizionare il file di configurazione apache nella /etc/httpd/conf.d/ directory .

2. Posizionare gli asset pubblicati dell'app (/bin/Release/{TARGET FRAMEWORK}/publish/wwwroot, dove il {TARGET FRAMEWORK} segnaposto è il framework di destinazione) nella /var/www/blazorapp directory (il percorso specificato in DocumentRoot nel file di configurazione).

3. Riavviare il servizio Apache.

Per altre informazioni, vedere mod_mime e mod_deflate.

GitHub Pages

L'azione GitHub predefinita, che distribuisce le pagine, ignora la distribuzione delle cartelle a partire dal carattere di sottolineatura, ad esempio la _framework cartella. Per distribuire le cartelle a partire dal carattere di sottolineatura, aggiungere un file vuoto .nojekyll al ramo Git.

Git tratta i file JavaScript (JS), ad esempio blazor.webassembly.js, come testo e converte le terminazioni di riga da CRLF (ritorno a capo del feed di riga) a LF (avanzamento riga) nella pipeline di distribuzione. Queste modifiche ai JS file producono hash di file diversi rispetto agli hash inviati Blazor al client nel blazor.boot.json file. Le mancate corrispondenze generano errori di controllo dell'integrità nel client. Un approccio alla risoluzione di questo problema consiste nell'aggiungere un file con .gitattributes una *.js binary riga prima di aggiungere gli asset dell'app al ramo Git. La *.js binary riga configura Git per trattare JS i file come file binari, evitando così di elaborare i file nella pipeline di distribuzione. Gli hash dei file non elaborati corrispondono alle voci nel blazor.boot.json file e vengono superati i controlli di integrità lato client. Per altre informazioni, vedere ASP.NET Runtime .NET Core Blazor WebAssembly e memorizzazione nella cache del bundle dell'app.

Per gestire le riscritture url, aggiungere un wwwroot/404.html file con uno script che gestisce il reindirizzamento della richiesta alla index.html pagina. Per un esempio, vedere il SteveSandersonMS/BlazorOnGitHubPages repository GitHub:

• wwwroot/404.html
• Sito live

Quando si usa un sito di progetto anziché un sito dell'organizzazione, aggiornare il <base> tag in wwwroot/index.html. Impostare il valore dell'attributo href sul nome del repository GitHub con una barra finale , ad esempio /my-repository/. SteveSandersonMS/BlazorOnGitHubPages Nel repository GitHub la base href viene aggiornata in fase di pubblicazione dal .github/workflows/main.yml file di configurazione.

Autonomo con Docker

Un'app autonoma Blazor WebAssembly viene pubblicata come set di file statici per l'hosting da parte di un file server statico.

Per ospitare l'app in Docker:

• Scegliere un contenitore Docker con supporto del server Web, ad esempio Ngnix o Apache.
• Copiare gli asset di publish cartella in una cartella di percorso definita nel server Web per la gestione di file statici.
• Applicare una configurazione aggiuntiva in base alle esigenze per gestire l'app Blazor WebAssembly .

Per indicazioni sulla configurazione, vedere le risorse seguenti:

• Sezione Nginx o sezione Apache di questo articolo
• Documentazione di Docker

Valori di configurazione dell'host

Blazor WebAssembly Le app possono accettare i valori di configurazione host seguenti come argomenti della riga di comando in fase di esecuzione nell'ambiente di sviluppo.

Radice del contenuto

L'argomento --contentroot imposta il percorso assoluto della directory che contiene i file di contenuto dell'app (radice del contenuto). Negli esempi seguenti /content-root-path è il percorso radice del contenuto dell'app.

• Passare l'argomento quando si esegue localmente l'app a un prompt dei comandi. Dalla directory dell'app, eseguire:

  dotnet watch --contentroot=/content-root-path
  

• Aggiungere una voce al file dell'app launchSettings.json nel profilo IIS Express . Questa impostazione viene usata quando l'app viene eseguita con il debugger di Visual Studio e da un prompt dei comandi con dotnet watch (o dotnet run).

  "commandLineArgs": "--contentroot=/content-root-path"
  

• In Visual Studio specificare l'argomento in Proprietà>Debug>Argomenti applicazione. L'impostazione dell'argomento nella pagina delle proprietà di Visual Studio aggiunge l'argomento al launchSettings.json file.

  --contentroot=/content-root-path
  

Base del percorso

L'argomento --pathbase imposta il percorso di base dell'app per un'app eseguita localmente con un percorso URL relativo non radice (il <base> tag href è impostato su un percorso diverso da / quello di staging e produzione). Negli esempi seguenti /relative-URL-path è la base del percorso dell'app. Per altre informazioni, vedere Percorso di base dell'app.

• Passare l'argomento quando si esegue localmente l'app a un prompt dei comandi. Dalla directory dell'app, eseguire:

  dotnet watch --pathbase=/relative-URL-path
  

• Aggiungere una voce al file dell'app launchSettings.json nel profilo IIS Express . Questa impostazione viene usata quando si esegue l'app con il debugger di Visual Studio e da un prompt dei comandi con dotnet watch (o dotnet run).

  "commandLineArgs": "--pathbase=/relative-URL-path"
  

• In Visual Studio specificare l'argomento in Proprietà>Debug>Argomenti applicazione. L'impostazione dell'argomento nella pagina delle proprietà di Visual Studio aggiunge l'argomento al launchSettings.json file.

  --pathbase=/relative-URL-path
  

URL

L'argomento --urls imposta gli indirizzi IP o gli indirizzi host con le porte e i protocolli su cui eseguire l'ascolto per le richieste.

• Passare l'argomento quando si esegue localmente l'app a un prompt dei comandi. Dalla directory dell'app, eseguire:

  dotnet watch --urls=http://127.0.0.1:0
  

• Aggiungere una voce al file dell'app launchSettings.json nel profilo IIS Express . Questa impostazione viene usata quando si esegue l'app con il debugger di Visual Studio e da un prompt dei comandi con dotnet watch (o dotnet run).

  "commandLineArgs": "--urls=http://127.0.0.1:0"
  

• In Visual Studio specificare l'argomento in Proprietà>Debug>Argomenti applicazione. L'impostazione dell'argomento nella pagina delle proprietà di Visual Studio aggiunge l'argomento al launchSettings.json file.

  --urls=http://127.0.0.1:0
  

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

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

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

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

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

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

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

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

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

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

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

Danneggiamento della distribuzione precedente

In genere nella distribuzione:

• Vengono sostituiti solo i file modificati, che in genere comportano una distribuzione più rapida.
• I file esistenti che non fanno parte della nuova distribuzione vengono lasciati sul posto per l'uso da parte della nuova distribuzione.

In rari casi, i file persistenti di una distribuzione precedente possono danneggiare una nuova distribuzione. L'eliminazione completa della distribuzione esistente (o dell'app pubblicata in locale prima della distribuzione) può risolvere il problema con una distribuzione danneggiata. Spesso, l'eliminazione della distribuzione esistente una volta è sufficiente per risolvere il problema, tra cui per una compilazione DevOps e distribuire la pipeline.

Se si determina che la cancellazione di una distribuzione precedente è sempre necessaria quando è in uso una compilazione DevOps e si distribuisce la pipeline, è possibile aggiungere temporaneamente un passaggio alla pipeline di compilazione per eliminare la distribuzione precedente per ogni nuova distribuzione fino a risolvere la causa esatta del danneggiamento.

Risolvere gli errori di controllo dell'integrità

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, che non vengono memorizzati nella cache nei client. 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.

Per Blazor WebAssemblyl'origine di riferimento all'avvio, vedere il Boot.WebAssembly.ts file nel dotnet/aspnetcore repository GitHub.

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 (CDN) tentano di minificare automaticamente 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 la configurazione del server Web o della rete CDN nel caso in cui siano configurate 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.

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

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

Disabilitare il controllo dell'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.

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 il controllo dell'integrità per 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.