Débogage de flux de travail SharePoint

Montre comment SharePoint utilise désormais Workflow Manager 1.0 pour l’ensemble du traitement et de la gestion des flux de travail, et illustre les options de débogage.

Fourni par : Andrew Connell, Voitanos

Notes

Les flux de travail SharePoint 2010 ont été retirés depuis le 1er août 2020 pour les nouveaux locataires et retirés des locataires existants le 1er novembre 2020. Si vous utilisez des flux de travail SharePoint 2010, nous vous recommandons de migrer vers Power Automate ou d'autres solutions prises en charge. Pour plus d'informations, voir la retraite du flux de travail SharePoint 2010.

L'équipe chargée du flux de travail a travaillé avec l'équipe Azure pour créer un produit appelé Gestionnaire de flux de travail. Le Gestionnaire de flux de travail héberge la dernière version du service runtime Windows Workflow Foundation et tous les services nécessaires dans un sens disponible et évolutif. Il tire parti du bus des services Microsoft Azure pour les performances et l’évolutivité, et lorsqu’il est déployé, il s’exécute exactement de la même manière dans un déploiement local que dans le cloud, à l'instar d'Office 365. SharePoint est ensuite connecté et configuré pour transmettre l’exécution du flux de travail et les tâches associées à la batterie de serveurs de Gestionnaire de flux de travail.

Cette modification de l’architecture exigeait quelques modifications apportées aux deux principaux outils de création de flux de travail (SharePoint Designer 2013 et Visual Studio 2012) qui ont été utilisés pour créer des flux de travail personnalisés. Toutefois, les techniques de débogage utilisées par les développeurs dans SharePoint 2007 et SharePoint 2010 s’appliquent encore. La nouvelle architecture permet d’utiliser une nouvelle option pour les flux de travail créés à l’aide de SharePoint Designer 2013 ou de Visual Studio 2012, tandis que Fiddler permet de contrôler le trafic entre SharePoint et Gestionnaire de flux de travail.

Vue d’ensemble du débogage de flux de travail SharePoint

Le débogage de flux de travail personnalisés créés pour SharePoint est semblable aux versions précédentes, notamment SharePoint 2010 et SharePoint 2007. Certaines options de débogage disponibles dépendent de l’outil utilisé pour créer le flux de travail (SharePoint Designer 2013 ou Visual Studio 2012) et le type de déploiement SharePoint (par exemple, local ou Office 365). Quatre techniques de débogage de flux de travail peuvent être exploitées par les auteurs de flux de travail :

  • Journalisation dans la liste historique du flux de travail
  • Définition de points d’arrêt
  • Envoyer des messages de débogage sur la console
  • Surveillance du trafic entre SharePoint et Gestionnaire de flux de travail avec Fiddler

Chaque option présente des avantages et des inconvénients. Il est utile de comprendre ce que vous pouvez faire en utilisant les deux outils de création de flux de travail (SharePoint Designer 2013 ou Visual Studio 2012), ainsi que le type de déploiement de flux de travail (local ou Office 365). Le tableau suivant contient une matrice des outils de création, des objectifs de déploiement et des options disponibles dans chaque scénario.

Produit SharePoint local Office 365 SharePoint Online
SharePoint Designer 2013, SharePoint Online Consigner dans l’historique Fiddler Consigner dans l’historique
Visual Studio 2012 Consigner dans l’historique les messages Fiddler de débogage de la console des points d’arrêt Consigner dans les points d’arrêt de l’historique

Débogage avec la liste historique du flux de travail

La seule option de débogage disponible dans tous les types de déploiements SharePoint écrit les messages de journal dans la liste historique du flux de travail. À l'aide de cette méthode, vous pouvez utiliser soit l'action Consigner dans l’historique dans SharePoint Designer 2013, soit l'activité WriteToHistory dans Visual Studio 2012 pour écrire un message de chaîne sous forme de nouvel élément dans la liste, spécifié dans l'association de flux de travail, qui est le conteneur de tous les messages de consignation de l'historique. Il peut s’agir de chaînes simples ou de la concaténation du contenu de variables dans le flux de travail.

Il n’est pas recommandé d’utiliser la liste d’historique comme outil de débogage, car les utilisateurs peuvent voir les messages. Par conséquent, lorsque la session de débogage est terminée et que le flux de travail est utilisé dans la production, le développeur de flux de travail souhaite supprimer ces messages et créer une étape supplémentaire entre le débogage et le déploiement. Néanmoins, il s’agit de la seule option disponible dans tout scénario, quel que soit l’outil utilisé pour créer le flux de travail ou le type de déploiement SharePoint.

Débogage à l’aide des points d’arrêt de Visual Studio 2012

Une autre option de débogage consiste à tirer parti des points d’arrêt. Les points d’arrêt ne sont disponibles que pour les flux de travail créés à l’aide de Visual Studio 2012, car SharePoint Designer 2013 ne peut pas créer de points d’arrêt ou joindre un débogueur au processus en cours d’exécution. Celles-ci sont disponibles dans les déploiements SharePoint locaux et hébergés tels qu’Office 365. Dans ce scénario, vous devez créer un point d’arrêt sur une activité dans le flux de travail, puis démarrer le flux de travail en mode débogage.

Figure 1. Démarrer le flux de travail

Figure 1. Démarrage du flux de travail

Visual Studio déploiera le flux de travail dans l’environnement SharePoint cible et attachera un débogueur. Lorsque le processus de workflow atteint l’activité sur laquelle le point d’arrêt est défini, Visual Studio récupère le focus et vous permet d’examiner les valeurs des variables de workflow et de parcourir chaque activité à partir de Visual Studio 2012, comme illustré dans la figure suivante.

Figure 2. Point d’arrêt de flux de travail

Figure 2. Point d’arrêt de flux de travail

Débogage de flux de travail à l’aide de messages de débogage et de l’hôte de service de test

L’introduction du Gestionnaire de flux de travail dans le flux de travail SharePoint présente deux nouvelles opportunités de débogage disponibles lorsque vous créez des flux de travail personnalisés à l’aide de Visual Studio 2012 et testez-les dans un déploiement local. Visual Studio 2012 inclut une activité WriteLine qui accepte un message basé sur une chaîne unique comme entrée.

Figure 3. Activité WriteLine

Figure 3. Activité WriteLine

Cette activité écrit le message semblable à la méthode System.Diagnostics.Debug.WriteLine() dans une application .NET standard de la console Windows. L’outil de développement de Workflow Manager 1.0 inclut un utilitaire de console appelé Hôte de service de test que Visual Studio 2012 s’ouvre lorsqu’une nouvelle session de débogage est démarrée et que vous testez avec un déploiement SharePoint local. Cet utilitaire de la console, Microsoft.Workflow.TestServiceHost.exe se trouve dans C:\Program Files (x86)\Outils de gestionnaire de flux de travail\1.0, est joint à l’instance de gestionnaire de flux de travail inscrit et écoute les messages rédigés à l’aide de l’activité WriteLine, comme illustré dans la figure suivante.

Figure 4. Messages pour l’activité WriteLine

Figure 4. Messages pour l’activité WriteLine

Ces messages s’apparentent aux commentaires de code ou aux messages de débogage dans une application console. Contrairement à l’écriture dans la liste historique du flux de travail, vous n’avez pas besoin de les supprimer avant de déployer le flux de travail en production. Sauf si l’utilitaire Hôte de service de test est connecté au Gestionnaire de flux de travail, les messages sont inoffensifs.

Cette option de débogage n’est pas disponible pour les flux de travail créés à l’aide de SharePoint Designer 2013, car aucune action n’est mappée à l’activité WriteLine. Malheureusement, cette option de débogage est disponible uniquement pour les installations SharePoint locales, car le port utilisé par l’utilitaire de l’hôte de service de test n’est généralement pas accessible publiquement en dehors d’un réseau local. Cela s’applique également à Office 365. Les ports que SharePoint utilise pour se connecter au Gestionnaire de flux de travail sont les mêmes que ceux utilisés par l’hôte de service de test, et ceux-ci sont accessibles uniquement dans le réseau approuvé. Toutefois, cela ne signifie pas que vous devez modifier leurs flux de travail pour supprimer les activités WriteLine avant de procéder au déploiement vers Office 365. Ces activités peuvent être laissées dans le flux de travail, car elles ne sont pas visibles, sauf si l’Hôte de service de test est connecté au Gestionnaire de flux de travail.

Débogage à l’aide de Fiddler pour analyser le trafic HTTP

La dernière option de débogage pour les flux de travail SharePoint est un nouvel ajout pour les développeurs de flux de travail en raison de la modification de la façon dont les flux de travail sont gérés dans la plateforme actuelle. Rappelez-vous que, dans SharePoint, le traitement du flux de travail est transmis à un produit externe, Workflow Manager 1.0. Lorsqu’un flux de travail doit communiquer avec SharePoint, par exemple, la mise à jour de l’état actuel du flux de travail, la collecte de données à partir d’éléments ou d’utilisateurs dans un site SharePoint, ou lorsque vous travaillez avec des tâches, les activités du Gestionnaire de flux de travail exploitent l’API REST SharePoint pour effectuer ces opérations. SharePoint communique avec le Gestionnaire de flux de travail à l’aide d’une bibliothèque cliente qui sert de proxy pour les services REST exposés par le Gestionnaire de flux de travail. SharePoint et le Gestionnaire de flux de travail communiquent entre eux à l’aide des protocoles HTTP et HTTPS standard.

Cette architecture génère une nouvelle option de débogage pour les auteurs de flux de travail. L’outil proxy de débogage HTTP Fiddler vous permet de contrôler chaque demande et la réponse correspondante entre les deux produits. De plus, les services personnalisés appelés par les flux de travail personnalisés à l’aide de l'activité HttpSend dans Visual Studio 2012 ou l’action Appeler le service web HTTP correspondant dans SharePoint Designer 2013 peut également être surveillé et inspecté par Fiddler. Ce modèle de débogage est également disponible, quel que soit l’outil utilisé pour créer des flux de travail personnalisés (SharePoint Designer 2013 ou Visual Studio 2012).

Cette option n’est pas disponible lorsque vous testez des flux de travail à l’aide d’un déploiement Office 365 de SharePoint. Dans la mesure où tout le trafic entre SharePoint et Workflow Manager se produit, il n’est pas possible de se connecter à l’un des serveurs dans Office 365 et de démarrer Fiddler à partir de la console.

Cette nouvelle option offre une transparence et une vue d’ensemble du moteur de flux de travail qui n’était pas possible lors du développement de flux de travail dans les versions précédentes de SharePoint avant SharePoint.

Par exemple, vous pouvez voir les réponses brutes provenant du Gestionnaire de flux de travail ou de SharePoint dans un appel de service web. Il peut arriver que le gestionnaire de flux de travail réponde avec un message d’erreur spécifique. SharePoint inclut des messages d'erreur conviviaux, mais ceux-ci peuvent ne pas être suffisamment spécifiques. À l’aide de Fiddler, vous pouvez voir le message d’erreur exact renvoyé pour résoudre le problème.

Un autre cas d’utilisation consiste à examiner la réponse d’un appel de service web réussi. Lorsque vous utilisez des services web dans les flux de travail, quel que soit l’outil de création, vous devez connaître le nom exact de la propriété (et le chemin d’accès s’il s’agit d’une réponse complexe) pour une valeur contenue dans une réponse. L’utilisation de Fiddler vous permet de consulter les données de réponse complètes.

Présentation de SharePoint et du Gestionnaire de flux de travail pour le débogage avec Fiddler

Pour déboguer des flux de travail dans SharePoint et Workflow Manager 1.0 avec Fiddler, certaines étapes de configuration et d'installation doivent être effectuées dans un environnement de développement avant de procéder au débogage. Avant d’effectuer cette procédure, il est utile de comprendre le fonctionnement de Fiddler et le fonctionnement des flux de travail dans SharePoint.

Fiddler ne peut inspecter que le trafic sur le serveur local

Le seul trafic de la requête Fiddler peut intercepter et inspecter les requêtes provenant du serveur local sur lequel Fiddler a commencé. Cela peut présenter un défi lorsque Fiddler est utilisé comme outil de débogage pour les flux de travail SharePoint.

Si SharePoint et Workflow Manager 1.0 sont installés sur différents serveurs et si Fiddler est démarré à partir de SharePoint Server, le seul trafic affiché par Fiddler est le trafic où la requête provient de SharePoint. Aucun trafic provenant de Workflow Manager 1.0, même si celui-ci est ciblé sur le serveur SharePoint, n’est intercepté.

Par conséquent, lorsque vous développez des flux de travail, il est plus facile de les déboguer si SharePoint et Workflow Manager 1.0 sont installés sur le même serveur. Notez qu’il ne s’agit pas d’une obligation, vous pouvez démarrer Fiddler sur les serveurs SharePoint Server et Workflow Manager, bien qu’il soit plus complexe d’analyser deux instances sur deux serveurs pour le même processus de flux de travail.

Fiddler ne peut inspecter que le trafic de l'utilisateur actuellement connecté

Fiddler peut uniquement intercepter et inspecter le trafic provenant de l’utilisateur actuellement connecté. Pour afficher le trafic provenant de SharePoint, vous devez vous connecter à SharePoint Server à l’aide du compte Windows configuré comme identité du pool d’applications qui héberge l’application web pour le site SharePoint qui lance le flux de travail.

Il en va de même pour workflow Manager. Pour intercepter et inspecter le trafic provenant du Gestionnaire de flux de travail, vous devez vous connecter au serveur à l’aide de l’identité Windows configurée lors de l’approvisionnement de la batterie de serveurs Workflow Manager en tant que compte de service du Gestionnaire de flux de travail.

Lorsque vous utilisez Fiddler pour déboguer des flux de travail, il est plus facile de les déboguer si non seulement workflow Manager et SharePoint sont installés et configurés sur le même serveur, mais qu’ils utilisent également la même identité Windows que le compte de service. Tout le trafic provenant du Gestionnaire de flux de travail et de SharePoint peut ensuite être intercepté et inspecté par Fiddler.

SharePoint doit approuver le certificat de Fiddler

Avant d’utiliser Fiddler pour le débogage de flux de travail SharePoint, vous devez comprendre la manière dont le trafic chiffré est géré. Le trafic chiffré sur HTTP, connu sous le nom de HTTPS, est implémenté à l’aide de la clé privée d’un certificat pour chiffrer des données, puis l’envoyer à un autre destinataire. Le destinataire dispose de la clé publique du certificat qui est couplée avec la clé privée. Lorsqu’une demande est reçue par le destinataire, le destinataire peut vérifier que la demande provient de l’expéditeur, car la signature du contenu chiffré correspond à la clé publique, qui ne peut être vraie que si elle a été chiffrée avec la clé privée du certificat.

Fiddler peut intercepter le trafic HTTPS et être configuré pour le déchiffrer afin qu'il soit dans un format lisible par l'homme pour l'inspection dans l'outil. Une fois la demande affichée, Fiddler utilise son propre certificat pour re-chiffrer le trafic et l’envoyer au destinataire. Cela peut toutefois être à l’origine du problème, car à présent, le destinataire a reçu la réponse d’origine, mais elle n’est pas sécurisée à l’aide du certificat de l’expéditeur d’origine. Il peut s’agir d’un problème lors du débogage de flux de travail SharePoint, car le certificat de Fiddler n’est pas approuvé par SharePoint. Par conséquent, afin d'utiliser Fiddler pour intercepter et inspecter le trafic HTTPS entre SharePoint et le Gestionnaire de flux de travail, le certificat de Fiddler doit être approuvé par SharePoint.

Configurer SharePoint et Workflow Manager 1.0 pour le débogage de flux de travail avec Fiddler

Les sections suivantes expliquent comment configurer Fiddler et SharePoint pour le débogage de flux de travail.

Configurer la configuration du proxy par défaut .NET Framework

La première étape consiste à définir la configuration du proxy par défaut pour .NET Framework. Ces modifications permettront à Fiddler d’intercepter le trafic provenant de SharePoint et du Gestionnaire de flux de travail. Ouvrez le fichier machine.config dans les deux emplacements suivants :

  • %systemdrive%\\Windows\\Microsoft.NET\\Framework\\v4.0.30319\\Config\\machine.config
  • %systemdrive%\\Windows\\Microsoft.NET\\Framework64\\v4.0.30319\\Config\\machine.config

Ajoutez ensuite la balise suivante en bas de chaque fichier, juste avant l’élément de fermeture :

<system.net>
  <defaultProxy enabled="true">
    <proxy bypassonlocal="false" usesystemdefault="true" />
  </defaultProxy>
</system.net>

Enregistrez les modifications et fermez les fichiers.

Configurer Fiddler pour intercepter et inspecter le trafic HTTPS

L’étape suivante consiste à configurer Fiddler pour intercepter le trafic chiffré et le déchiffrer pour la configuration.

  1. Démarrer Fiddler.
  2. Si vous utilisez le fichier HOSTS local, assurez-vous que les entrées sont incluses dans Fiddler en sélectionnant l’option de menu Outils-> HOSTS.
  3. Cochez la case Activez le remappage des requêtes d'un hôte vers un autre hôte ou une autre adresse IP, en remplaçant le DNS,
  4. Cliquez sur Importer le fichier hosts de Windows, puis cliquez sur le bouton Enregistrer.
Figure 5. Remappage d’hôte

Figure 5. Interface utilisateur permettant d’utiliser le fichier HOSTS local

Ensuite, configurez les options de connexion de Fiddler.

  1. Sélectionnez l’option de menu Outils-> Options Fiddler.

  2. Cliquez sur l'onglet Connexions.

  3. Effacez la sélection Chaîner au proxy de passerelle en amont.

  4. Sélectionnez le options Agir en tant que proxy système au démarrage et Contrôler toutes les connexions, comme illustré dans la figure suivante.

    Figure 6. Options de connexion de Fiddler

  5. Sélectionnez l’onglet HTTPS dans la boîte de dialogue Options Fiddler.

  6. Cochez la case Capturer les connexions HTTPS.

  7. Sélectionnez Déchiffrer le trafic HTTPS.

  8. Sélectionnez ???à partir de tous les processus.

  9. Cochez Ignorer les erreurs de certificat de serveur.

  10. Cliquez sur le bouton Exporter le certificat racine vers le bureau.

  11. Lorsque vous y êtes invité, cliquez sur Oui pour Approuver le certificat racine Fiddler.

Ce processus permet de configurer Windows de manière à ce qu’il approuve le certificat, même si SharePoint ne l’approuve pas pour le moment.

Figure 7. Onglet HTTPS

Figure 7. Onglet HTTPS

Notes

Si un avertissement de sécurité s’affiche avec un message indiquant de ne pas approuver le certificat Fiddler, cliquez sur Oui pour continuer à installer le certificat.

Configuration de SharePoint pour l’approbation du certificat

La dernière étape consiste à configurer SharePoint de sorte qu’il approuve le certificat Fiddler exporté au cours de l’étape précédente.

  1. Connectez-vous en tant qu’un administrateur de batterie de serveurs SharePoint.

  2. Démarrez SharePoint Management Shell.

  3. Chargez le composant logiciel enfichable SharePoint.

    Add-PSSnapIn Microsoft.SharePoint.PowerShell
    
  4. Utilisez l’utilitaire de certificat pour installer le certificat Fiddler.

    $fidderCertificatePath = [full path to exported FiddlerRoot.cer certificate file]
    certutil.exe -addstore -enterprise -f -v root $fidderCertificatePath
    $fiddlerCertificate = Get-PfxCertificate -FilePath $fidderCertificatePath
    New-SPTrustedRootAuthority -Name "Fiddler" -Certificate $fiddlerCertificate
    
  5. Exécutez IISRESET pour vous assurer que SharePoint récupère la modification de confiance de certificat.

Procédure pas à pas : débogage d’un flux de travail SharePoint avec Fiddler

Cette procédure pas à pas montre comment utiliser Fiddler pour déboguer un flux de travail SharePoint créé à l’aide de Visual Studio 2012. Lorsque le flux de travail démarre, il récupère un ID client à partir d’un champ dans une liste personnalisée. Cet ID de client est utilisé pour interroger un service accessible par le public et récupérer des détails supplémentaires sur le client. Il utilise ensuite ces valeurs pour mettre à jour l'élément original de la liste. Le flux de travail peut être trouvé dans l'exemple de code MSDN suivant : Flux de travail SharePoint : Appeler un service web externe.

Les conditions suivantes doivent être préalablement remplies pour la procédure pas à pas :

  • SharePoint et Workflow Manager 1.0 sont installés sur le même serveur.

  • L’identité Windows CONTOSO\SP_Content est configurée pour l’identité du pool d’applications qui héberge l’application web qui dessert le site SharePoint qui démarre le flux de travail.

  • Le site SharePoint utilisé pour démarrer le flux de travail est http://intranet.contoso.com

  • Le point de terminaison de la batterie de serveurs Workflow Manager 1.0 est w15sp.contoso.com.

  • SharePoint et Workflow Manager 1.0 sont configurés pour autoriser l’option OAuth sur HTTP.

    Attention

    Cela ne doit jamais être effectué sur le serveur de production, mais uniquement pour les tests et le débogage.

  1. Connectez-vous au serveur sur lequel le Gestionnaire de flux de travail et SharePoint sont installés avec l’identité Windows configurée en tant que compte de la batterie de serveurs Workflow Manager 1.0 et identité du pool d’applications SharePoint.

  2. Démarrer Fiddler. Bien que Fiddler intercepte le trafic de l’utilisateur actuel, si des connexions ou processus existants sont en cours d’exécution, Fiddler peut les manquer, car il n’était pas en cours d’exécution lorsque les connexions ont été établies pour la première fois. Pour forcer à ce que le Gestionnaire de flux de travail et SharePoint Server se recyclent et que leur trafic soit intercepté par Fiddler, vous pouvez recycler SharePoint en exécutant un IISRESET et recycler le gestionnaire de flux de travail en arrêtant et en redémarrant le service Windows Gestionnaire de flux de travail Backend. Pour ce faire, vous pouvez utiliser les deux commandes suivantes dans une invite de commandes d’administration.

    IISRESET
    net stop WorkflowServiceBackend
    net start WorkflowServiceBackend
    
  3. Démarrer le flux de travail.

Dans la figure ci-dessous, notez que les sessions n° 18 à 36 proviennent de SharePoint et de sessions n°37 à 43 provenant du Gestionnaire de flux de travail.

Figure 8. Démarrage du flux de travail

Figure 8. Démarrage du flux de travail

Notez que, dans la session n° 36, SharePoint demande que le Gestionnaire de flux de travail démarre un flux de travail (indiqué comme [A] dans la figure) et que le Gestionnaire de flux de travail réponde (indiquée comme [B] dans la figure) avec un message de « Réussite » :

Figure 9. Réponse à un message de réussite

Figure 10. Message de réussite

Session n° 40 est l’endroit où Gestionnaire de flux de travail récupère les ID d’élément de liste et GUID de SharePoint.

Figure 10. Récupération de l’ID d’élément et du GUID

Figure 10. Récupération de l’ID et du GUID d’élément de liste

La session n° 43 est l’endroit où le Gestionnaire de flux de travail met à jour l’élément de liste dans SharePoint avec une nouvelle valeur pour le champ Corps de l’élément de l’annonce en transmettant un objet JSON (JavaScript Object Notation) (indiqué comme [A] dans la figure), ainsi que la charge utile. SharePoint répond par l’état HTTP de 204, ce qui indique qu’il a traité la demande avec succès, mais qu’il n’y a pas de message dans la réponse.

Figure 11. Mise à jour de l’élément de liste

Figure 11. Mise à jour de l’élément de liste dans SharePoint

Conclusion

Le scénario de flux de travail dans la version SharePoint a mis en place une nouvelle couche d’abstraction, Workflow Manager 1.0. Cette nouvelle architecture a modifié la manière dont les flux de travail sont traités. SharePoint utilise désormais sur Workflow Manager 1.0 pour l’ensemble du traitement et de la Gestion des flux de travail.

L’une des tâches que vous devez effectuer lors de la création d’applications et de processus commerciaux personnalisés dans les flux de travail consiste à déboguer votre travail. La nouvelle architecture de flux de travail de SharePoint offre les mêmes options de débogage que celles qui existaient dans les versions précédentes de SharePoint. Toutefois, la nouvelle architecture offre deux nouvelles options pour créer des flux de travail personnalisés à l’aide de la nouvelle architecture. Cet article décrit les options de débogage existantes ainsi que les nouvelles options de l’activité WriteLine et l’utilisation de Fiddler pour l’interception et l’inspection du trafic entre SharePoint et Workflow Manager 1.0.

Voir aussi