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

Cet article explique comment héberger et déployer Blazor WebAssembly avec ASP.NET Core, des réseaux de distribution de contenu (CDN), des serveurs de fichiers et GitHub Pages.

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.

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 du tas pour certains navigateurs d’appareils mobiles

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

<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

• 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 auprès 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.

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

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

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

Après la balise <script> de Blazor et avant la balise fermante </body>, ajoutez le bloc <script> de code JavaScript suivant.

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

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

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

dotnet publish -p:CompressionEnabled=false

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

dotnet publish -p:BlazorEnableCompression=false

Réécriture d’URL pour un routage correct

Le routage des requêtes de composants de page dans une application Blazor WebAssembly ne se résume pas simplement au 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 la section IIS.

<SelfContained>false</SelfContained>

<RuntimeIdentifier>{RID}</RuntimeIdentifier>

<SelfContained>false</SelfContained>

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\ (selon la version du Kit de développement logiciel (SDK) .NET utilisée), où l’espace réservé {TARGET FRAMEWORK} est l’infrastructure cible.

Azure App Service

Les applications Blazor WebAssembly 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.

Azure Static Web Apps

Utilisez l’une des approches suivantes pour déployer une application Blazor WebAssembly vers Azure Static Web Apps :

• Déployer à partir de Visual Studio
• Déployer à partir de Visual Studio Code
• Déployer à partir de GitHub

Déployer à partir de Visual Studio

Pour déployer à partir de Visual Studio, créez un profil de publication pour Azure Static Web Apps :

1. Enregistrez tout travail non enregistré dans le projet, car un redémarrage de Visual Studio peut être nécessaire pendant le processus.

2. Dans l’interface utilisateur Publier de Visual Studio, sélectionnez Cible>Azure>Cible spécifique>Azure Static Web Apps pour créer un profil de publication.

3. Si le composant Azure WebJobs Tools pour Visual Studio n’est pas installé, une invite s’affiche pour installer le composant de développement web et ASP.NET. Suivez les invites pour installer les outils à l’aide de Visual Studio Installer. Visual Studio ferme et rouvre automatiquement lors de l’installation des outils. Une fois les outils installés, commencez la première étape pour créer le profil de publication.

4. Dans la configuration du profil de publication, fournissez le nom de l’abonnement. Sélectionnez une instance existante ou sélectionnez Créer une instance. Lors de la création d’une instance dans l’interface utilisateur Créer une application web statique du portail Azure, définissez les Détails du déploiement>Source sur Autre. Attendez que le déploiement se termine dans le portail Azure avant de continuer.

5. Dans la configuration du profil de publication, sélectionnez l’instance Azure Static Web Apps dans le groupe de ressources de l’instance. Sélectionnez Terminer pour créer le profil de publication. Si Visual Studio invite à installer l’interface CLI Static Web Apps (SWA), installez-la en suivant les invites. L’interface CLI SWA nécessite NPM/Node.js (documentation Visual Studio).

Une fois le profil de publication créé, déployez l’application sur l’instance Azure Static Web Apps à l’aide du profil de publication en sélectionnant le bouton Publier.

Déployer à partir de Visual Studio Code

Pour effectuer un déploiement à partir de Visual Studio Code, consultez Démarrage rapide : créer votre premier site statique avec Azure Static Web Apps.

Déployer à partir de GitHub

Pour déployer à partir d’un référentiel GitHub, consultez Didacticiel : Création d’une application web statique avec Blazor dans Azure Static Web Apps.

IIS

IIS est un serveur de fichiers statiques compatible avec les applications Blazor. Pour configurer IIS afin d’héberger Blazor, consultez Générer un site web statique sur IIS.

Les ressources publiées sont créées dans le dossier /bin/Release/{TARGET FRAMEWORK}/publish ou bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish, selon la version de SDK utilisée et où l’espace réservé {TARGET FRAMEWORK} est le framework cible. Hébergez le contenu du dossier publish sur le serveur web ou le service d’hébergement.

web.config

Quand un projet Blazor est publié, un fichier web.config est créé avec la configuration IIS suivante :

• types MIME
• La compression HTTP est activée pour les types MIME suivants :
  • application/octet-stream
  • application/wasm
• Des règles du module de réécriture d’URL sont établies :
  • Servir le sous-répertoire où résident les ressources statiques de l’application (wwwroot/{PATH REQUESTED}).
  • Créer un routage de secours SPA afin que les requêtes pour des ressources autres que des fichiers soient redirigées vers le document par défaut de l’application dans son dossier de ressources statiques (wwwroot/index.html).

Utiliser un web.config personnalisé

Pour utiliser un fichier web.config personnalisé :

Si la génération ou la transformation web.config du SDK pendant la publication ne déplace pas le fichier vers les ressources publiées dans le dossier publish ou modifie la configuration personnalisée dans votre fichier web.config personnalisé, utilisez l’une des approches suivantes si nécessaire pour prendre le contrôle total du processus :

• Si le SDK ne génère pas le fichier, par exemple, dans une application Blazor WebAssembly autonome sur /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot ou bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish, selon la version du SDK utilisée et où l’espace réservé {TARGET FRAMEWORK} est le framework cible, définissez la propriété <PublishIISAssets> sur true dans le fichier projet (.csproj). En règle générale, pour les applications WebAssembly autonomes, il s’agit du seul paramètre requis pour déplacer un fichier web.config personnalisé et empêcher la transformation du fichier par le SDK.

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

• Désactivez la transformation de web.config du SDK dans le fichier projet (.csproj) :

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

• Ajoutez une cible personnalisée au fichier projet (.csproj) pour déplacer un fichier web.config personnalisé. Dans l’exemple suivant, le fichier web.config personnalisé est placé par le développeur à la racine du projet. Si le fichier web.config réside ailleurs, spécifiez le chemin d’accès au fichier dans SourceFiles. L’exemple suivant spécifie le dossier publish avec $(PublishDir), mais fournit un chemin d’accès à DestinationFolder pour un emplacement de sortie personnalisé.

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

Installer le module de réécriture d’URL

Le module de réécriture d’URL est nécessaire pour réécrire les URL. Il n’est pas installé par défaut, et ne peut pas l’être en tant que fonctionnalité de service de rôle Serveur Web (IIS). Vous devez le télécharger à partir du site web IIS. Utilisez Web Platform Installer pour installer le module :

1. Localement, accédez à la page des téléchargements du Module de réécriture d’URL. Pour la version anglaise, sélectionnez WebPI pour télécharger le programme d’installation WebPI. Pour les autres langues, sélectionnez l’architecture appropriée pour le serveur (x86/x64) afin de télécharger le programme d’installation.
2. Copiez le programme d’installation sur le serveur. Exécutez le programme d’installation. Sélectionnez le bouton Installer et acceptez les termes du contrat de licence. Il n’est pas nécessaire de redémarrer le serveur après l’installation.

Configurer le site web

Affectez le dossier de l’application comme chemin physique du site web. Le dossier contient :

• Le fichier web.config utilisé par IIS pour configurer le site web, notamment les règles de redirection nécessaires et les types de contenu de fichiers
• Le dossier de ressources statiques de l’application

Hôte en tant que sous-application IIS

Si une application autonome est hébergée en tant que sous-application IIS, effectuez l’une des opérations suivantes :

• Désactivez le gestionnaire de module ASP.NET Core hérité.

  Supprimez le gestionnaire dans le fichier web.config publié de l’application Blazor en ajoutant une section <handlers> à la section <system.webServer> du fichier :

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

• Désactivez l’héritage de la section <system.webServer> de l’application racine (parente) en affectant la valeur false à l’attribut inheritInChildApplications d’un élément <location> :

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

  Remarque

  La désactivation de l’héritage de la section <system.webServer> de l’application racine (parent) est la configuration par défaut pour les applications publiées à l’aide du SDK .NET.

La suppression du gestionnaire ou la désactivation de l’héritage est effectuée en plus de la configuration du chemin de base de l’application. Dans le fichier index.html de l’application, définissez le chemin de base de l’application sur l’alias IIS utilisé lors de la configuration de la sous-application dans IIS.

Configurez le chemin de base de l’application en suivant les instructions de l’article Héberger et déployer ASP.NET CoreBlazor.

Compression Brotli et Gzip

IIS peut être configuré via web.config pour servir des ressources compressées Blazor Brotli ou Gzip pour les applications autonomes Blazor WebAssembly. Pour obtenir un exemple de fichier de configuration, consultez web.config.

Une configuration supplémentaire de l’exemple de fichier web.config peut être nécessaire dans les scénarios suivants :

• La spécification de l’application appelle l’un des éléments suivants :
  • Remise des fichiers compressés qui ne sont pas configurés par l’exemple de fichier web.config.
  • Remise des fichiers compressés configurés par l’exemple de fichier web.config dans un format non compressé.
• La configuration IIS du serveur (par exemple, applicationHost.config) fournit des valeurs IIS par défaut au niveau du serveur. Selon la configuration au niveau du serveur, l’application peut nécessiter une configuration IIS différente de celle que contient l’exemple de fichier web.config.

Pour plus d’informations sur les fichiers personnalisés web.config, consultez la section Utiliser un web.config personnalisé.

Résolution des problèmes

Si vous recevez un message 500 – Erreur interne du serveur et que le Gestionnaire IIS lève des erreurs quand vous tentez d’accéder à la configuration du site web, vérifiez que le module de réécriture d’URL est installé. Quand le module n’est pas installé, le fichier web.config ne peut pas être analysé par IIS. Cela empêche le Gestionnaire IIS de charger la configuration du site web et empêche le site web de fournir les fichiers statiques Blazor.

Pour plus d’informations sur la résolution des problèmes des déploiements sur IIS, consultez Résolution des problèmes ASP.NET Core sur Azure App Service et IIS.

Azure Storage

L’hébergement d’un fichier statique de stockage Azure permet l’hébergement d’applications serverless Blazor. Les noms de domaine personnalisé, le réseau de distribution de contenu Azure (CDN) et HTTPS sont pris en charge.

Lorsque le service blob est activé pour l’hébergement de site Web statique sur un compte de stockage :

• Définissez le nom du document d’index sur index.html.
• Définissez le chemin d’accès au document d’erreur sur index.html. Les composants de Razor et autres points de terminaison non-fichier ne se trouvent sur les chemins d’accès physiques dans le contenu statique stocké par le service blob. Lors de la réception d’une requête pour l’une de ces ressources que le routeur Blazor doit gérer, l’erreur 404 - introuvable générée par le service blob achemine la requête vers le chemin d’accès au document d’erreur. Le blob index.html est retourné et le routeur Blazor charge et traite le chemin d’accès.

Si les fichiers ne sont pas chargés au moment de l’exécution en raison de types MIME inappropriés dans les en-têtes Content-Type des fichiers, effectuez l’une des actions suivantes :

• Configurez vos outils pour définir les types MIME appropriés (en-têtes Content-Type) lors du déploiement des fichiers.

• Modifiez les types MIME (en-têtes Content-Type) des fichiers après le déploiement de l’application.

  Dans l’Explorateur Stockage (Portail Azure) pour chaque fichier :

  1. Cliquez avec le bouton de droite sur le fichier et sélectionnez Propriétés.
  2. Définissez ContentType et sélectionnez le bouton Enregistrer.

Pour plus d’informations, consultez Hébergement de site Web statique dans le stockage Azure.

Nginx

Le fichier nginx.conf suivant est simplifié afin de montrer comment configurer Nginx pour envoyer le fichier index.html chaque fois qu’il ne trouve aucun fichier correspondant sur le disque.

events { }
http {
    server {
        listen 80;

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

Lors de la définition de la limite de débit de rafale NGINX avec limit_req, les applications Blazor WebAssembly peuvent nécessiter une valeur de paramètre burst conséquente pour prendre en charge le nombre relativement élevé de requêtes effectuées par une application. Initialement, définissez la valeur sur au moins 60 :

http {
    server {
        ...

        location / {
            ...

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

Augmentez la valeur si les outils de développement de navigateur ou un outil de trafic réseau indiquent que les requêtes reçoivent un code État 503 - Service indisponible.

Pour plus d’informations sur la configuration du serveur web Nginx de production, consultez Creating NGINX Plus and NGINX Configuration Files (Création de fichiers de configuration NGINX et NGINX Plus).

Apache

Pour déployer une application Blazor WebAssembly vers Apache :

1. Placez le fichier config Apache dans le répertoire /etc/httpd/conf.d/.

2. Placez les ressources publiées de l’application (/bin/Release/{TARGET FRAMEWORK}/publish/wwwroot, où l’espace réservé {TARGET FRAMEWORK} est l’infrastructure cible) dans le répertoire /var/www/blazorapp (l’emplacement spécifié à DocumentRoot dans le fichier config).

3. Redémarrez le service Apache.

Pour plus d’informations, consultez mod_mime et mod_deflate.

GitHub Pages

L’action GitHub par défaut, qui déploie des pages, ignore le déploiement de dossiers commençant par un trait de soulignement, par exemple, le dossier _framework. Pour déployer des dossiers commençant par un trait de soulignement, ajoutez un fichier .nojekyll vide à la branche Git.

Git traite les fichiers JavaScript (JS), comme blazor.webassembly.js, en tant que texte et convertit les terminaisons de ligne CRLF (retour chariot) en LF (saut de ligne) dans le pipeline de déploiement. Ces modifications apportées aux fichiers JS produisent des hachages de fichiers différents de ceux que Blazor envoie au client dans le fichier blazor.boot.json. Ces disparités entraînent des échecs de vérification de l’intégrité sur le client. Une approche pour résoudre ce problème consiste à ajouter un fichier .gitattributes avec la ligne *.js binary avant d’ajouter les ressources de l’application à la branche Git. La ligne *.js binary configure Git pour traiter les fichiers JS en tant que fichiers binaires, ce qui évite de traiter les fichiers dans le pipeline de déploiement. Les hachages des fichiers non traités correspondent aux entrées du fichier blazor.boot.json, et les vérifications d’intégrité côté client réussissent. Pour plus d’informations, consultez runtime ASP.NET Core Blazor WebAssembly .NET et la mise en cache du bundle d’applications.

Pour gérer les réécritures d’URL, ajoutez un fichier wwwroot/404.html avec un script qui gère la redirection de la requête vers la page index.html. Pour obtenir un exemple, consultez le dépôt GitHub SteveSandersonMS/BlazorOnGitHubPages :

• wwwroot/404.html
• Site en ligne

Quand vous utilisez un site de projet plutôt qu’un site d’entreprise, mettez à jour la balise <base> dans wwwroot/index.html. Définissez la valeur d’attribut href sur le nom du dépôt GitHub avec une barre oblique (par exemple, /my-repository/). Dans le dépôt GitHub SteveSandersonMS/BlazorOnGitHubPages, le href de base est mis à jour au moment de la publication par le fichier de configuration .github/workflows/main.yml.

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, par exemple Ngnix 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 :

• Section Nginx ou Apache de cet article
• 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 href de la balise <base> 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.

• 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
  

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
  

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

Endommagement par un déploiement antérieur

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.

Résoudre les échecs de vérification de l’intégrité

Lorsque Blazor WebAssembly télécharge les fichiers de démarrage d’une application, il indique au navigateur d’effectuer des vérifications d’intégrité sur les réponses. Blazor envoie les valeurs de hachage SHA-256 pour la DLL (.dll), WebAssembly (.wasm) et d’autres fichiers dans le fichier blazor.boot.json, qui n’est pas mis en cache sur les clients. Les hachages de fichiers mis en cache sont comparés aux hachages du fichier blazor.boot.json. Pour les fichiers mis en cache avec un hachage correspondant, Blazor utilise les fichiers mis en cache. Sinon, les fichiers sont demandés auprès du serveur. Une fois qu’un fichier est téléchargé, son hachage est à nouveau vérifié pour la validation de l’intégrité. Une erreur est générée par le navigateur si la vérification de l’intégrité du fichier téléchargé échoue.

L’algorithme Blazor pour la gestion de l’intégrité des fichiers :

• Garantit que l’application ne risque pas de charger un ensemble incohérent de fichiers, par exemple si un nouveau déploiement est appliqué à votre serveur web pendant que l’utilisateur est en train de télécharger les fichiers de l’application. Les fichiers incohérents peuvent entraîner un dysfonctionnement de l’application.
• Garantit que le navigateur de l’utilisateur ne met jamais en cache les réponses incohérentes ou non valides, ce qui peut empêcher l’application de démarrer même si l’utilisateur actualise manuellement la page.
• Permet de mettre en cache les réponses et de ne pas vérifier les modifications côté serveur tant que les hachages SHA-256 attendus changent, de sorte que les chargements de pages suivants impliquent moins de requêtes et se terminent plus rapidement.

Si le serveur web retourne des réponses qui ne correspondent pas aux hachages SHA-256 attendus, une erreur similaire à l’exemple suivant s’affiche dans la console du développeur du navigateur :

Impossible de trouver une synthèse valide dans l’attribut « integrity » pour la ressource « https://myapp.example.com/_framework/MyBlazorApp.dll » avec l’intégrité SHA-256 calculée « IIa70iwvmEg5WiDV17OpQ5eCztNYqL186J56852RpJY= ». La ressource a été bloquée.

Dans la plupart des cas, l’avertissement n’indique pas un problème de vérification d’intégrité. Au lieu de cela, l’avertissement signifie généralement qu’il existe un autre problème.

Pour obtenir la source de référence de démarrage de Blazor WebAssembly, consultez le fichier Boot.WebAssembly.ts dans le dépôt GitHub dotnet/aspnetcore.

Diagnostic des problèmes d’intégrité

Lorsqu’une application est générée, le manifeste blazor.boot.json généré décrit les hachages SHA-256 des ressources de démarrage au moment où la sortie de build est générée. La vérification de l’intégrité réussit tant que les hachages SHA-256 dans blazor.boot.json correspondent aux fichiers remis au navigateur.

Les raisons courantes de cet échec sont :

• La réponse du serveur web est une erreur (par exemple, 404 - Introuvable ou 500 - Erreur de serveur interne) au lieu du fichier demandé par le navigateur. Cela est signalé par le navigateur en tant qu’échec de vérification de l’intégrité et non en tant qu’échec de réponse.
• Quelque chose a modifié le contenu des fichiers entre la génération et la remise des fichiers dans le navigateur. Cela peut se produire :
  • Si vous ou les outils de génération modifiez manuellement la sortie de build.
  • Si un aspect du processus de déploiement a modifié les fichiers. Par exemple, si vous utilisez un mécanisme de déploiement basé sur Git, gardez à l’esprit que Git convertit en toute transparence les terminaisons de ligne de style Windows en fin de ligne de style Unix si vous validez des fichiers sur Windows et que vous les extrayez sur Linux. La modification des fins de ligne de fichier modifie les hachages SHA-256. Pour éviter ce problème, envisagez d’utiliser .gitattributes pour traiter les artefacts de build comme des fichiers binary.
  • Le serveur web modifie le contenu du fichier dans le cadre de son service. Par exemple, certains réseaux de distribution de contenu (CDN) tentent automatiquement de minifier le code HTML, le modifiant ainsi. Vous devrez peut-être désactiver ces fonctionnalités.
• Le fichier blazor.boot.json ne parvient pas à se charger correctement ou est mis en cache incorrectement sur le client. Les causes courantes incluent les suivantes :
  • Code de développeur personnalisé mal configuré ou défectueux.
  • Une ou plusieurs couches de mise en cache intermédiaire mal configurées.

Pour diagnostiquer lequel de ces éléments s’applique dans votre cas :

1. Notez le fichier qui déclenche l’erreur en lisant le message d’erreur.
2. Ouvrez les outils de développement de votre navigateur et recherchez l’onglet Réseau. Si nécessaire, rechargez la page pour afficher la liste des demandes et des réponses. Recherchez le fichier qui déclenche l’erreur dans cette liste.
3. Vérifiez le code d’état HTTP dans la réponse. Si le serveur retourne autre chose que 200 - OK (ou un autre code d’état 2xx), vous avez un problème côté serveur à diagnostiquer. Par exemple, le code d’état 403 signifie qu’il existe un problème d’autorisation, tandis que le code d’état 500 signifie que le serveur échoue de manière non spécifiée. Consultez les journaux côté serveur pour diagnostiquer et corriger l’application.
4. Si le code d’état est 200 - OK pour la ressource, examinez le contenu de la réponse dans les outils de développement du navigateur et vérifiez que le contenu correspond aux données attendues. Par exemple, un problème courant est la mauvaise configuration du routage, faisant que les requêtes retournent vos données pour index.html même pour d’autres fichiers. Assurez-vous que les réponses aux requêtes .wasm sont des fichiers binaires WebAssembly et que les réponses aux requêtes .dll sont des fichiers binaires d’assembly .NET. Si ce n’est pas le cas, vous rencontrez un problème de routage côté serveur à diagnostiquer.
5. Essayez de valider la sortie publiée et déployée de l’application avec le script PowerShell Résoudre les problèmes d’intégrité.

Si vous confirmez que le serveur retourne des données plausiblement correctes, il doit y avoir autre chose qui modifie le contenu entre la génération et la remise du fichier. Pour vérifier cela :

• Examinez la chaîne d’outils de génération et le mécanisme de déploiement au cas où ils modifieraient les fichiers une fois les fichiers générés. Par exemple, Git transforme les terminaisons de ligne de fichier, comme décrit précédemment.
• Examinez la configuration du serveur web ou du CDN au cas où ils seraient configurés pour modifier les réponses de manière dynamique (par exemple, en essayant de minifier le code HTML). Le serveur web peut implémenter la compression HTTP (par exemple, en retournant content-encoding: br ou content-encoding: gzip), car cela n’affecte pas le résultat après la décompression. Toutefois, le serveur web ne peut pas modifier les données non compressées.

Script PowerShell Résoudre les problèmes d’intégrité

Utilisez le script PowerShell integrity.ps1 pour valider une application Blazor publiée et déployée. Le script est fourni pour PowerShell Core 7 ou version ultérieure comme point de départ lorsque l’application rencontre des problèmes d’intégrité que le framework Blazor ne peut pas identifier. La personnalisation du script peut être nécessaire pour vos applications, y compris en cas d’exécution sur une version de PowerShell ultérieure à la version 7.2.0.

Le script vérifie les fichiers du dossier publish et téléchargés à partir de l’application déployée pour détecter les problèmes dans les différents manifestes qui contiennent des hachages d’intégrité. Ces vérifications devraient détecter les problèmes les plus courants :

• Vous avez modifié un fichier dans la sortie publiée sans vous en rendre compte.
• L’application n’a pas été correctement déployée sur la cible de déploiement, ou quelque chose a changé dans l’environnement de la cible de déploiement.
• Il existe des différences entre l’application déployée et la sortie de la publication de l’application.

Appelez le script avec la commande suivante dans un interpréteur de commandes PowerShell :

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

Dans l’exemple suivant, le script est exécuté sur une application exécutée localement à l’adresse https://localhost:5001/ :

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

Espaces réservés :

• {BASE URL} : URL de l’application déployée. Une barre oblique de fin (/) est requise.
• {PUBLISH OUTPUT FOLDER} : chemin d’accès au dossier publish ou à l’emplacement où l’application est publiée pour le déploiement.

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

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

Désactiver la vérification de l’intégrité pour les applications non PWA

Dans la plupart des cas, ne désactivez pas la vérification d’intégrité. La désactivation de la vérification de l’intégrité ne résout pas le problème sous-jacent qui a provoqué les réponses inattendues, et entraîne la perte des avantages répertoriés précédemment.

Dans certains cas, vous ne pouvez pas vous fier au serveur web pour retourner des réponses cohérentes, et vous n’avez pas d’autre choix que de désactiver temporairement les vérifications d’intégrité jusqu’à ce que le problème sous-jacent soit résolu.

Pour désactiver les vérifications d’intégrité, ajoutez ce qui suit à un groupe de propriétés dans le fichier projet de l’application Blazor WebAssembly (.csproj) :

<BlazorCacheBootResources>false</BlazorCacheBootResources>

BlazorCacheBootResources désactive également le comportement par défaut de mise en cache des fichiers .dll, .wasm et autres de Blazor en fonction de leurs hachages SHA-256, car la propriété indique que les hachages SHA-256 ne peuvent pas être utilisés pour vérifier l’exactitude. Même avec ce paramètre, le cache HTTP normal du navigateur peut toujours mettre en cache ces fichiers ; la configuration de votre serveur web et des en-têtes cache-control qu’il sert détermine si cela se produit ou non.

Nous ne pouvons pas fournir une liste exhaustive des scénarios dans lesquels la désactivation de la vérification de l’intégrité est nécessaire. Les serveurs peuvent répondre à une requête de manière arbitraire en dehors de l’étendue du framework Blazor. Le framework fournit le paramètre BlazorCacheBootResources permettant de rendre l’application exécutable au prix de la perte de la garantie d’intégrité que l’application peut fournir. Là encore, nous vous déconseillons de désactiver la vérification de l’intégrité, en particulier pour les déploiements de production. Les développeurs doivent chercher à résoudre le problème d’intégrité sous-jacent qui provoque l’échec de la vérification de l’intégrité.

Voici quelques cas généraux qui peuvent entraîner des problèmes d’intégrité :

• Exécution sur HTTP, où l’intégrité ne peut pas être vérifiée.
• Si votre processus de déploiement modifie les fichiers après la publication de quelque manière que ce soit.
• Si votre hôte modifie les fichiers d’une manière quelconque.

Désactiver la vérification de l’intégrité pour les PWA

Le modèle d’application web progressive (PWA) de Blazor contient un fichier service-worker.published.js suggéré qui est responsable de l’extraction et du stockage des fichiers d’application pour une utilisation hors connexion. Il s’agit d’un processus distinct du mécanisme de démarrage normal de l’application, qui a sa propre logique de vérification de l’intégrité.

Dans le fichier service-worker.published.js, la ligne suivante est présente :

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

Pour désactiver la vérification de l’intégrité, supprimez le paramètre integrity en remplaçant la ligne par ce qui suit :

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

Là encore, la désactivation de la vérification de l’intégrité signifie que vous perdez les garanties de sécurité offertes par la vérification d’intégrité. Par exemple, il existe un risque que si le navigateur de l’utilisateur met en cache l’application au moment exact où vous déployez une nouvelle version, elle peut mettre en cache certains fichiers de l’ancien déploiement et d’autres du nouveau déploiement. Si cela se produit, l’application est bloquée dans un état rompu jusqu’à ce que vous déployiez une autre mise à jour.