Implémenter le débogage d’instantané
Un scénario de support courant pour les consultants consiste à être contacté par un client ayant un problème dans une solution, qui doit être résolu afin de déterminer sa cause et son emplacement dans le code.
Il existe un support pour la création de bacs à sable avec une copie des données de production ainsi qu’un flux de programme de débogage/arrêt sans impact sur l’abonné de production d’un client. Toutefois, dans certains cas, le client est bloqué et le consultant se retrouve sous pression pour examiner et résoudre le problème sans avoir le temps nécessaire pour approvisionner un environnement dupliqué afin d’y reproduire le problème.
Pour résoudre ce problème, Microsoft a introduit la possibilité d’associer le débogueur AL de Visual Studio Code à un abonné de production afin de prendre des instantanés de l’exécution du code, garantissant une enquête rapide et une collaboration optimale avec le client sur les étapes de reproduction exactes.
Grâce à la nouvelle fonctionnalité d’instantané, vous pouvez effectuer les actions suivantes :
Définir des snappoints dans le code.
Créer une configuration d’association d’instantanés. Il peut s’agir d’un client web, d’une API web ou d’une session en arrière-plan (en spécifiant l’ID utilisateur ou l’ID de session, aucune interface utilisateur de sélection à l’heure actuelle).
Associer à un environnement en mode instantané.
Effectuer des étapes de reproduction pour déclencher des snappoints.
Télécharger un snappoint dans Visual Studio Code après avoir terminé la reproduction.
Inspecter le rapport des appels de procédure/l’exécution du programme et les variables au niveau des snappoints en mode hors connexion dans Visual Studio Code.
Le débogage d’instantané permet à un administrateur délégué d’enregistrer le code AL qui s’exécute sur le serveur et, une fois qu’il a été exécuté, de déboguer l’instantané enregistré dans Visual Studio Code. Pour qu’un administrateur délégué puisse créer et télécharger un fichier d’instantané qui existe sur le serveur au nom d’un utilisateur final, il doit faire partie du groupe d’autorisations Débogage d’instantané D365.
L’un des avantages du débogage d’instantané est qu’il offre la possibilité d’inspecter l’exécution du code et les variables dans l’environnement de production au sein d’un service cloud, sur une session utilisateur spécifiée.
Le débogage d’instantané introduit le concept de snappoints. Un snappoint est un point d’arrêt dans Visual Studio Code qui est défini lors de la création d’un instantané. Toutefois, il n’arrête pas l’exécution du code comme lors d’un débogage normal. Les snappoints demandent à l’exécution de consigner l’état au niveau du point d’arrêt pour une inspection hors connexion ultérieure.
Le débogage d’instantané enregistre le code AL lors de son exécution sur le serveur, mais ne collecte que des informations de variables sur :
les snappoints,
les exceptions AL.
Initialiser une session de débogage d’instantané
Depuis Visual Studio Code, vous démarrez un instantané en créant un fichier de configuration d’instantané.
Il existe deux configurations de modèles pour un instantané, accèssibles en sélectionnant Ajouter une configuration dans Visual Studio Code.
AL : initialiser une session de débogage d’instantané localement
AL : initialiser une session de débogage d’instantané sur le cloud
Choisissez si vous souhaitez exécuter la session sur un service cloud ou localement.
Le fichier config doit contenir les informations suivantes :
ID utilisateur : le GUID de l’utilisateur au nom duquel sera lancé un débogage d’instantané. Pour les exécutions locales, il peut également s’agir du nom d’utilisateur dans les scénarios d’authentification par mot de passe utilisateur. L’utilisateur doit pouvoir démarrer ou avoir ouvert un type de session spécifié dans le paramètre breakOnNext.
ID de session : identifiant de session pour l’utilisateur spécifié ci-dessus dans ID utilisateur.
Commentaires d’instantané : détermine la quantité de contexte d’exécution à enregistrer. Si SnapPoint est spécifié, seules les méthodes qui atteignent un snappoint sont enregistrées.
Lorsqu’une configuration est définie, une session de débogage d’instantané peut être initialisée en appuyant sur Ctrl + Maj + P, puis en sélectionnant AL: Initialize Snapshot Debugging ou en appuyant sur F7.
Pour enregistrer l’exécution AL, le serveur attend à présent qu’une connexion se produise où les règles suivantes s’appliquent :
Si un ID de session est spécifié pour un ID utilisateur pour un abonné donné, cette session fait l’objet d’un débogage d’instantané.
Si seul un ID utilisateur est spécifié pour un abonné donné, la session suivante spécifiée dans le paramètre de configuration breakOnNext fait l’objet d’un débogage d’instantané.
Si aucun ID utilisateur n’est spécifié, la session suivante sur un abonné donné qui valide le paramètre breakOnNext fait l’objet d’un débogage d’instantané.
Une fois qu’une session de débogage d’instantané est initialisée, le compteur de sessions de débogage d’instantané sur la barre d’état est mis à jour et ressemble à ceci :
Statut d’une session de débogage d’instantané
Un clic sur l’icône de la barre d’état ou un appui sur Maj + F7 entraîne l’affichage d’une liste de tous les instantanés disponibles.
La liste des statuts affiche l’état d’une session de débogage d’instantané. Une session de débogage d’instantané peut être associée à l’un des statuts suivants :
Initialisé : une requête est émise et le serveur attend que la session suivante fasse l’objet d’un débogage d’instantané en fonction des règles ci-dessus.
Démarré : vous vous êtes connecté à une session d’utilisateur final pour procéder à un débogage d’instantané.
Terminé : lorsque la session de débogage d’instantané est terminée.
Téléchargé : lorsque le fichier d’instantané est téléchargé.
Terminer une session de débogage d’instantané
Pour terminer une session de débogage d’instantané, appuyez sur Alt + F7. Toutes les sessions d’instantanés démarrées s’affichent alors. En choisir une entraîne la fermeture de la session de débogage sur le serveur et le téléchargement du fichier d’instantané.
Le fichier d’instantané peut contenir des données de confidentialité du client. Il doit de ce fait être traité conformément aux exigences en matière de confidentialité et doit être supprimé lorsqu’il n’est plus nécessaire.
Les sessions de débogage d’instantané qui ont produit un fichier d’instantané peuvent être déboguées. L’emplacement d’un fichier d’instantané est contrôlé par le paramètre de configuration al.snapshotOutputPath. Par défaut, il est local à l’espace de travail actuel et s’appelle ./.snapshots.
Télécharger des symboles sur le point de terminaison du débogueur d’instantané
Pour télécharger des symboles sur un serveur de production, vous avez besoin des entrées liées aux autorisations suivantes :
Être un administrateur délégué
L’accès en lecture seule à la table des applications publiées mise en évidence dans l’ensemble d’autorisations GESTION DES EXTENSIONS D365 doit également être accordé.
Le débogage nécessite que les symboles sur le serveur correspondent aux symboles que l’utilisateur possède localement. Si ce n’est pas le cas et que vous définissez un point d’arrêt sur une ligne donnée dans Visual Studio Code, la ligne de code peut différer de ce qui se trouve sur le serveur.
Le téléchargement des symboles utilise les paramètres de configuration de débogage snapshotInitialize dans Visual Studio Code, configurés lorsque vous choisissez AL: Initialize a snapshot debugging session locally ou AL: Initialize a snapshot debugging session on cloud.
{
"name": "snapshotInitialize: MyServer",
"type": "al",
"request": "snapshotInitialize",
"environmentType": "OnPrem",
"server": "http://localhost",
"serverInstance": "BC170",
"authentication": "UserPassword",
"breakOnNext": "WebClient"
},
Le débogage nécessite que les symboles sur le serveur correspondent aux symboles que l’utilisateur possède localement. Si ce n’est pas le cas et que vous définissez un point d’arrêt sur une ligne donnée dans Visual Studio Code, la ligne de code peut différer de ce qui se trouve sur le serveur. C’est pourquoi vous devez télécharger des symboles à partir des serveurs de production pour le débogage d’instantané afin qu’un point d’arrêt défini sur une ligne corresponde à ce que le serveur comprend de cette ligne. Cela permet d’éviter tout scénario dans lequel vous définissez un point d’arrêt dans un fichier DAL en ligne 12, mais la ligne 12 sur le serveur est une ligne vide ou différente si les symboles ne sont pas les mêmes.
Débogage d’un fichier d’instantané
Deux actions utilisateur démarrent le débogage d’instantané.
En créant une configuration de débogage de lancement et en spécifiant le nom du fichier d’instantané dans le paramètre de configuration snapshotFileName. Il s’agit du seul paramètre nécessaire en sus du type, de la requête et du nom.
En cliquant sur l’icône du statut ou en appuyant sur Maj + F7 et en sélectionnant une session de débogage d’instantané terminée.
Une fois qu’une session de débogage d’instantané démarre dans Visual Studio Code, l’exécution du code s’arrête au premier snappoint. Les exceptions AL sont traitées comme des snappoints, à la seule différence qu’elles ne peuvent pas être supprimées par les actions de l’utilisateur. Les autres snappoints sont des points d’arrêt réguliers qui peuvent être supprimés ou rajoutés par les actions de l’utilisateur. Si aucun snappoint n’est spécifié dans les premières méthodes enregistrées, la première ligne est le point d’arrêt d’entrée.
L’utilisateur peut définir des points d’arrêt et continuer l’exécution jusqu’à ce point d’arrêt à des fins de test si, par exemple, une ligne est atteinte, mais que le snappoint comporte les informations réelles.
Le profileur AL
Grâce au profileur AL pour l’extension AL Language, vous pouvez capturer un profil de performance du code exécuté pour un instantané. Grâce à la vue de l’éditeur de profilage des performances dans Visual Studio Code, vous pouvez étudier le temps consacré à l’exécution à l’aide des vues de pile d’appels descendantes et ascendantes. Le profileur AL fonctionne sur un instantané du code d’exécution.
Pour effectuer le profilage sur le code, vous devez d’abord capturer un instantané du code d’exécution. La configuration de l’instantané a un paramètre nommé executionContext dont les valeurs possibles sont les suivantes. Si rien n’est spécifié, la configuration est DebugAndProfile par défaut.
Debug : la session d’instantané ne recueille aucune information de profil.
Profile : la session d’instantané recueille uniquement les informations de profil, les snappoints sont ignorés et le débogage ne fonctionne pas.
DebugAndProfile : le débogage et le profilage sont disponibles à la suite d’une session d’instantané. Encore une fois, il s’agit du paramètre par défaut.
Autrement dit, si nous souhaitons utiliser l’instantané à la fois à des fins de débogage et de profilage, la configuration de l’instantané dans le fichier launch.json doit ressembler à ce qui suit :
"configurations": [
{
"name": "snapshotInitialize: Your own server",
"type": "al",
"userId": "555",
"request": "snapshotInitialize",
"environmentType": "OnPrem",
"server": "http://localserver",
"serverInstance": "BC190",
"authentication": "Windows",
"breakOnNext": "WebClient",
"executionContext": "DebugAndProfile"
},
...
Ensuite, lorsque le fichier d’instantané est téléchargé, vous pouvez générer un fichier de profil. Cette opération peut être effectuée de l’une des deux manières suivantes :
Ouvrez la palette de commandes à l’aide du raccourci Ctrl+Maj+P, puis sélectionnez la commande AL: Generate profile file et choisissez un instantané dans le menu déroulant.
Dans l’Explorateur de Visual Studio Code, cliquez avec le bouton droit sur le fichier d’instantané spécifique et choisissez Générer un fichier de profil.
Pour étudier le graphique des appels de méthode, ouvrez le fichier de profil généré dans l’éditeur de profilage des performances. Si vous cliquez directement sur le fichier, il s’ouvre en vue descendante. Vous pouvez également cliquer avec le bouton droit sur un fichier de profil et obtenir les options suivantes :
Graphique TopDown du visualiseur de profil AL
Graphique BottomUp du visualiseur de profil AL
Lorsque le fichier de profil s’ouvre, il ressemble à l’illustration ci-dessous :
Différents modes d’affichage vous permettent d’étudier les données s’affichant dans le graphique. Pour basculer entre les vues, vous pouvez soit cliquer avec le bouton droit sur le fichier de profil et sélectionner une vue, soit cliquer sur le petit bouton dans le coin supérieur droit. Le graphique comporte deux modes d’affichage différents : descendant et ascendant.
En cas de tri ascendant de la pile, le graphique trie les méthodes en fonction de la séquence d’appels. Autrement dit, les nœuds enfants sont les méthodes appelées depuis le nœud parent. Et en cas de tri ascendant, le graphique est trié comme une pile d’appels inversée. Autrement dit, les nœuds enfants sont des méthodes ayant appelé le nœud parent.
Pour étudier plus avant, les colonnes Self-time et Temps total sont des indicateurs importants de l’endroit où le temps est passé dans le code. Le Self-time est le temps passé dans la méthode uniquement, à l’exclusion de tout appel hors de la méthode. Le Temps total est le Self-time plus tous les appels hors de la méthode. Sur les graphiques ascendants, les colonnes Temps total et Self-time sont triables. Un clic sur les colonnes entraîne leur tri croissant, puis un autre clic leur tri décroissant.
Le Nombre d’appels est disponible uniquement sur les graphiques descendants et indique le nombre d’appels d’une méthode spécifique. Le temps passé est agrégé.
Les nœuds du graphique peuvent être filtrés. Voici la syntaxe :
@column name | <alias> <op> <value> where
<column name> := [function, url, path, selfTime, totalTime, id, objectType, objectName, declaringApplication]
Voici les alias disponibles pour les noms de colonne :
<alias> := [f, u, p, s, t, id, ot, on, da]
<op> := [numeric operators, boolean operators, string operators]
numeric operators : [:, =, >, <, <=, >=, <>, !=]
: := equal
boolean operators : [:, =, <>, !=]
string operators : [:, =, !=, <>, ~, =]
~ = := <regex>
Visualiser les lignes de code exécutées dans la capture d’instantané
Le débogage d’instantané est un moyen puissant de résoudre les problèmes liés aux environnements de production cloud Business Central. Comme les captures d’instantané ne sont pas interactives, les snappoints doivent être définis au préalable, ce qui fait généralement du débogage d’instantané un processus itératif. Pour augmenter l’efficacité de la détermination du code exécuté, par exemple les chemins d’accès au code conditionnel, et faciliter la recherche des bons candidats pour définir de nouveaux snappoints afin d’étudier l’état variable de l’exécution du code, des repères visuels ont maintenant été ajoutés à la lecture de l’instantané. Ces repères s’affichent sous forme de lignes verticales dans la marge gauche de l’éditeur de code.
Lors de la lecture de l’instantané dans Visual Studio Code, la marge gauche de l’éditeur de code comporte une barre visuelle verticale pour indiquer le code exécuté dans la capture de l’instantané.
La couleur de la barre de marge peut être contrôlée à l’aide du nouveau paramètre al.snapshotDebuggerLinesHitDecoration dans le fichier settings.json.