Débogage de scripts
Débogage des scripts dans PowerShell Universal.
Les scripts qui s'exécutent dans Universal s'exécutent dans des processus en arrière-plan ou des runspaces, ce qui peut rendre difficile le débogage de ce qui se passe dans un script. Vous pouvez utiliser des cmdlets comme Write-Debug et Write-Verbose pour fournir plus d'informations dans les journaux pour les applications et les tâches.
Débogueur distant Visual Studio
À l'aide de l'extension Visual Studio Code pour PowerShell Universal, vous pouvez vous connecter directement à vos scripts PowerShell exécutant PowerShell Universal.
Débogueur intégré
Le débogueur intégré est pris en charge dans PowerShell 7 et les environnements intégrés. Il n'est pas pris en charge dans Windows PowerShell.
Le débogueur intégré permet d'accéder à une console de débogage pour l'exécution des scripts. Vous pouvez inclure l'appel de la cmdlet Wait-Debugger dans vos scripts et ceux-ci passeront à l'état In Breakpoint. Une fois cette transition effectuée, vous pouvez consulter la tâche pour exécuter des commandes contre le script.
Scripts
PowerShell Universal s'intègre directement avec le débogueur PowerShell. Vous pouvez inclure Wait-Debugger dans vos scripts pour les faire se mettre en pause.
Par exemple, supposons que vous ayez un script avec un appel à Wait-Debugger. La première ligne s'exécutera, puis le script se mettra en pause une fois qu'il atteindra la deuxième ligne.
$Processes = Get-Process
Wait-DebuggerUne fois qu'un script est mis en pause, vous verrez un terminal pour déboguer le script.
Vous pouvez ensuite utiliser les commandes de débogage intégrées pour parcourir le script pas à pas.
Applications
Vous pouvez utiliser Wait-Debugger directement dans vos applications PowerShell Universal. Vous pouvez inclure cette commande dans des gestionnaires d'événements et des éléments dynamiques pour mettre en pause l'exécution de l'application et évaluer l'état actuel du script.
Par exemple, vous pouvez inclure Wait-Debugger dans un élément dynamique.
Le résultat est que l'application affichera le squelette de chargement parce que le débogueur PowerShell est en point d'arrêt.
Dans la console d'administration, vous pouvez cliquer sur l'onglet Debugger pour afficher les points d'arrêt actuels sur lesquels l'application attend. Le débogueur fournit un terminal pour évaluer des commandes contre le runspace. Vous pouvez utiliser n'importe quelle commande PowerShell standard. Vous pouvez également utiliser les outils de débogage tels que le pas à pas et l'affichage du code source. Des boutons sont disponibles en haut de la console.
Vous pouvez utiliser des commandes comme Get-Variable pour obtenir des informations sur l'état des variables. Exécutez c pour permettre au point de terminaison de continuer à s'exécuter.
Journalisation des scripts
Certains aspects d'Universal journalisent automatiquement leurs scripts. D'autres fonctionnalités peuvent nécessiter que vous journalisiez vous-même.
API
Vous pouvez utiliser la vue des journaux en direct sur l'onglet Log pour afficher les journaux de l'API sélectionnée.
Tâches
Les tâches journalisent de manière extensive. Vous verrez la sortie de la console et du pipeline. Si vous définissez $DebugPreference ou $VerbosePreference, vous verrez également ces flux dans la sortie de la console. Vous pouvez ajouter des messages de journal supplémentaires en utilisant Write-Debug ou Write-Verbose.
Applications
Les applications journalisent les messages d'information, d'avertissement et d'erreur dans leur journal. Il est recommandé d'utiliser la journalisation lors du démarrage d'une application plutôt que d'essayer d'attacher un débogueur. Vous pouvez également utiliser la variable $DebugPreference pour obtenir des informations supplémentaires lors du démarrage de votre application.
Authentification et autorisation
Vous pouvez utiliser la vue des journaux en direct sur les pages d'authentification et de rôles pour voir la sortie des flux PowerShell.
Débogage des scripts depuis une console PowerShell
Vous pouvez déboguer n'importe quel script dans Universal (ou dans n'importe quel processus PowerShell, en réalité) en utilisant les cmdlets de débogage disponibles dans PowerShell. Ces cmdlets vous permettent de vous connecter à des processus PowerShell locaux, comme Universal, et de parcourir vos scripts pas à pas directement dans le terminal.
Mise en pause du script
Tout d'abord, vous devrez vous assurer que le script attendra que vous connectiez le débogueur avant de continuer. Cela signifie que vous devrez inclure une commande Wait-Debugger quelque part dans votre script.
Les applications n'attendront que 10 secondes lors du démarrage, donc placer un Wait-Debugger dans celles-ci peut ne pas fonctionner. Vous devriez vous appuyer sur l'utilisation de $DebugPreference et de Write-Debug pour diagnostiquer les problèmes de démarrage des applications.
Exécution de votre script
Maintenant que votre script est configuré pour se mettre en pause et attendre le débogueur, vous voudrez exécuter votre script. Pour les tâches, démarrez simplement la tâche. Pour les API, vous devrez effectuer une requête vers l'API via le point de terminaison que vous essayez de tester. Pour les applications, vous voudrez charger la page dans votre navigateur. Pour l'authentification et l'autorisation, vous voudrez vous connecter.
Trouver votre ID de processus
Une fois que vous avez votre commande Wait-Debugger dans le script que vous voulez déboguer, vous devrez démarrer le script et déterminer le processus dans lequel il s'exécute.
Tâches
Les tâches s'exécutent dans leur propre processus isolé dans Universal. Tout ce que vous avez à faire est de démarrer la tâche et elle démarrera le processus et attendra votre commande Wait-Debugger. Une fois votre tâche démarrée, vous pouvez utiliser la cmdlet Get-UAJob pour trouver l'ID de processus de cette tâche.
API
Les API s'exécutent dans un seul processus PowerShell. Elles ne démarrent pas un nouveau processus pour chaque appel d'API. Vous pouvez localiser le processus API en trouvant le processus pwsh ou PowerShell avec la ligne de commande qui inclut StartApi.
Applications
Les applications s'exécutent dans leur propre processus PowerShell isolé. L'ID de processus est affiché dans le tableau des applications dans la console d'administration.
Authentification et autorisation
Les scripts d'authentification et d'autorisation s'exécutent dans le serveur Universal. Vous pouvez trouver le processus Universal.Server.exe et y attacher le débogueur.
Environnement intégré
Toute fonctionnalité s'exécutant dans l'environnement intégré s'exécutera dans le processus Universal.Server.exe. Vous devrez vous attacher à ce processus pour les déboguer.
Attachement au processus et débogage du runspace
Une fois que vous avez le processus auquel vous souhaitez vous attacher, vous pouvez le faire en utilisant Enter-PSHostProcess. Spécifiez simplement l'ID de processus que vous avez trouvé à l'étape précédente.
Enter-PSHostProcess utilise des canaux nommés et nécessite que vous ayez la permission d'accéder au processus. Si vous exécutez Universal en tant que service, vous devrez peut-être l'exécuter sous votre compte local pour vous connecter correctement au processus.
Une fois que vous vous êtes attaché au processus, vous voudrez trouver le runspace où votre code s'exécute. Pour ce faire, vous pouvez utiliser la cmdlet Get-Runspace. Cela retournera une liste des runspaces actuellement actifs dans votre processus. Recherchez le runspace marqué InBreakpoint. C'est le runspace qui attend la commande Wait-Debugger.
Maintenant que vous avez trouvé votre runspace, utilisez Debug-Runspace pour vous y attacher. Vous aurez maintenant la possibilité d'émettre des commandes de débogage contre ce runspace. Vous pouvez afficher l'état des variables, émettre des commandes et même parcourir le script pas à pas.
Pour une liste complète des commandes de débogage, vous pouvez consulter la documentation Microsoft ici.
Exemple de connexion à un processus API
Voici un exemple de connexion à un processus API.
Débogage avec Visual Studio Code
Pour déboguer un script, vous pouvez utiliser la cmdlet Wait-Debugger dans votre script pour le mettre en pause jusqu'à ce qu'un débogueur soit attaché. Vous pouvez ensuite utiliser un débogueur, comme VS Code, pour vous attacher au processus et au runspace afin de visualiser les variables, parcourir le code pas à pas et exécuter des commandes de débogage.
Vous pouvez également déboguer des scripts en utilisant les cmdlets intégrées Enter-PSHostProcess, Get-Runspace et Debug-Runspace.
Mis à jour
Ce contenu vous a-t-il été utile ?