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

Article
11/06/2024

Remarque

Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 8 de cet article.

Avertissement

Cette version d’ASP.NET Core n’est plus prise en charge. Pour plus d’informations, consultez la Stratégie de prise en charge de .NET et .NET Core. Pour la version actuelle, consultez la version .NET 8 de cet article.

Important

Ces informations portent sur la préversion du produit, qui est susceptible d’être en grande partie modifié avant sa commercialisation. Microsoft n’offre aucune garantie, expresse ou implicite, concernant les informations fournies ici.

Pour la version actuelle, consultez la version .NET 8 de cet article.

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.

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, qui comprend des informations sur l’hébergement d’une application Blazor WebAssembly en tant que sous-application IIS.

Les stratégies de déploiement suivantes sont prises en charge :

L’application Blazor est fournie par une application ASP.NET Core. Cette stratégie est abordée dans la section Déploiement hébergé avec ASP.NET Core.
L’application Blazor est placée sur un service ou un serveur web d’hébergement statique, où .NET n’est pas utilisé pour servir l’application Blazor. Cette stratégie est abordée dans la section Déploiement autonome, qui comprend des informations sur l’hébergement d’une application Blazor WebAssembly en tant que sous-application IIS.
Une application ASP.NET Core héberge plusieurs applications Blazor WebAssembly. Pour plus d’informations, consultez Plusieurs applications ASP.NET Core Blazor WebAssembly hébergées.

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

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 octets dans le fichier Program :

Lors de la création d’une application Blazor WebAssembly qui cible les navigateurs d’appareils mobiles, en particulier Safari sur iOS, la diminution maximale de la mémoire pour 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 octets 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’empaquetage Webcil pour les assemblys .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 :

Blazor s’appuie sur l’hôte pour traiter les fichiers compressés appropriés. Lors de l’utilisation d’un projet ASP.NET Core hébergéBlazor WebAssembly, le projet hôte est capable d’effectuer la négociation du contenu et de traiter les fichiers compressés de manière statique. 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 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.

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

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

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

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

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

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/) :

Le navigateur effectue une requête.
La page par défaut est retournée, généralement index.html.
index.html amorce l’application.
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.

Déploiement hébergé avec ASP.NET Core

Un déploiement hébergé fournit l’application Blazor WebAssembly aux navigateurs à partir d’une application ASP.NET Core qui s’exécute sur un serveur web.

Hébergé : L’application Blazor WebAssembly cliente est publiée dans le dossier /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot de l’application serveur, avec toutes les autres ressources web statiques de l’application serveur. Les deux applications sont déployées ensemble. Un serveur web capable d’héberger une application ASP.NET Core est nécessaire. Pour un déploiement hébergé, Visual Studio inclut le modèle de projet Application Blazor WebAssembly (modèle blazorwasm lors de l’utilisation de la commande dotnet new) avec l’option Hosted sélectionnée (-ho|--hosted lors de l’utilisation de la commande dotnet new).

Pour plus d’informations, consultez les articles suivants :

Hébergement et déploiement d’applications ASP.NET Core : Héberger et déployer ASP.NET Core
Déploiement sur Azure App Service : Publier une application ASP.NET Core sur Azure avec Visual Studio
Modèles de projet Blazor : Structure de projet ASP.NET Core Blazor

Déploiement hébergé d’un exécutable dépendant du framework pour une plateforme spécifique

Pour déployer une application hébergée Blazor WebAssembly en tant qu’exécutable dépendant du framework pour une plateforme spécifique (non autonome), utilisez les conseils suivants en fonction des outils utilisés.

Visual Studio

Un déploiement autonome est configuré pour un profil de publication généré (.pubxml). Vérifiez que le profil de publication du projet Server contient la propriété MSBuild <SelfContained> définie sur false.

Dans le fichier de profil de publication .pubxml dans le dossier Properties du projet Server :

<SelfContained>false</SelfContained>

Définissez l’Identificateur de runtime (RID) à l’aide du paramètre Runtime cible dans la zone Paramètres de l’interface utilisateur de Publication, qui génère la propriété MSBuild <RuntimeIdentifier> dans le profil de publication :

<RuntimeIdentifier>{RID}</RuntimeIdentifier>

Dans la configuration précédente, l’espace réservé {RID} est l’identificateur d’exécution (RID).

Publiez le projet Server dans la configuration Release.

Remarque

Il est possible de publier une application avec des paramètres de profil de publication à l’aide de l’interface CLI .NET en passant /p:PublishProfile={PROFILE} à la commande dotnet publish, où l’espace réservé {PROFILE} est le profil. Pour plus d’informations, consultez les sections Publier des profils et Exemple de publication de dossier dans l’article Profils de publication de Visual Studio (.pubxml) pour le déploiement d’applications ASP.NET Core. Si vous transmettez le RID dans la commande dotnet publish et non dans le profil de publication, utilisez la propriété MSBuild (/p:RuntimeIdentifier) avec la commande, pas avec l’option -r|--runtime.

CLI .NET

Configurez un déploiement autonome en plaçant la propriété MSBuild <SelfContained> dans un <PropertyGroup> dans le fichier projet du projet Server en définissant sa valeur sur false :

<SelfContained>false</SelfContained>

Important

La propriété SelfContained doit être placée dans le fichier projet du projet Server. La propriété ne peut pas être définie correctement avec la commande dotnet publish à l’aide de l’option --no-self-contained ou de la propriété MSBuild /p:SelfContained=false.

Définissez l’Identificateur de runtime (RID) à l’aide de l’une ou l’autre des approches suivantes :

Option 1 : Définissez le RID dans un <PropertyGroup> dans le fichier projet du projet Server :
```
<RuntimeIdentifier>{RID}</RuntimeIdentifier>
```
Dans la configuration précédente, l’espace réservé {RID} est l’identificateur d’exécution (RID).

Publiez l’application dans la configuration Release à partir du projet Server :
```
dotnet publish -c Release
```
Option 2 : transmettez le RID dans la commande dotnet publish en tant que propriété MSBuild (/p:RuntimeIdentifier), et pas avec l’option -r|--runtime :
```
dotnet publish -c Release /p:RuntimeIdentifier={RID}
```
Dans la commande précédente, l’espace réservé {RID} est l’identificateur d’exécution (RID).

Pour plus d’informations, consultez les articles suivants :

Déploiement hébergé avec plusieurs applications Blazor WebAssembly

Pour plus d’informations, consultez Plusieurs applications ASP.NET Core Blazor WebAssembly hébergées.

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 :

Enregistrez tout travail non enregistré dans le projet, car un redémarrage de Visual Studio peut être nécessaire pendant le processus.
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.
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.
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.
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é :

Placez le fichier web.config personnalisé dans le dossier racine du projet.
Publiez le projet. Pour plus d’informations, consultez Héberger et déployer ASP.NET Core Blazor.

Placez le fichier web.config personnalisé dans le dossier racine du projet. Pour une Blazor WebAssemblysolution hébergée, placez le fichier dans le dossier du projet Server.
Publiez le projet. Pour une solution Blazor WebAssembly hébergée, publiez la solution à partir du projet Server. Pour plus d’informations, consultez Héberger et déployer ASP.NET Core Blazor.

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 :

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

Cette section s’applique uniquement aux applications Blazor WebAssembly autonomes.

Cette section s’applique uniquement aux applications autonomes Blazor WebAssembly. Les applications hébergées Blazor utilisent un fichier web.config d’application ASP.NET Core par défaut, et non le fichier lié dans cette section.

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 :

Créez le fichier de configuration Apache. L’exemple suivant est un fichier de configuration simplifié (blazorapp.config) :

<VirtualHost *:80>
    ServerName www.example.com
    ServerAlias *.example.com

    DocumentRoot "/var/www/blazorapp"
    ErrorDocument 404 /index.html

    AddType application/wasm .wasm

    <Directory "/var/www/blazorapp">
        Options -Indexes
        AllowOverride None
    </Directory>

    <IfModule mod_deflate.c>
        AddOutputFilterByType DEFLATE text/css
        AddOutputFilterByType DEFLATE application/javascript
        AddOutputFilterByType DEFLATE text/html
        AddOutputFilterByType DEFLATE application/octet-stream
        AddOutputFilterByType DEFLATE application/wasm
        <IfModule mod_setenvif.c>
            BrowserMatch ^Mozilla/4 gzip-only-text/html
            BrowserMatch ^Mozilla/4.0[678] no-gzip
            BrowserMatch bMSIE !no-gzip !gzip-only-text/html
        </IfModule>
    </IfModule>

    ErrorLog /var/log/httpd/blazorapp-error.log
    CustomLog /var/log/httpd/blazorapp-access.log common
</VirtualHost>

Créez le fichier de configuration Apache. L’exemple suivant est un fichier de configuration simplifié (blazorapp.config) :

<VirtualHost *:80>
    ServerName www.example.com
    ServerAlias *.example.com

    DocumentRoot "/var/www/blazorapp"
    ErrorDocument 404 /index.html

    AddType application/wasm .wasm
    AddType application/octet-stream .dll

    <Directory "/var/www/blazorapp">
        Options -Indexes
        AllowOverride None
    </Directory>

    <IfModule mod_deflate.c>
        AddOutputFilterByType DEFLATE text/css
        AddOutputFilterByType DEFLATE application/javascript
        AddOutputFilterByType DEFLATE text/html
        AddOutputFilterByType DEFLATE application/octet-stream
        AddOutputFilterByType DEFLATE application/wasm
        <IfModule mod_setenvif.c>
            BrowserMatch ^Mozilla/4 gzip-only-text/html
            BrowserMatch ^Mozilla/4.0[678] no-gzip
            BrowserMatch bMSIE !no-gzip !gzip-only-text/html
        </IfModule>
    </IfModule>

    ErrorLog /var/log/httpd/blazorapp-error.log
    CustomLog /var/log/httpd/blazorapp-access.log common
</VirtualHost>

Placez le fichier config Apache dans le répertoire /etc/httpd/conf.d/.
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).
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 :

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.

Remarque

Le dépôt GitHub SteveSandersonMS/BlazorOnGitHubPages n’est pas détenu, géré ou pris en charge par .NET Foundation ou par Microsoft.

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.

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 href="/CoolApp/"> (inclut une barre oblique) comme chemin de base de l’application dans la balise <base>, 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
```

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

Déploiement hébergé sur Linux (Nginx)

Configurez l’application avec ForwardedHeadersOptions pour transférer les en-têtes X-Forwarded-For et X-Forwarded-Proto en suivant les instructions de Configurer ASP.NET Core pour l’utilisation de serveurs proxy et d’équilibreurs de charge.

Pour plus d’informations sur la définition du chemin de base de l’application, y compris la configuration du chemin d’accès de sous-application, consultez Héberger et déployer ASP.NET Core Blazor.

Suivez les instructions pour une application ASP.NET Core SignalR avec les modifications suivantes :

Supprimez la configuration de la mise en mémoire tampon du proxy (proxy_buffering off;), car le paramètre s’applique uniquement aux événements envoyés par le serveur (SSE), qui ne sont pas pertinents pour les interactions client-serveur de l’applicationBlazor.
Remplacez le chemin location de /hubroute (location /hubroute { ... }) par le chemin de sous-application /{PATH} (location /{PATH} { ... }), où l’espace réservé {PATH} est le chemin de la sous-application.

L’exemple suivant configure le serveur pour une application qui répond aux requêtes au niveau du chemin racine / :
```
http {
    server {
        ...
        location / {
            ...
        }
    }
}
```
L’exemple suivant configure le chemin d’accès de la sous-application de /blazor :
```
http {
    server {
        ...
        location /blazor {
            ...
        }
    }
}
```

Pour plus d’informations et pour obtenir de l’aide sur la configuration, consultez les ressources suivantes :

Héberger ASP.NET Core sur Linux avec Nginx
Documentation Nginx :
- NGINX en tant que proxy WebSocket
- Proxy WebSocket
Développeurs sur des forums d’assistance non Microsoft :

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.

Configurer l'éditeur de liens

Blazor effectue la liaison de 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’éditeur de liens pour ASP.NET Core Blazor.

Modifier l’extension de nom de fichier des fichiers DLL

Cette section s’applique à ASP.NET Core 6.x ou 7.x. Dans ASP.NET Core dans .NET 8 ou ultérieur, les assemblys .NET sont déployés en tant que fichiers WebAssembly (.wasm) avec le format de fichier Webcil. Dans ASP.NET Core dans .NET 8 ou ultérieur, cette section s’applique uniquement si le format de fichier Webcil a été désactivé dans le fichier projet de l’application.

Si un pare-feu, un programme antivirus ou une appliance de sécurité réseau bloque la transmission des fichiers DLL (bibliothèque de liens dynamiques) de l’application (.dll), vous pouvez suivre les instructions de cette section pour modifier les extensions de nom de fichier des fichiers DLL publiés de l’application.

Remarque

La modification des extensions de nom de fichier des fichiers DLL de l’application peut ne pas résoudre le problème, car de nombreux systèmes de sécurité analysent le contenu des fichiers de l’application, et pas simplement les extensions de fichier.

Pour une approche plus solide dans les environnements qui bloquent le téléchargement et l’exécution de fichiers DLL, utilisez ASP.NET Core dans .NET 8 ou version ultérieure, qui par défaut crée des packages des assemblys .NET en tant que fichiers WebAssembly (.wasm) avec le format de fichier Webcil. Pour plus d’informations, consultez la section Format d’empaquetage Webcil pour les assemblys .NET dans une version 8.0 ou ultérieure de cet article.

Il existe des approches tierces pour résoudre ce problème. Pour plus d’informations, consultez les ressources sur Awesome Blazor.

Remarque

Pour une approche plus robuste dans les environnements qui bloquent le téléchargement et l’exécution des fichiers DLL, suivez l’une des approches suivantes :

Utilisez ASP.NET Core dans .NET 8 ou version ultérieure, qui crée des packages des assemblys .NET en tant que fichiers WebAssembly (.wasm) avec le format de fichier Webcil. Pour plus d’informations, consultez la section Format d’empaquetage Webcil pour les assemblys .NET dans une version 8.0 ou ultérieure de cet article.
Dans ASP.NET Core dans .NET 6 ou ultérieur, utilisez une disposition de déploiement personnalisée.

Il existe des approches tierces pour résoudre ce problème. Pour plus d’informations, consultez les ressources sur Awesome Blazor.

Après avoir publié l’application, utilisez un script shell ou un pipeline de build DevOps pour renommer les fichiers .dll pour utiliser une autre extension de fichier dans le répertoire de la sortie publiée de l’application.

Dans les exemples suivants :

PowerShell (PS) est utilisé pour mettre à jour les extensions de fichier.
Les fichiers .dll sont renommés pour utiliser l’extension de fichier .bin à partir de la ligne de commande.
Les fichiers répertoriés dans le fichier blazor.boot.json publié avec une extension de fichier .dll sont mis à jour vers l’extension de fichier .bin.
Si les ressources du Worker de service sont également utilisées, une commande PowerShell met à jour les fichiers .dll répertoriés dans le fichier service-worker-assets.js vers l’extension de fichier .bin.

Pour utiliser une extension de fichier différente de .bin, remplacez .bin dans les commandes suivantes par l’extension de fichier souhaitée.

Sur Windows :

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

Dans la commande précédente, l’espace réservé {PATH} est le chemin d’accès au dossier _framework publié (par exemple, .\bin\Release\net6.0\browser-wasm\publish\wwwroot\_framework à partir du dossier racine du projet).

Si des ressources de travail de service sont également utilisées :

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

Dans la commande précédente, l’espace réservé {PATH} est le chemin d’accès au fichier service-worker-assets.js publié.

Sur Linux ou macOS :

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

Si des ressources de travail de service sont également utilisées :

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

Dans la commande précédente, l’espace réservé {PATH} est le chemin d’accès au fichier service-worker-assets.js publié.

Pour traiter les fichiers compressés blazor.boot.json.gz et blazor.boot.json.br, adoptez l’une des approches suivantes :

Supprimez les fichiers blazor.boot.json.gz et blazor.boot.json.br compressés. La compression est désactivée avec cette approche.
Recompressez le fichier blazor.boot.json mis à jour.

Les conseils précédents pour le fichier blazor.boot.json compressé s’appliquent également lorsque les ressources du Worker de service sont en cours d’utilisation. Supprimez ou recompressez service-worker-assets.js.br et service-worker-assets.js.gz. Sinon, les vérifications d’intégrité des fichiers échouent dans le navigateur.

L’exemple Windows suivant pour .NET 6 utilise un script PowerShell placé à la racine du projet. Le script suivant, qui désactive la compression, est la base des modifications supplémentaires si vous souhaitez recompresser le fichier blazor.boot.json.

ChangeDLLExtensions.ps1: :

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

Si des ressources Worker de service sont également utilisées, ajoutez les commandes suivantes :

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

Dans le fichier projet, le script est exécuté après la publication de l’application pour la configuration Release :

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

Remarque

Lors du changement de nom et du chargement différé des mêmes assemblys, consultez les instructions d’Assemblys de chargement différé dans ASP.NET Core Blazor WebAssembly.

En règle générale, le serveur de l’application nécessite une configuration de ressource statique pour traiter les fichiers avec l’extension mise à jour. Pour une application hébergée par IIS, ajoutez une entrée de carte MIME (<mimeMap>) pour la nouvelle extension de fichier dans la section de contenu statique (<staticContent>) dans un fichier web.config personnalisé. L’exemple suivant suppose que l’extension de fichier est modifiée de .dll à .bin :

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

Incluez une mise à jour pour les fichiers compressés si la compression est en cours d’utilisation :

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

Supprimez l’entrée de l’extension de fichier .dll :

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

Supprimez les entrées des fichiers .dll compressés si la compression est en cours d’utilisation :

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

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

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.

Remarque

Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Échanger les branches ou les balises. Pour plus d’informations, consultez Comment sélectionner une balise de version du code source ASP.NET Core (dotnet/AspNetCore.Docs #26205).

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 :

Notez le fichier qui déclenche l’erreur en lisant le message d’erreur.
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.
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.
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.
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.

Remarque

Lors du clonage du dépôt GitHub dotnet/AspNetCore.Docs, le script integrity.ps1 peut être mis en quarantaine par Bitdefender ou un autre scanneur antivirus présent sur le système. En règle générale, le fichier est piégé par la technologie d’analyse heuristique d’un scanneur antivirus, qui recherche simplement des modèles dans les fichiers susceptibles d’indiquer la présence de programmes malveillants. Pour empêcher le scanneur antivirus de mettre en quarantaine le fichier, ajoutez une exception au scanneur antivirus avant de cloner le dépôt. L’exemple suivant est un chemin d’accès classique au script sur un système Windows. Ajustez le chemin d’accès en fonction pour les autres systèmes. L’espace réservé {USER} est le segment de chemin d’accès de l’utilisateur.

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

Avertissement : la création d’exceptions antivirus est dangereuse et ne doit être effectuée que lorsque vous êtes certain que le fichier est sécurisé.

La comparaison de la somme de contrôle d’un fichier à une valeur de somme de contrôle valide ne garantit pas la sécurité des fichiers, mais la modification d’un fichier d’une manière qui conserve la valeur de somme de contrôle n’est pas triviale pour les utilisateurs malveillants. Par conséquent, les sommes de contrôle sont utiles en tant qu’approche de sécurité générale. Comparez la somme de contrôle du fichier integrity.ps1 local à l’une des valeurs suivantes :

SHA256 : 32c24cb667d79a701135cb72f6bae490d81703323f61b8af2c7e5e5dc0f0c2bb
MD5 : 9cee7d7ec86ee809a329b5406fbf21a8

Obtenez la somme de contrôle du fichier sur le système d’exploitation Windows avec la commande suivante. Indiquez le chemin d’accès et le nom de fichier de l’espace réservé {PATH AND FILE NAME} et indiquez le type de somme de contrôle à produire pour l’espace réservé {SHA512|MD5}, SHA256 ou MD5 :

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

Si vous êtes préoccupé par le fait que la validation de somme de contrôle n’est pas suffisamment sécurisée dans votre environnement, consultez le leadership de sécurité de votre organisation pour obtenir des conseils.

Pour plus d’informations, consultez Vue d’ensemble de la protection contre les menaces de l’Antivirus Microsoft Defender.

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.

Remarque

La propriété BlazorCacheBootResources ne désactive pas les vérifications d’intégrité pour les applications web progressives (PWA). Pour obtenir des conseils sur les PWA, consultez la section Désactiver la vérification de l’intégrité pour les PWA.

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.

Partage via

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

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

Réduire la taille maximale du tas pour certains navigateurs d’appareils mobiles

Format d’empaquetage Webcil pour les assemblys .NET

Personnaliser le mode de chargement des ressources de démarrage

Compression

Réécriture d’URL pour un routage correct

Déploiement hébergé avec ASP.NET Core

Déploiement hébergé d’un exécutable dépendant du framework pour une plateforme spécifique

Visual Studio

CLI .NET

Déploiement hébergé avec plusieurs applications Blazor WebAssembly

Déploiement autonome

Azure App Service

Azure Static Web Apps

Déployer à partir de Visual Studio

Déployer à partir de Visual Studio Code

Déployer à partir de GitHub

IIS

web.config

Utiliser un web.config personnalisé

Installer le module de réécriture d’URL

Configurer le site web

Hôte en tant que sous-application IIS

Compression Brotli et Gzip

Résolution des problèmes

Azure Storage

Nginx

Apache

GitHub Pages

Autonome avec Docker

Valeurs de configuration de l’hôte

Racine de contenu

Base du chemin

URL

Déploiement hébergé sur Linux (Nginx)

Configurer l’outil de découpage

Configurer l'éditeur de liens

Modifier l’extension de nom de fichier des fichiers DLL

Endommagement par un déploiement antérieur

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

Diagnostic des problèmes d’intégrité

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

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

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

Ressources supplémentaires

Utiliser un `web.config` personnalisé