ASP.NET Core Blazor WebAssembly runtime .NET et la mise en cache des offres groupées d’applications

Note

Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 9 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 support .NET et .NET Core. Pour la version actuelle, consultez la version .NET 9 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 9 de cet article.

Lorsqu’une application Blazor WebAssembly se charge dans le navigateur, l’application télécharge les ressources de démarrage à partir du serveur :

• Code JavaScript pour démarrer l’application
• Runtime et assemblys .NET
• Données spécifiques aux paramètres régionaux

À l’exception du fichier de ressources de démarrage de Blazor (blazor.boot.json), le runtime WebAssembly .NET et les fichiers groupés d’applications sont mis en cache sur les clients. Le fichier blazor.boot.json contient un manifeste des fichiers qui composent l’application qui doit être téléchargée avec un hachage du contenu du fichier utilisé pour détecter si l’une des ressources de démarrage a changé. Blazor met en cache les fichiers téléchargés à l’aide de l’API cache du navigateur.

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.

Note

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 :

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 :

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

PowerShell

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

Note

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 :

Console

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 mise en cache et les vérifications d’intégrité des ressources 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) :

XML

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

Note

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 mise en cache des ressources et les contrôles d’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 :

JavaScript

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

JavaScript

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

Ressources supplémentaires

Chargement des ressources de démarrage