Déboguer des ressources web JavaScript à l’aide de remplacements locaux

Lorsque vous développez et déboguez des ressources web JavaScript que vous utilisez en tant que gestionnaire d’événements dans une application pilotée par modèle, vous devez généralement apporter plusieurs modifications et tester leur fonctionnement. Le chargement et la publication de la ressource web après chaque modification ralentit ce processus.

Les outils de développement de navigateur modernes offrent des fonctionnalités permettant d’enregistrer une copie locale de la ressource web. Lorsque l’application pilotée par modèle demande la ressource web, le navigateur charge votre copie locale au lieu du fichier à partir du serveur. Vous pouvez modifier la copie locale, actualiser la page et tester vos modifications sans charger et publier à plusieurs reprises la ressource web. Vous n’avez pas besoin d’installer de logiciels proxy, d’extensions de navigateur ou de certificats.

En savoir plus sur la façon dont les navigateurs modernes fournissent ces fonctionnalités.

• Microsoft Edge Remplacements locaux
• Google Chrome Remplacements locaux
• Firefox Remplacements réseau
• Safari Remplacements locaux de l’inspecteur web de WebKit

Important

Une substitution locale modifie uniquement la ressource chargée par votre navigateur. Cela ne met pas à jour la ressource web JavaScript dans Microsoft Dataverse, et d'autres utilisateurs ne voient pas vos modifications. Une fois la résolution des problèmes terminé, copiez les modifications que vous souhaitez conserver dans votre fichier source et utilisez votre processus normal pour mettre à jour et publier la ressource web. Cet article ne décrit pas ce processus.

Prerequisites

Avant de commencer :

• Vous avez besoin d’une application basée sur un modèle qui dispose d’une ressource web JavaScript utilisée pour fournir des gestionnaires d’événements pour un formulaire.

  Cet article utilise la ressource web JavaScript décrite dans Écrire votre premier script client. Cette procédure pas à pas crée une ressource web JavaScript nommée example_form-script.js, l’ajoute au formulaire Compte et inscrit des fonctions pour les événements Au chargement et À l’enregistrement du formulaire, ainsi que pour l’événement À la modification de la colonne Nom.

  Note

  Vous pouvez télécharger le JavaScriptWebResourceExampleSolution_1_0_managed.zip. Installez cette solution managée et vous trouverez une application pilotée par modèle qui représente le résultat terminé de l’article Écrire votre premier script client.

• Cet article utilise Microsoft Edge, mais les outils de développement de Google Chrome, Firefox et Safari offrent des fonctionnalités similaires.

• Créez un dossier vide sur votre ordinateur pour Microsoft Edge DevTools afin de stocker les remplacements locaux. N’utilisez pas de dossier qui contient des fichiers sources, des informations d’identification, des certificats ou d’autres informations sensibles. DevTools crée la structure de dossiers dont elle a besoin dans ce dossier. Cet article utilise C:\temp\overrides , mais vous souhaiterez peut-être utiliser C:\Users\<your user name>\overrides.

Cet article utilise le script suivant, tiré de Écrire votre premier script client :

// Define a unique namespace for the sample library.
window.Example ??= {};

(() => {
    const notificationId = "_myUniqueId";
    const currentUserName = Xrm.Utility.getGlobalContext().userSettings.userName;
    const message = `${currentUserName}: Your JavaScript code in action!`;

    // Code to run in the form OnLoad event
    window.Example.formOnLoad = (executionContext) => {
        const formContext = executionContext.getFormContext();

        // Display the form level notification as an INFO
        formContext.ui.setFormNotification(message, "INFO", notificationId);

        // Wait for 5 seconds before clearing the notification
        window.setTimeout(
            () => formContext.ui.clearFormNotification(notificationId),
            5000
        );
    };

    // Code to run in the column OnChange event
    window.Example.attributeOnChange = (executionContext) => {
        const formContext = executionContext.getFormContext();

        // Automatically set some column values if the account name contains "Contoso"
        const accountName = formContext.getAttribute("name").getValue();
        if (accountName?.toLowerCase().includes("contoso")) {
            formContext.getAttribute("websiteurl").setValue("https://www.contoso.com");
            formContext.getAttribute("telephone1").setValue("425-555-0100");
            formContext.getAttribute("description").setValue("Website URL, Phone and Description set using custom script.");
        }
    };

    // Code to run in the form OnSave event
    window.Example.formOnSave = () => {
        // Display an alert dialog
        Xrm.Navigation.openAlertDialog({ text: "Record saved." });
    };
})();

Cette ressource web JavaScript fournit trois fonctions inscrites pour les événements suivants :

Function	Event
Example.formOnLoad	Au chargement du formulaire
Example.attributeOnChange	À la modification du champ
Example.formOnSave	Form OnSave

Les étapes fonctionnent également avec n’importe quelle ressource web JavaScript inscrite en tant que gestionnaire d’événements de formulaire. Utilisez le nom de votre ressource web et déclenchez son événement lorsque les étapes font référence à l’exemple.

Vérifiez que le script publié fonctionne

Avant de créer un remplacement, vérifiez le comportement actuel de la ressource web publiée :

1. Ouvrez l’application basée sur des modèles dans Microsoft Edge.

2. Ouvrez une fiche de compte existante ou créez-en une nouvelle.

3. Vérifiez qu’une notification de formulaire similaire au message suivant s’affiche pendant cinq secondes :

   <Your Name>: Your JavaScript code in action!

Cette étape confirme que le formulaire charge la ressource web et appelle le gestionnaire d’événements Example.formOnLoad.

Configurer les surcharges locales

Vous ne devez sélectionner un dossier de remplacements que la première fois que vous utilisez les remplacements locaux dans un profil de navigateur Microsoft Edge.

1. Une fois le formulaire de compte ouvert, appuyez sur F12 ou Ctrl++ pour ouvrir DevTools.

2. Sélectionnez l’outil Sources .

3. Dans le volet Navigateur, sélectionnez l’onglet Remplacements. Si l’onglet n’est pas visible, sélectionnez Plus d’onglets, puis sélectionnez Remplacements.

4. Sélectionnez Sélectionner un dossier pour les remplacements.

5. Sélectionnez le dossier vide que vous avez créé pour les remplacements, puis sélectionnez Sélectionner un dossier.

6. Lorsque DevTools demande un accès complet au dossier, sélectionnez Autoriser.

   

7. Vérifiez que l’option Activer les remplacements locaux est sélectionnée.

   

Activer le contournement du réseau pour les Service Workers

Important

L’activation de l’option Contourner pour le réseau garantit l’application des remplacements locaux de DevTools en empêchant les Service Workers de fournir des réponses mises en cache. Si vous n’effectuez pas cette étape, les remplacements locaux ne fonctionneront pas avec les applications pilotées par modèle.

1. Dans DevTools, sélectionnez l’onglet Application .

   Si l’onglet n’est pas visible, sélectionnez + (Autres onglets), puis Application.

2. Dans le volet de navigation gauche, sélectionnez Service Workers.

3. Sélectionnez Contourner le réseau pour forcer les requêtes à contourner le Service Worker et à utiliser le réseau à la place.

   

4. Actualisez la page pour appliquer la modification.

Créer un remplacement pour la ressource web

Utilisez l’outil Network pour rechercher le fichier JavaScript chargé par le formulaire de compte :

1. Sélectionnez l’outil Réseau .

2. Si l’activité réseau n’est pas enregistrée, sélectionnez Enregistrer le journal réseau.

3. Actualisez la page afin que le formulaire charge à nouveau la ressource web.

4. Dans la zone Filtre , commencez à taper le nom de la ressource web, par exemple : example_form-script.js.

5. Dans la liste des requêtes réseau, cliquez avec le bouton droit sur example_form-script.js, puis sélectionnez Remplacer le contenu.

   

6. Sélectionnez l’outil Sources, puis sélectionnez l’onglet Remplacements.

7. Développez les dossiers créés par DevTools, puis sélectionnez example_form-script.js.

   

   DevTools copie la ressource web dans le dossier Overrides. Un point violet sur l’icône de fichier indique que DevTools a remplacé la ressource.

Tip

Vous pouvez également créer le remplacement à partir de l’onglet Page dans l’outil Sources. Recherchez la ressource web, cliquez dessus avec le bouton droit, puis sélectionnez Remplacer le contenu.

Vérifiez que Microsoft Edge charge la copie locale

Apportez une modification facilement reconnaissable afin de vérifier que le remplacement fonctionne :

1. Dans l’éditeur DevTools, recherchez la ligne suivante :

   const message = `${currentUserName}: Your JavaScript code in action!`;
   

2. Remplacez-la par cette ligne :

   const message = `${currentUserName}: Local override in action!`;
   

   Note

   Si vous essayez de coller du code dans l’éditeur DevTools, vous voyez cette boîte de dialogue. Vous devez taper allow pasting et sélectionner Autoriser pour continuer. Cette boîte de dialogue n’apparaît pas si vous apportez directement des modifications.

   

3. Remplacez la durée de notification de 5000 par 15000.

4. Appuyez sur Ctrl+S pour enregistrer le fichier local.

5. Actualisez le formulaire du compte.

6. Vérifiez que la notification affiche Remplacement local activé ! et reste visible pendant 15 secondes.

   

Le message et la durée modifiés confirment que Microsoft Edge a chargé le remplacement local au lieu de la ressource web publiée.

Déboguer les gestionnaires d’événements

Après avoir confirmé que la surcharge fonctionne, utilisez le débogueur DevTools pour examiner le script.

Déboguer l’événement OnLoad du formulaire

1. Dans l’outil Sources, ouvrez le fichier example_form-script.js remplacé.

2. Sélectionnez le numéro de ligne de cette instruction pour définir un point d’arrêt :

   

3. Actualisez le formulaire du compte.

4. Lorsque l’exécution du script s’interrompt, utilisez le volet Scope pour inspecter executionContext et formContext.

   

5. Parcourez la fonction et observez l’appel à setFormNotification.

6. Sélectionnez Reprendre l’exécution du script pour continuer.

Déboguer l’événement OnChange nom de compte

1. Définissez un point d’arrêt sur cette instruction dans Example.attributeOnChange :

   const accountName = formContext.getAttribute("name").getValue();
   

2. Dans le formulaire de compte, modifiez Account Name, puis déplacez le focus hors de la colonne pour déclencher l’événement On Change.

3. Lorsque l’exécution s’interrompt, inspectez la valeur de accountName.

   

4. Utilisez un nom de compte qui contient Contosoet parcourez la fonction pour observer comment le script définit les valeurs Site Web, Téléphone principal et Description.

Déboguer l’événement OnSave du formulaire

1. Définissez un point d’arrêt sur l’instruction Xrm.Navigation.openAlertDialog dans Example.formOnSave.

2. Enregistrez l’enregistrement.

3. Lorsque l’exécution s’interrompt, inspectez la pile des appels pour confirmer que l’événement On Save du formulaire a appelé la fonction attendue.

   

4. Reprendre l’exécution du script et confirmer que la boîte de dialogue d’alerte s’ouvre.

Vous pouvez modifier et enregistrer la substitution chaque fois que vous souhaitez tester un correctif possible. Actualisez le formulaire pour tester les modifications apportées au code qui s’exécute lorsque le formulaire se charge. Déclenchez l’événement de formulaire ou de colonne approprié pour tester d’autres gestionnaires d’événements. Utilisez l’outil console pour passer en revue les erreurs et la sortie du journal.

Comparer le remplacement avec la ressource web publiée

Pour vérifier si un problème est dû à vos modifications locales :

1. Dans l’outil Sources, sélectionnez l’onglet Remplacements.
2. Décochez Activer les remplacements locaux.
3. Actualisez le formulaire du compte et testez de nouveau l’événement.

Microsoft Edge charge maintenant la ressource web publiée depuis le serveur. Sélectionnez Activer les remplacements locaux et actualisez le formulaire pour reprendre à l’aide de la copie locale.

Finaliser le dépannage

Les fichiers de remplacement local ne sont pas connectés à la ressource web dans Dataverse ou aux fichiers sources de votre solution.

1. Copiez les modifications que vous souhaitez conserver du fichier de substitution dans le fichier source que vous utilisez pour gérer la ressource web.
2. Utilisez votre processus de développement et de déploiement normal pour mettre à jour et publier la ressource web JavaScript.
3. Testez la ressource web publiée avec Activer les remplacements locaux désactivé.
4. Lorsque vous n’avez plus besoin de la configuration de remplacement, sélectionnez Effacer la configuration sous l’onglet Remplacements .

Caution

Ne traitez pas le fichier dans le dossier des remplacements comme fichier source pour la ressource web. Conservez les modifications que vous souhaitez conserver avant d’effacer la configuration ou de supprimer les fichiers de surcharge locale.

Résoudre les remplacements locaux

Voici des problèmes que vous pouvez rencontrer lors de l’utilisation des remplacements locaux.

La ressource web n’apparaît pas dans l’outil Réseau

Vérifiez que l’outil Réseau enregistre, effacez les filtres, puis actualisez le formulaire. Le formulaire doit charger la ressource web avant d’apparaître. Vérifiez également que la bibliothèque JavaScript est ajoutée au formulaire et que les personnalisations de formulaire sont publiées.

La commande Remplacer le contenu d’origine n’est pas disponible

Revenez à l’outil Sources et vérifiez que vous avez sélectionné un dossier de remplacements, autorisé DevTools à y accéder et sélectionné Activer les remplacements locaux. Actualisez ensuite le formulaire et réessayez.

Le formulaire utilise toujours le script publié

Maintenez DevTools ouvert, vérifiez que l’option Activer les remplacements locaux est sélectionnée et vérifiez que la ressource web a un point violet dans l’outil Réseau ou Sources . Enregistrez le remplacement, puis réactualisez le formulaire.

Le point d’arrêt n’est pas atteint

Vérifiez que vous avez défini le point d’arrêt dans le fichier redéfini et qu’il apparaît activé. Déclenchez l’événement associé à cette fonction : actualisez le formulaire pour On Load, modifiez la colonne configurée pour On Change ou enregistrez l’enregistrement pour On Save. Vérifiez également l’outil Console pour vérifier la présence d’une erreur de syntaxe qui empêche le chargement du script.

Informations connexes

• Remplacements des ressources de page web avec des copies locales (onglet Remplacements)
• Vue d’ensemble de l’outil Sources
• Déboguer JavaScript
• Création de scripts client à l’aide de JavaScript
• Ressources web JavaScript