Déboguer des compléments Office dans Visual Studio

Cet article explique comment déboguer du code côté client dans les compléments Office créés avec l’un des modèles de projet complément Office dans Visual Studio 2022. Pour plus d’informations sur le débogage du code côté serveur dans les compléments Office, voir Vue d’ensemble du débogage des compléments Office - Côté serveur ou côté client ?.

Remarque

Vous ne pouvez pas utiliser Visual Studio pour déboguer des compléments dans Office sur Mac. Pour plus d’informations sur le débogage sur un Mac, voir Déboguer des compléments Office sur un Mac.

Réviser les propriétés de création et de débogage

Avant de commencer le débogage, passez en revue les propriétés de chaque projet pour vérifier que Visual Studio ouvre l’application Office souhaitée et que les autres propriétés de build et de débogage sont définies de manière appropriée.

Propriétés du projet de complément

Ouvrez la fenêtre Propriétés du projet de complément pour passer en revue les propriétés du projet.

1. Dans l’Explorateur de solutions, choisissez le projet de complément (pas le projet d’application web).

2. Dans la barre de menu, choisissez Affichage>Fenêtre Propriétés.

Le tableau suivant décrit les propriétés du projet de complément.

Propriété	Description
Action de démarrage	Spécifie le mode de débogage pour votre complément. Cette option doit être définie sur Client de bureau Office lorsque vous souhaitez déboguer dans Microsoft 365 sur Windows. Pour déboguer dans Microsoft 365 sur le web, il doit être défini sur Microsoft Edge.
Document de démarrage (Compléments Excel, PowerPoint et Word uniquement)	Spécifie le document à ouvrir lors du démarrage du projet. Dans un nouveau projet, cette valeur est définie sur [Nouveau classeur Excel],[Nouveau document Word] ou [Nouvelle présentation PowerPoint]. Pour spécifier un document particulier, suivez les étapes décrites dans Utiliser un document existant pour déboguer le complément.
Projet Web	Spécifie le nom du projet web associé au complément.
Adresse e-mail (Compléments Outlook uniquement)	Spécifie l’adresse de messagerie du compte utilisateur dans Exchange Server ou Exchange Online avec lequel vous souhaitez tester votre complément Outlook. Si ce champ n’est pas renseigné, vous serez invité à entrer l’adresse e-mail lorsque vous démarrerez le débogage.
Url EWS (Compléments Outlook uniquement)	Spécifie l’URL des services web Exchange (par exemple : https://www.contoso.com/ews/exchange.aspx). Cette propriété peut être laissée vide.
Url OWA (Compléments Outlook uniquement)	Spécifie l’URL Outlook sur le web (par exemple : https://www.contoso.com/owa). Cette propriété peut être laissée vide.
Utiliser l’authentification multi-facteur (Compléments Outlook uniquement)	Spécifie la valeur booléenne qui indique si l’authentification multifacteur doit être utilisée. La valeur par défaut est false, mais la propriété n’a aucun effet pratique. Si vous devez normalement fournir un deuxième facteur pour vous connecter au compte de messagerie, vous serez invité à le faire lorsque vous démarrerez le débogage.
Nom d'utilisateur (Compléments Outlook uniquement)	Spécifie le nom du compte utilisateur dans Exchange Server ou Exchange Online avec lequel vous souhaitez tester votre complément Outlook. Cette propriété peut être laissée vide.
Fichier du projet	Indique le nom du fichier contenant la version, la configuration et d’autres informations sur le projet.
Dossier du projet	Précise l’emplacement du fichier de projet.
Configuration du déploiement actif (présente uniquement lors du débogage d’Excel, PowerPoint ou Word sur le web)	Spécifie la configuration du déploiement. Cette valeur doit être définie sur Par défaut.
Connexion au serveur (présente uniquement lors du débogage d’Excel, PowerPoint ou Word sur le web)	Spécifie si le projet se connecte au service SharePoint spécifié dans la propriété URL du site . Cette valeur doit être définie sur En ligne.
URL du site ; (présente uniquement lors du débogage d’Excel, PowerPoint ou Word sur le web)	Spécifie l’URL complète et absolue du locataire SharePoint que vous souhaitez héberger les pages du complément lors du débogage. Par exemple, https://mysite.sharepoint.com/

Remarque

Pour un complément Outlook, vous pouvez choisir de spécifier des valeurs pour une ou plusieurs des propriétés des compléments Outlook uniquement dans la fenêtre Propriétés , mais cela n’est pas obligatoire.

Propriétés du projet application Web

Ouvrez la fenêtre Propriétés du projet d’application web pour passer en revue les propriétés du projet.

1. Dans Explorateur de solutions, choisissez le projet d’application web.

2. Dans la barre de menu, choisissez Affichage>Fenêtre Propriétés.

Le tableau suivant décrit les propriétés du projet d’application web qui sont les plus pertinentes aux projets complément Office.

Propriété	Description
SSL activé	Spécifie si SSL est activé sur le site. Cette propriété doit être définie sur vrai pour les projets complément Office.
URL SSL	Spécifie l’URL HTTPS sécurité pour le site. Lecture seule.
URL	Spécifie l’URL HTTP pour le site. Lecture seule.
Fichier du projet	Indique le nom du fichier contenant la version, la configuration et d’autres informations sur le projet.
Dossier du projet	Précise l’emplacement du fichier de projet. Lecture seule. Le fichier manifeste créé par Visual Studio lors de l’exécution est écrit le bin\Debug\OfficeAppManifests dossier dans cet emplacement.

Déboguer un projet de complément sur le bureau Windows

Cette section explique comment démarrer et déboguer un complément dans office de bureau sur Windows. autrement dit, lorsque la propriété Action de démarrage du projet de complément est définie sur Client Office Desktop.

Démarrer le projet de complément

Démarrez le projet en choisissant Déboguer>Démarrer le débogage dans la barre de menus ou appuyez sur le bouton F5. Visual Studio génère automatiquement la solution et démarre l’application hôte Office.

Lorsque Visual Studio génère le projet, il effectue les tâches suivantes :

1. Crée une copie du fichier manifeste XML et l’ajoute au _ProjectName_\bin\Debug\OfficeAppManifests répertoire. L’application Office qui héberge votre complément consomme cette copie lorsque vous démarrez Visual Studio et déboguez le complément.

2. Crée un ensemble d’entrées de Registre sur votre ordinateur Windows qui permet au complément d’apparaître dans l’application Office.

3. Génère le projet d’application web, puis le déploie sur le serveur web IIS local (https://localhost).

4. S’il s’agit du premier projet de complément que vous avez déployé sur le serveur web IIS local, vous pouvez être invité à installer un certificat Self-Signed dans le magasin de certificats racines approuvés de l’utilisateur actuel. Cela est nécessaire pour qu’IIS Express puisse afficher correctement le contenu de votre complément.

Remarque

Si Office utilise le contrôle Edge Legacy Webview (EdgeHTML) pour exécuter des compléments sur votre ordinateur Windows, Visual Studio peut vous inviter à ajouter une exemption de bouclage de réseau local. Cela est nécessaire pour que le contrôle webview puisse accéder au site web déployé sur le serveur web IIS local. Vous pouvez également modifier ce paramètre à tout moment dans Visual Studio sous Outils>Options>Outils Office (web)>Débogage de compléments web. Pour savoir quel contrôle webview est utilisé sur votre ordinateur Windows, voir Navigateurs et contrôles d’affichage web utilisés par les compléments Office.

Visual Studio effectue ensuite les actions suivantes :

1. Modifie l’élément SourceLocation du fichier manifeste XML (qui a été copié dans le _ProjectName_\bin\Debug\OfficeAppManifests répertoire) en remplaçant le ~remoteAppUrl jeton par l’adresse complète de la page de démarrage (par exemple, https://localhost:44302/Home.html).

2. Il démarre le projet d’application web dans IIS Express.

3. Valide le manifeste.

   Importante

   Si vous recevez des erreurs de validation pour le manifeste, il se peut que les fichiers de schéma de manifeste de Visual Studio n’ont pas été mis à jour pour prendre en charge les dernières fonctionnalités. La première étape de résolution des problèmes doit consister à remplacer un ou plusieurs de ces fichiers par les dernières versions. Pour obtenir des instructions détaillées, consultez Erreurs de validation de schéma de manifeste dans les projets Visual Studio.

4. Ouvre l’application Office et charge une version test de votre complément.

Déboguer le complément

La meilleure méthode pour déboguer un complément dans Visual Studio 2022 varie selon que le complément s’exécute dans WebView2, qui est le contrôle webview associé à Microsoft Edge (Chromium) ou un contrôle d’affichage web plus ancien. Pour déterminer le contrôle webview utilisé, voir Navigateurs et contrôles webview utilisés par les compléments Office. Si votre ordinateur utilise WebView2, consultez Utiliser le débogueur Visual Studio intégré pour déboguer sur le bureau. Pour tout autre contrôle webview, consultez Utiliser les outils de développement du navigateur pour déboguer sur le bureau.

Utiliser le débogueur Visual Studio intégré pour déboguer sur le bureau

1. Définissez des points d’arrêt, selon les besoins, dans les fichiers JavaScript ou TypeScript sources. Vous pouvez le faire avant ou après le démarrage du complément, comme décrit dans la section précédente Démarrer le projet de complément. Si la définition d’un point d’arrêt entraîne l’arrêt du serveur IIS (Internet Information Services), redémarrez le débogage après avoir défini vos points d’arrêt.

2. Lorsque le complément est en cours d’exécution, utilisez l’interface utilisateur du complément pour exécuter le code qui contient vos points d’arrêt.

Importante

Les points d’arrêt définis dans Office.initialize ou Office.onReady ne sont pas atteints. Pour déboguer ces méthodes, consultez Déboguer les fonctions initialize et onReady.

Conseil

Si vous rencontrez des problèmes, vous trouverez plus d’informations dans Déboguer une application JavaScript ou TypeScript dans Visual Studio.

Utiliser les outils de développement du navigateur pour déboguer sur le bureau

1. Suivez les étapes de la section précédente Démarrer le projet de complément.

2. Lancez le complément dans l’application Office si elle n’est pas déjà ouverte. Par exemple, s’il s’agit d’un complément du volet Office, il aura ajouté un bouton au ruban Accueil (par exemple, un bouton Afficher le volet Des tâches ). Sélectionnez le bouton sur le ruban.

   Remarque

   Si votre complément n’est pas chargé de manière indépendante par Visual Studio, vous pouvez le charger manuellement. Suivez les instructions pour charger une version test d’un complément Office à des fins de test pour votre plateforme.

   Dans la liste des compléments disponibles, recherchez la section Compléments développeur et sélectionnez votre complément pour effectuer cette opération.

   Conseil

   Le volet Office peut apparaître vide lorsqu’il s’ouvre pour la première fois. Si c’est le cas, il doit s’afficher correctement lorsque vous lancez les outils de débogage dans une étape ultérieure.

3. Ouvrez le menu personnalité , puis choisissez Attacher un débogueur. Cette action ouvre les outils de débogage du contrôle webview qu’Office utilise pour exécuter des compléments sur votre ordinateur Windows. Vous pouvez définir des points d’arrêt et parcourir le code pas à pas comme décrit dans l’un des articles suivants :

   • Déboguer des compléments à l’aide des outils de développement pour Internet Explorer
   • Déboguer des compléments à l’aide des outils de développement pour la version héritée Edge
   • Déboguer des compléments à l’aide des Outils de développement dans Microsoft Edge (basés sur Chromium)

4. Pour apporter des modifications à votre code, commencez par arrêter la session de débogage dans Visual Studio et fermez l’application Office. Apportez vos modifications et démarrez une nouvelle session de débogage.

Déboguer un projet de complément dans Microsoft 365 sur le web

Cette section explique comment démarrer et déboguer un complément dans le bureau Office sur le Web, c’est-à-dire lorsque la propriété Action de démarrage du projet de complément est définie sur Microsoft Edge.

Démarrer le projet de complément sur le web

Démarrez le projet en choisissant Déboguer>Démarrer le débogage dans la barre de menus ou appuyez sur le bouton F5. Visual Studio génère automatiquement la solution et lance la page hôte d’application Office de votre location Microsoft 365.

Remarque

Lorsque vous déboguez un complément sur le web, vous pouvez obtenir une erreur AADSTS50011 semblable à la suivante :

« L’URI {Full absolute URL to add-in home page} de redirection spécifié dans la requête ne correspond pas aux URI de redirection configurés pour l’application ... "

Cela se produit parce que les nouvelles applications web déployées sur SharePoint peuvent prendre jusqu’à 24 heures pour être disponibles. Pour que votre complément soit immédiatement débogué, procédez comme suit :

1. Arrêtez le débogage dans Visual Studio.

2. Create un script PowerShell avec les lignes suivantes. Remplacez l’espace réservé {Full absolute URL to add-in home page} par l’URL de redirection dans le message d’erreur ; par exemple, « https://contoso-79d42f062409ae.sharepoint.com/_forms/default.aspx".

   Connect-MgGraph -Scopes Application.ReadWrite.All
   $sharepointPrincipal = Get-MgServiceprincipal -Filter "AppId eq '00000003-0000-0ff1-ce00-000000000000'"
   $sharepointPrincipal | fl
   $replyUrls = $sharepointPrincipal.ReplyUrls
   $replyUrls += "{Full absolute URL to add-in home page}"
   Update-MgServiceprincipal -ServicePrincipalId $sharepointPrincipal.Id -ReplyUrls $replyUrls
   

3. Exécutez le script dans PowerShell.

4. Redémarrez le projet en choisissant Déboguer>Démarrer le débogage dans la barre de menus ou appuyez sur le bouton F5.

Lorsque Visual Studio génère le projet, il effectue les tâches suivantes.

1. Vous invite à entrer les informations d’identification de connexion. Si vous êtes invité à vous connecter à plusieurs reprises ou si vous recevez une erreur indiquant que vous n’êtes pas autorisé, l’authentification de base peut être désactivée pour les comptes de votre locataire Microsoft 365. Dans ce cas, essayez d’utiliser un compte Microsoft à la place. Vous pouvez également essayer de définir la propriété Utiliser l’authentification multifacteur sur True dans le volet des propriétés du projet de complément. Consultez Propriétés du projet de complément.

2. Crée une copie du fichier manifeste XML et l’ajoute au _ProjectName_\bin\Debug\OfficeAppManifests répertoire. Microsoft 365 utilise cette copie lorsque vous démarrez Visual Studio et déboguez le complément.

3. Génère le projet d’application web, puis le déploie sur la location Microsoft 365.

Visual Studio effectue ensuite les actions suivantes :

1. Modifie l’élément SourceLocation du fichier manifeste XML (qui a été copié dans le _ProjectName_\bin\Debug\OfficeAppManifests répertoire) en remplaçant le ~remoteAppUrl jeton par l’adresse complète de la page de démarrage (par exemple, https://contoso-79d42f062409ae.sharepoint.com/_forms/default.aspx).

2. Démarre le projet d’application web.

3. Valide le manifeste.

   Importante

   Si vous recevez des erreurs de validation pour le manifeste, il se peut que les fichiers de schéma de manifeste de Visual Studio n’ont pas été mis à jour pour prendre en charge les dernières fonctionnalités. La première étape de résolution des problèmes doit consister à remplacer un ou plusieurs de ces fichiers par les dernières versions. Pour obtenir des instructions détaillées, consultez Erreurs de validation de schéma de manifeste dans les projets Visual Studio.

4. Ouvre la page hôte de l’application Office de votre location Microsoft 365 dans Microsoft Edge.

Déboguer le complément sur le web

La meilleure méthode pour déboguer un complément dans Visual Studio 2022 varie selon que le complément s’exécute dans WebView2, qui est le contrôle webview associé à Microsoft Edge (Chromium) ou un contrôle d’affichage web plus ancien. Pour déterminer le contrôle webview utilisé, voir Navigateurs et contrôles webview utilisés par les compléments Office. Si votre ordinateur utilise WebView2, consultez Utiliser le débogueur Visual Studio intégré pour déboguer sur le web. Pour tout autre contrôle webview, consultez Utiliser les outils de développement du navigateur pour déboguer sur le web.

Utiliser le débogueur Visual Studio intégré pour déboguer sur le web

1. Définissez des points d’arrêt, selon les besoins, dans les fichiers JavaScript ou TypeScript sources. Vous pouvez le faire avant ou après le démarrage du complément, comme décrit dans la section précédente Démarrer le projet de complément sur le web.

2. Lorsque le complément est en cours d’exécution, utilisez l’interface utilisateur du complément pour exécuter le code qui contient vos points d’arrêt.

Conseil

• Parfois, dans Outlook sur le web, le débogueur Visual Studio ne s’attache pas. Si vous recevez des erreurs par les points d’arrêt qui indiquent qu’ils ne seront pas atteints, utilisez les outils de développement du navigateur pour l’attacher au débogueur Visual Studio : après avoir appuyé sur F5 pour démarrer le débogage et que Outlook sur le web s’est ouvert, suivez les quatre premières étapes de l’article Utiliser les outils de développement du navigateur pour déboguer sur le web. (Suivez les instructions pour Microsoft Edge (basé sur Chromium).) Une fois que vous avez défini un point d’arrêt dans les outils du navigateur et qu’il a été atteint, l’exécution s’interrompt sur le point d’arrêt dans les outils de navigateur et dans Visual Studio. Cela indique que le débogueur Visual Studio est attaché. À ce stade, vous pouvez fermer les outils du navigateur et ajouter des points d’arrêt dans Visual Studio comme vous le feriez normalement.
• Si vous rencontrez des problèmes, vous trouverez plus d’informations dans Déboguer une application JavaScript ou TypeScript dans Visual Studio.

Utiliser les outils de développement du navigateur pour déboguer sur le web

1. Pour un complément dans n’importe quel hôte à l’exception d’Outlook, dans la page de l’application hôte Office, appuyez sur F12 pour ouvrir l’outil de débogage.

2. Pour un complément Outlook, si le manifeste du complément est configuré pour une surface de lecture, sélectionnez un message électronique ou un élément de rendez-vous pour l’ouvrir dans sa propre fenêtre. Si le complément est configuré uniquement pour une surface de composition, ouvrez un nouveau message, répondez à un message ou une nouvelle fenêtre de rendez-vous. Vérifiez que la fenêtre appropriée a le focus et appuyez sur F12 pour utiliser l’outil de débogage.

3. Une fois l’outil ouvert, lancez le complément. Les étapes exactes varient en fonction de la conception de votre complément. En règle générale, vous appuyez sur un bouton pour ouvrir un volet Office. Dans Outlook, dans la barre d’outils en haut de la fenêtre, sélectionnez le bouton Plus d’applications , puis sélectionnez votre complément dans la légende qui s’ouvre.

   

4. Suivez les instructions de l’un des articles suivants pour définir des points d’arrêt et parcourir le code. Ils ont chacun un lien vers des instructions plus détaillées.

   • Déboguer des compléments à l’aide des outils de développement pour la version héritée Edge
   • Déboguer des compléments à l’aide des Outils de développement dans Microsoft Edge (basés sur Chromium)

   Conseil

   Pour déboguer du code qui s’exécute dans la Office.initialize fonction ou une Office.onReady fonction qui s’exécute lorsque le complément s’ouvre, définissez vos points d’arrêt, puis fermez et rouvrez le complément. Pour plus d’informations sur ces fonctions, voir Initialiser votre complément Office.

5. Pour apporter des modifications à votre code, commencez par arrêter la session de débogage dans Visual Studio et fermez les pages Outlook. Apportez vos modifications et démarrez une nouvelle session de débogage.

Utiliser un document existant pour déboguer le complément

Si vous avez un document qui contient les données de test à utiliser pendant le débogage de votre complément Excel, PowerPoint ou Word, Visual Studio peut être configuré pour ouvrir ce dernier lorsque vous démarrez le projet. Pour spécifier un document existant à utiliser pour déboguer le complément, procédez comme suit.

1. Dans l’Explorateur de solutions, choisissez le projet de complément (pas le projet d’application web).

2. Dans la barre de menus, sélectionnez Project>ajouter un élément existant.

3. Dans la boîte de dialogue Ajouter un élément existant, recherchez et sélectionnez le document que vous souhaitez ajouter.

4. Choisissez le boutonAjouter pour ajouter le document à votre projet.

5. Dans l’Explorateur de solutions, choisissez le projet de complément (pas le projet d’application web).

6. Dans la barre de menu, choisissez Affichage>Fenêtre Propriétés.

7. Dans la fenêtrepropriétés, choisissez la listeDocument de démarrage et sélectionnez le document que vous avez ajouté au projet. Le projet est désormais configuré pour démarrer le complément dans ce document.

Étapes suivantes

Une fois que votre complément fonctionne comme vous le souhaitez, voir Déployer et publier votre complément Office pour en savoir plus sur les méthodes avec lesquelles vous pouvez distribuer le complément aux utilisateurs.