Hosting di ASP.NET Core e distribuzione Blazor WebAssembly

Questo articolo illustra come ospitare e distribuire le app Blazor WebAssembly.

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.

Questo articolo si riferisce allo scenario di distribuzione in cui l'app Blazor viene inserita in un server o un servizio Web di hosting statico, .NET non viene usato per gestire l'app Blazor . Questa strategia è illustrata nella sezione Distribuzione autonoma e in altri articoli di questo nodo per IIS, servizi di Azure, Apache, Nginx e GitHub Pages.

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

Quando si sviluppa un'app Blazor che viene eseguita sul client (progetto .Client di un'app Blazor Web App o app autonoma Blazor WebAssembly) e destinata ai browser dei dispositivi mobili, in particolare Safari su iOS, potrebbe essere necessario ridurre la memoria massima per l'app utilizzando la proprietà EmccMaximumHeapSize di MSBuild. Il valore predefinito è 2.147.483.648 byte, che potrebbe essere troppo grande e causare un arresto anomalo dell'app se l'app tenta di allocare più memoria con il browser che non riesce a concederlo. Nell'esempio seguente il valore viene impostato su 268.435.456 byte nel Program file:

<EmccMaximumHeapSize>268435456</EmccMaximumHeapSize>

Per ulteriori informazioni sulle proprietà e destinazioni di MSBuild Mono/WebAssembly, vedere

Formato di creazione di pacchetti Webcil per assembly .NET

Webcil è un formato di creazione di pacchetti web per gli assembly .NET progettati per consentire l'uso Blazor WebAssembly in ambienti di rete restrittivi. I file Webcil usano un wrapper WebAssembly standard, in cui gli assembly vengono distribuiti come file WebAssembly che usano l'estensione di file standard .wasm .

Webcil è il formato di creazione di pacchetti predefinito quando si pubblica un'app Blazor WebAssembly . Per disabilitare l'uso di Webcil, impostare la proprietà MSBuild seguente nel file di progetto dell'app:

<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 ulteriori informazioni, vedere ASP.NET Core Blazor startup.

Compression

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

Blazor si basa sull'host per gestire i file compressi appropriati. Quando si ospita un'app Blazor WebAssembly autonoma, potrebbe essere necessario un lavoro aggiuntivo per garantire che i file compressi in modo statico vengano gestiti:

• 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 JavaScript Brotli dal google/brotli repository GitHub. Il file minimizzato del decodificatore è denominato e si trova nella cartella del repository.

Note

Se la versione minimizzata dello decode.js script (decode.min.js) ha esito negativo, provare a usare invece la versione non modificata (decode.js).

Aggiornare l'app per usare il decodificatore.

Nel file wwwroot/index.html, settare autostart su false nel tag di Blazor<script>:

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

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

Blazor Web App:

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

Un Blazor WebAssembly autonomo:

<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 ulteriori informazioni sul caricamento delle risorse di avvio, vedere ASP.NET Core Blazor startup.

Per disabilitare la compressione, aggiungere la CompressionEnabled proprietà MSBuild al file di progetto dell'app e impostare il valore su false:

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

La CompressionEnabled proprietà può essere passata al dotnet publish comando con la sintassi seguente in una shell dei comandi:

dotnet publish -p:CompressionEnabled=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: si carica alla radice dell'applicazione e contiene un collegamento al componente About (href="About").
• About.razor: componente About.

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 il componente viene caricato e viene eseguito il rendering del componente RazorMain.

Nella pagina principale, la selezione del collegamento al componente About funziona sul client perché il router Blazor impedisce al browser di effettuare una richiesta su Internet per www.contoso.comAbout e gestisce direttamente il componente About renderizzato. 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 prende in carico 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 Ospitare e distribuire ASP.NET Core Blazor WebAssembly con IIS.

Distribuzione autonoma

Una distribuzione autonoma serve l'app come un set di file statici richiesti direttamente dai clienti. Qualsiasi file server statico è in grado di gestire l'app Blazor .

Gli asset di distribuzione autonomi vengono pubblicati nella cartella /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot o bin/Release/{TARGET FRAMEWORK}/browser-wasm/publish, dove il segnaposto {TARGET FRAMEWORK} è il framework di destinazione.

Servizio app di Azure

Blazor WebAssembly Le app possono essere distribuite in Servizi app di 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.

Indipendente 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 Nginx o Apache.
• Copiare gli asset della cartella publish in una cartella posizionata nel server Web per servire file statici.
• Applicare una configurazione aggiuntiva in base alle esigenze per gestire l'app Blazor WebAssembly .

Per indicazioni sulla configurazione, vedere le risorse seguenti:

• Articoli di Nginx o Apache
• 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.

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

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

• Aggiungere un'entrata al file dell'app launchSettings.json nel profilo di 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, specifica l'argomento in Proprietà>Debug>Argomenti dell'applicazione. L'impostazione dell'argomento nella pagina delle proprietà di Visual Studio aggiunge l'argomento al file launchSettings.json.

  --contentroot=/content-root-path
  

Percorso base

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 ulteriori informazioni, vedere il percorso di base dell'app ASP.NET Core.

Important

A differenza del percorso specificato per href del tag <base>, non includere una barra finale (/) quando si passa il valore dell'argomento --pathbase. Se il percorso di base dell'app viene specificato nel tag <base> come <base href="/CoolApp/"> (inclusa una barra finale), passare il valore dell'argomento della riga di comando come --pathbase=/CoolApp (senza barra finale).

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

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

• Aggiungere un'entrata al file dell'app launchSettings.json nel profilo di 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, specifica l'argomento in Proprietà>Debug>Argomenti dell'applicazione. L'impostazione dell'argomento nella pagina delle proprietà di Visual Studio aggiunge l'argomento al file launchSettings.json.

  --pathbase=/relative-URL-path
  

Per ulteriori informazioni, vedere il percorso di base dell'app ASP.NET Core.

URLs

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

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

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

• Aggiungere un'entrata al file dell'app launchSettings.json nel profilo di 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, specifica l'argomento in Proprietà>Debug>Argomenti dell'applicazione. L'impostazione dell'argomento nella pagina delle proprietà di Visual Studio aggiunge l'argomento al file launchSettings.json.

  --urls=http://127.0.0.1:0
  

Configurare il trimmer

Blazor esegue il taglio del linguaggio intermedio (IL) in ogni build di rilascio per rimuovere il codice IL non necessario dagli assembly di output. Per altre informazioni, vedere Configurare Trimmer per ASP.NET Core Blazor.

Danneggiamento dell'implementazione precedente

In genere durante l'implementazione:

• 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, anche per una pipeline di compilazione e distribuzione DevOps.

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.