Héberger et déployer ASP.NET Core Blazor WebAssembly

Cet article explique comment héberger et déployer des applications Blazor WebAssembly.

Avec le modèle d’hébergement Blazor WebAssembly :

• L’application Blazor, ses dépendances et le runtime .NET sont téléchargés sur le navigateur en parallèle.
• L’application est exécutée directement sur le thread d’interface utilisateur du navigateur.

Cet article s’applique au scénario de déploiement dans lequel l’application Blazor est placée sur un service ou serveur web d’hébergement statique et .NET n’est pas utilisé pour servir l’application Blazor. Cette stratégie est abordée dans la section déploiement autonome et d’autres articles de ce nœud pour IIS, les services Azure, Apache, Nginx et GitHub Pages.

Sous-domaine et hébergement de sous-application IIS

L’hébergement de sous-domaine ne nécessite pas de configuration spéciale de l’application. Vous n’avez pas besoin de configurer le chemin d’accès de base de l’application (balise <base> dans wwwroot/index.html) pour héberger l’application sur un sous-domaine.

L’hébergement de sous-application IIS nécessite que vous définissiez le chemin d’accès de base de l’application. Pour plus d’informations et pour obtenir des liens croisés vers des instructions supplémentaires sur l’hébergement de sous-applications IIS, consultez Héberger et dépliyer ASP.NET Core Blazor.

Réduire la taille maximale de mémoire pour certains navigateurs d’appareils mobiles

Lors de la création d’une application Blazor qui s’exécute sur le client (projet .Client d’une application Blazor Web App ou d’une application Blazor WebAssembly autonome) et cible les navigateurs d’appareils mobiles, en particulier Safari sur iOS, la diminution de la mémoire maximale de l’application avec la propriété MSBuild EmccMaximumHeapSize peut être nécessaire. La valeur par défaut est de 2 147 483 648 octets, ce qui peut être trop volumineux et entraîner un blocage de l’application si l’application tente d’allouer plus de mémoire avec le navigateur qui ne l’a pas accordé. L’exemple suivant définit la valeur sur 268 435 456 bytes dans le fichier Program :

<EmccMaximumHeapSize>268435456</EmccMaximumHeapSize>

Pour plus d’informations sur les propriétés et les cibles Mono/WebAssembly MSBuild, consultez WasmApp.Common.targets (dotnet/runtime dépôt GitHub).

Format d'emballage Webcil pour les assemblies .NET

Webcil est un format d’empaquetage convivial pour les assemblys .NET conçu pour permettre l’utilisation de Blazor WebAssembly dans des environnements réseau restrictifs. Les fichiers Webcil utilisent un wrapper WebAssembly standard, où les assemblys sont déployés en tant que fichiers WebAssembly qui utilisent l’extension de fichier .wasm standard.

Webcil est le format d’empaquetage par défaut lorsque vous publiez une application Blazor WebAssembly. Pour désactiver l’utilisation de Webcil, définissez la propriété MSBuild suivante dans le fichier projet de l’application :

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

Personnaliser le mode de chargement des ressources de démarrage

Personnalisez la façon dont les ressources de démarrage sont chargées à l’aide de l’API loadBootResource. Pour plus d’informations, consultez Démarrage ASP.NET Core Blazor.

Compression

Quand une application Blazor WebAssembly est publiée, la sortie est compressée statiquement pendant la publication pour réduire la taille de l’application et ôter la surcharge liée à la compression du runtime. Les algorithmes de compression suivants sont utilisés :

• Brotli (niveau le plus élevé)
• Gzip

Blazor s’appuie sur l’hôte pour traiter les fichiers compressés appropriés. Lors de l’hébergement d’une application autonome Blazor WebAssembly, des tâches supplémentaires peuvent être nécessaires pour s’assurer que les fichiers compressés statiquement sont traités :

• Pour la configuration de la compression IIS web.config, consultez la section IIS : compression Brotli et Gzip.
• Lors de l'hébergement sur des solutions d'hébergement statiques qui ne prennent pas en charge la négociation de contenu de fichier compressé statiquement, envisagez de configurer l'application pour récupérer et décoder les fichiers compressés Brotli :

Obtenez le décodeur Brotli JavaScript à partir du dépôt GitHub google/brotli. Le fichier de décodeur minifié est nommé decode.min.js et se trouve dans le dossier js du dépôt.

Remarque

Si la version minifiée du script decode.js (decode.min.js) échoue, essayez d’utiliser la version non minifiée (decode.js) à la place.

Mettez à jour l’application pour utiliser le décodeur.

Dans le fichier wwwroot/index.html, définissez autostart à false dans la balise Blazor de <script>.

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

Après la balise Blazor de <script> et avant la balise fermante </body>, ajoutez le bloc <script> de code JavaScript suivant. La fonction suivante appelle fetch avec cache: 'no-cache' pour maintenir le cache du navigateur mis à jour.

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>

Blazor WebAssembly autonome :

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

Pour plus d’informations sur le chargement des ressources de démarrage, consultez Démarrage ASP.NET Core Blazor.

Pour désactiver la compression, ajoutez la propriété MSBuild CompressionEnabled au fichier projet de l’application et définissez la valeur sur false :

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

La propriété CompressionEnabled peut être passée à la commande dotnet publish avec la syntaxe suivante dans un interpréteur de commandes :

dotnet publish -p:CompressionEnabled=false

Réécriture d’URL pour un routage correct

Le routage des requêtes de composants de page dans une application Blazor WebAssembly n'est pas aussi simple que le routage de requêtes dans une application Blazor Server. Considérez une application Blazor WebAssembly avec deux composants :

• Main.razor : Se charge à la racine de l’application et contient un lien vers le composant About (href="About").
• About.razor : composant About.

Quand le document par défaut de l’application est demandé à l’aide de la barre d’adresses du navigateur (par exemple, https://www.contoso.com/) :

1. Le navigateur effectue une requête.
2. La page par défaut est retournée, généralement index.html.
3. index.html amorce l’application.
4. Le composant Router se charge et le composant RazorMain est rendu.

Dans la page principale, la sélection du composant About fonctionne sur le client, car le routeur Blazor empêche le navigateur d’effectuer une requête sur Internet à www.contoso.com pour About et fournit lui-même le composant About rendu. Toutes les requêtes de point de terminaison interne au sein de l’application Blazor WebAssembly fonctionnent de la même façon : les requêtes ne déclenchent pas de requêtes basées sur un navigateur pour les ressources hébergées sur le serveur sur Internet. Le routeur gère les requêtes en interne.

Si une requête pour www.contoso.com/About est effectuée à l’aide de la barre d’adresses du navigateur, elle échoue. Comme cette ressource n’existe pas sur l’hôte Internet de l’application, une réponse 404 – Non trouvé est retournée.

Étant donné que les navigateurs envoient des requêtes aux hôtes basés sur Internet pour des pages côté client, les serveurs web et les services d’hébergement doivent réécrire toutes les requêtes pour les ressources qui ne se trouvent pas physiquement sur le serveur afin qu’elles pointent vers la page index.html. Quand index.html est retournée, le routeur Blazor de l’application prend le relais et répond avec la ressource appropriée.

Lors du déploiement sur un serveur IIS, vous pouvez utiliser le module réécriture d’URL avec le fichier web.config publié de l’application. Pour plus d’informations, consultez Host and deploy ASP.NET Core Blazor WebAssembly avec IIS.

Déploiement autonome

Un déploiement autonome fournit l’application Blazor WebAssembly sous la forme d’un ensemble de fichiers statiques qui sont demandés directement par les clients. N’importe quel serveur de fichiers statiques est capable de servir l’application Blazor.

Les ressources de déploiement autonomes sont publiées dans le dossier /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot ou bin/Release/{TARGET FRAMEWORK}/browser-wasm/publish, où l'espace réservé {TARGET FRAMEWORK} correspond à l'infrastructure cible.

Azure App Service

Blazor WebAssembly les applications peuvent être déployées sur Azure App Services sur Windows, qui héberge l’application sur IIS.

Le déploiement d’une application Blazor WebAssembly autonome sur Azure App Service pour Linux n’est actuellement pas pris en charge. Nous vous recommandons d’héberger une application Blazor WebAssembly autonome à l’aide d’Azure Static Web Apps, qui prend en charge ce scénario.

Autonome avec Docker

Une application autonome Blazor WebAssembly est publiée sous la forme d’un ensemble de fichiers statiques à héberger par un serveur de fichiers statique.

Pour héberger l’application dans Docker :

• Choisissez un conteneur Docker avec prise en charge du serveur web, tel que Nginx ou Apache.
• Copiez les ressources du dossier publish dans un dossier d’emplacement défini dans le serveur web pour servir des fichiers statiques.
• Appliquez une configuration supplémentaire en fonction des besoins pour servir l’application Blazor WebAssembly.

Pour des instructions de configuration, consultez les ressources suivantes :

• Les articles Nginx ou Apache
• Documentation Docker

Valeurs de configuration de l’hôte

Les applications Blazor WebAssembly peuvent accepter les valeurs de configuration d’hôte suivantes en tant qu’arguments de ligne de commande au moment de l’exécution dans l’environnement de développement.

Racine de contenu

L’argument --contentroot définit le chemin absolu du répertoire qui contient les fichiers de contenu de l’application (racine du contenu). Dans les exemples suivants, /content-root-path est le chemin racine du contenu de l’application.

• Passez l’argument lors de l’exécution de l’application localement à une invite de commandes. À partir du répertoire de l’application, exécutez :

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

• Ajoutez une entrée au fichier launchSettings.json de l’application dans le profil IIS Express. Ce paramètre est utilisé en cas d’exécution de l’application avec le débogueur Visual Studio et dans une invite de commandes avec dotnet watch (ou dotnet run).

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

• Dans Visual Studio, spécifiez l’argument dans Propriétés>Déboguer>Arguments d’application. Le fait de définir l’argument dans la page de propriétés Visual Studio l’ajoute au fichier launchSettings.json.

  --contentroot=/content-root-path
  

Base du chemin

L’argument --pathbase définit le chemin de base de l’application pour une application s’exécutant localement avec un chemin d’URL relative non racine (le <base> de la balise href a comme valeur un chemin autre que / pour la préproduction et la production). Dans les exemples suivants, /relative-URL-path est la base du chemin de l’application. Pour plus d’informations, consultez chemin de base de l’application ASP.NET CoreBlazor.

Important

Contrairement au chemin fourni au href de la balise <base>, n’incluez pas de barre oblique (/) quand vous passez la valeur d’argument --pathbase. Si vous spécifiez <base> (inclut une barre oblique) comme chemin de base de l’application dans la balise <base href="/CoolApp/">, passez --pathbase=/CoolApp (aucune barre oblique de fin) comme valeur d’argument de ligne de commande.

• Passez l’argument lors de l’exécution de l’application localement à une invite de commandes. À partir du répertoire de l’application, exécutez :

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

• Ajoutez une entrée au fichier launchSettings.json de l’application dans le profil IIS Express. Ce paramètre est utilisé en cas d’exécution de l’application avec le débogueur Visual Studio et dans une invite de commandes avec dotnet watch (ou dotnet run).

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

• Dans Visual Studio, spécifiez l’argument dans Propriétés>Déboguer>Arguments d’application. Le fait de définir l’argument dans la page de propriétés Visual Studio l’ajoute au fichier launchSettings.json.

  --pathbase=/relative-URL-path
  

Pour plus d’informations, consultez chemin de base de l’application ASP.NET CoreBlazor.

URL

L’argument --urls définit les adresses IP ou les adresses d’hôtes avec les ports et protocoles sur lesquels il faut écouter les demandes.

• Passez l’argument lors de l’exécution de l’application localement à une invite de commandes. À partir du répertoire de l’application, exécutez :

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

• Ajoutez une entrée au fichier launchSettings.json de l’application dans le profil IIS Express. Ce paramètre est utilisé en cas d’exécution de l’application avec le débogueur Visual Studio et dans une invite de commandes avec dotnet watch (ou dotnet run).

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

• Dans Visual Studio, spécifiez l’argument dans Propriétés>Déboguer>Arguments d’application. Le fait de définir l’argument dans la page de propriétés Visual Studio l’ajoute au fichier launchSettings.json.

  --urls=http://127.0.0.1:0
  

Configurer l’outil de découpage

Blazor effectue la suppression du langage intermédiaire (IL) lors de chaque génération de version afin de supprimer tout langage intermédiaire inutile des assemblys de sortie. Pour plus d’informations, consultez Configurer l’outil de suppression pour Blazor ASP.NET Core.

Corruption avant le déploiement

Généralement lors du déploiement :

• Seuls les fichiers modifiés sont remplacés, ce qui entraîne généralement un déploiement plus rapide.
• Les fichiers existants qui ne font pas partie du nouveau déploiement sont laissés en place pour être utilisés par le nouveau déploiement.

Dans de rares cas, des fichiers persistants d’un déploiement précédent peuvent endommager un nouveau déploiement. La suppression complète du déploiement existant (ou de l’application publiée localement avant le déploiement) peut résoudre le problème lié à un déploiement endommagé. Souvent, la suppression du déploiement existant une fois suffit à résoudre le problème, y compris pour une génération et un pipeline de déploiement DevOps.

Si vous déterminez que l’effacement d’un déploiement antérieur est toujours nécessaire lorsqu’un pipeline de build et de déploiement DevOps est en cours d’utilisation, vous pouvez ajouter temporairement une étape au pipeline de build pour supprimer le déploiement précédent pour chaque nouveau déploiement jusqu’à ce que vous déterminiez la cause exacte de l’endommagement.