À propos des débogueurs

Article
06/21/2023

DESCRIPTION COURTE

Décrit le débogueur PowerShell.

DESCRIPTION DÉTAILLÉE

Le débogage est le processus d’examen d’un script pendant son exécution pour identifier et corriger les erreurs dans les instructions de script. Le débogueur PowerShell peut vous aider à examiner et à identifier les erreurs et les inefficacités dans vos scripts, fonctions, commandes, configurations d’Desired State Configuration PowerShell (DSC) ou expressions.

À compter de PowerShell 5.0, le débogueur PowerShell a été mis à jour pour déboguer des scripts, des fonctions, des commandes, des configurations ou des expressions qui s’exécutent dans la console ou Windows PowerShell ISE sur des ordinateurs distants. Vous pouvez exécuter Enter-PSSession pour démarrer une session PowerShell à distance interactive dans laquelle vous pouvez définir des points d’arrêt et déboguer des fichiers de script et des commandes sur l’ordinateur distant. Enter-PSSession la fonctionnalité a été mise à jour pour vous permettre de vous reconnecter à une session déconnectée qui exécute un script ou une commande sur un ordinateur distant. Si le script en cours d’exécution atteint un point d’arrêt, votre session cliente démarre automatiquement le débogueur. Si la session déconnectée qui exécute un script a déjà atteint un point d’arrêt et est arrêtée au point d’arrêt, Enter-PSSession démarre automatiquement le débogueur de ligne de commande après vous être reconnecté à la session.

Vous pouvez utiliser les fonctionnalités du débogueur PowerShell pour examiner un script, une fonction, une commande ou une expression PowerShell pendant son exécution. Le débogueur PowerShell comprend un ensemble d’applets de commande qui vous permettent de définir des points d’arrêt, de gérer les points d’arrêt et d’afficher la pile des appels.

Applets de commande du débogueur

Le débogueur PowerShell inclut l’ensemble d’applets de commande suivant :

Set-PSBreakpoint: définit des points d’arrêt sur les lignes, les variables et les commandes.
Get-PSBreakpoint: obtient les points d’arrêt dans la session active.
Disable-PSBreakpoint: désactive les points d’arrêt dans la session active.
Enable-PSBreakpoint: réactive les points d’arrêt dans la session active.
Remove-PSBreakpoint: supprime les points d’arrêt de la session active.
Get-PSCallStack: affiche la pile des appels actuelle.

Démarrage et arrêt du débogueur

Pour démarrer le débogueur, définissez un ou plusieurs points d’arrêt. Ensuite, exécutez le script, la commande ou la fonction que vous souhaitez déboguer.

Lorsque vous atteignez un point d’arrêt, l’exécution s’arrête et le contrôle est remis au débogueur.

Pour arrêter le débogueur, exécutez le script, la commande ou la fonction jusqu’à ce qu’il soit terminé. Ou tapez stop ou t.

Commandes du débogueur

Lorsque vous utilisez le débogueur dans la console PowerShell, utilisez les commandes suivantes pour contrôler l’exécution. Dans Windows PowerShell ISE, utilisez les commandes du menu Déboguer.

Remarque : Pour plus d’informations sur l’utilisation du débogueur dans d’autres applications hôtes, consultez la documentation de l’application hôte.

s, StepInto: exécute l’instruction suivante, puis s’arrête.
v, StepOver: exécute l’instruction suivante, mais ignore les fonctions et les appels. Les instructions ignorées sont exécutées, mais sans pas à pas.
Ctrl+Break: (Arrêter tout dans ISE) Permet de créer un script en cours d’exécution dans la console PowerShell ou Windows PowerShell ISE. Notez que Ctrl+Break dans Windows PowerShell 2.0, 3.0 et 4.0 ferme le programme. Arrêter tout fonctionne sur les scripts locaux et distants exécutés de manière interactive.
o, StepOut: sort de la fonction actuelle ; un niveau supérieur s’il est imbriqué. Si dans le corps du main, il continue jusqu’à la fin ou le point d’arrêt suivant. Les instructions ignorées sont exécutées, mais sans pas à pas.
c, Continue: continue à s’exécuter jusqu’à ce que le script soit terminé ou jusqu’à ce que le point d’arrêt suivant soit atteint. Les instructions ignorées sont exécutées, mais sans pas à pas.
l, List: affiche la partie du script en cours d’exécution. Par défaut, il affiche la ligne actuelle, cinq lignes précédentes et 10 lignes suivantes. Pour continuer à répertorier le script, appuyez sur ENTRÉE.
l <m>, List: affiche 16 lignes du script commençant par le numéro de ligne spécifié par <m>.
l <m> <n>, List: affiche les <n> lignes du script, en commençant par le numéro de ligne spécifié par <m>.
q, Stop, Exit: arrête l’exécution du script et quitte le débogueur. Si vous déboguez un travail en exécutant l’applet Debug-Job de commande, la Exit commande détache le débogueur et permet au travail de continuer à s’exécuter.
k, Get-PsCallStack: affiche la pile des appels actuelle.
<Enter>: répète la dernière commande s’il s’agissait de Step (s), StepOver (v) ou List (l). Sinon, représente une action d’envoi.
?, h: affiche l’aide de la commande de débogueur.

Pour quitter le débogueur, vous pouvez utiliser Arrêter (q).

À partir de PowerShell 5.0, vous pouvez exécuter la commande Exit pour quitter une session de débogage imbriquée que vous avez démarrée en exécutant Debug-Job ou Debug-Runspace.

À l’aide de ces commandes de débogueur, vous pouvez exécuter un script, vous arrêter sur un point de préoccupation, examiner les valeurs des variables et l’état du système, et continuer à exécuter le script jusqu’à ce que vous ayez identifié un problème.

REMARQUE : Si vous effectuez un pas à pas détaillé dans une instruction avec un opérateur de redirection, tel que «> », le débogueur PowerShell effectue des étapes sur toutes les instructions restantes dans le script.

Affichage des valeurs des variables de script

Lorsque vous êtes dans le débogueur, vous pouvez également entrer des commandes, afficher la valeur des variables, utiliser des applets de commande et exécuter des scripts sur la ligne de commande.

Vous pouvez afficher la valeur actuelle de toutes les variables du script en cours de débogage, à l’exception des variables automatiques suivantes :

$_
$Args
$Input
$MyInvocation
$PSBoundParameters

Si vous essayez d’afficher la valeur d’une de ces variables, vous l’obtenez pour un pipeline interne que le débogueur utilise, pas la valeur de la variable dans le script.

Pour afficher la valeur de ces variables pour le script en cours de débogage, dans le script, affectez la valeur de la variable automatique à une nouvelle variable. Vous pouvez ensuite afficher la valeur de la nouvelle variable.

Par exemple,

$scriptArgs = $Args
$scriptArgs

Dans l’exemple de cette rubrique, la valeur de la $MyInvocation variable est réaffectée comme suit :

$scriptname = $MyInvocation.MyCommand.Path

Environnement débogueur

Lorsque vous atteignez un point d’arrêt, vous entrez dans l’environnement du débogueur. L’invite de commandes change de sorte qu’elle commence par « [DBG] : ».

Pour plus d’informations sur la personnalisation de l’invite, consultez about_Prompts.

En outre, dans certaines applications hôtes, telles que la console PowerShell (mais pas dans Windows PowerShell’environnement de script intégré [ISE]), une invite imbriquée s’ouvre pour le débogage. Vous pouvez détecter l’invite imbriquée en répétant les caractères supérieurs à (ASCII 62) qui s’affichent à l’invite de commandes.

Par exemple, voici l’invite de débogage par défaut dans la console PowerShell :

[DBG]: PS (get-location)>>>

Vous pouvez trouver le niveau d’imbrication à l’aide de la $NestedPromptLevel variable automatique.

En outre, une variable automatique, $PSDebugContext, est définie dans l’étendue locale. Vous pouvez utiliser la présence de la $PsDebugContext variable pour déterminer si vous êtes dans le débogueur.

Par exemple :

if ($PSDebugContext) {"Debugging"} else {"Not Debugging"}

Vous pouvez utiliser la valeur de la $PSDebugContext variable dans votre débogage.

[DBG]: PS>>> $PSDebugContext.InvocationInfo

Name   CommandLineParameters  UnboundArguments  Location
----   ---------------------  ----------------  --------
=      {}                     {}                C:\ps-test\vote.ps1 (1)

Débogage et étendue

La détection du débogueur ne modifie pas l’étendue dans laquelle vous travaillez, mais lorsque vous atteignez un point d’arrêt dans un script, vous accédez à l’étendue du script. L’étendue de script est un enfant de l’étendue dans laquelle vous avez exécuté le débogueur.

Pour rechercher les variables et les alias définis dans l’étendue du script, utilisez le paramètre Scope des applets de Get-Alias commande ou Get-Variable .

Par exemple, la commande suivante obtient les variables dans l’étendue locale (script) :

Get-Variable -scope 0

Vous pouvez raccourcir la commande comme suit :

gv -s 0

Il s’agit d’un moyen utile de voir uniquement les variables que vous avez définies dans le script et que vous avez définies lors du débogage.

Débogage sur la ligne de commande

Lorsque vous définissez un point d’arrêt de variable ou une commande, vous pouvez définir le point d’arrêt uniquement dans un fichier de script. Toutefois, par défaut, le point d’arrêt est défini sur tout ce qui s’exécute dans la session active.

Par exemple, si vous définissez un point d’arrêt sur la variable, le $name débogueur s’arrête sur n’importe quelle $name variable dans un script, une commande, une fonction, une applet de commande de script ou une expression que vous exécutez jusqu’à ce que vous désactiviez ou supprimiez le point d’arrêt.

Cela vous permet de déboguer vos scripts dans un contexte plus réaliste dans lequel ils peuvent être affectés par des fonctions, des variables et d’autres scripts dans la session et dans le profil de l’utilisateur.

Les points d’arrêt de ligne étant spécifiques aux fichiers de script, ils sont définis uniquement dans les fichiers de script.

Fonctions de débogage

Lorsque vous définissez un point d’arrêt sur une fonction qui a Begindes sections , Processet End , le débogueur s’arrête à la première ligne de chaque section.

Par exemple :

function test-cmdlet {
    begin {
        write-output "Begin"
    }
    process {
        write-output "Process"
    }
    end {
        write-output "End"
    }
}

C:\PS> Set-PSBreakpoint -command test-cmdlet

C:\PS> test-cmdlet

Begin
Entering debug mode. Use h or ? for help.

Hit Command breakpoint on 'prompt:test-cmdlet'

test-cmdlet

[DBG]: C:\PS> c
Process
Entering debug mode. Use h or ? for help.

Hit Command breakpoint on 'prompt:test-cmdlet'

test-cmdlet

[DBG]: C:\PS> c
End
Entering debug mode. Use h or ? for help.

Hit Command breakpoint on 'prompt:test-cmdlet'

test-cmdlet

# [DBG]: C:\PS>

Débogage de scripts distants

À partir de PowerShell 5.0, vous pouvez exécuter le débogueur PowerShell dans une session à distance, dans la console ou Windows PowerShell ISE. Enter-PSSession la fonctionnalité a été mise à jour pour vous permettre de vous reconnecter à une session déconnectée qui s’exécute sur un ordinateur distant et qui exécute actuellement un script. Si le script en cours d’exécution atteint un point d’arrêt, votre session cliente démarre automatiquement le débogueur.

Voici un exemple qui montre comment cela fonctionne, avec des points d’arrêt définis dans un script aux lignes 6, 11, 22 et 25. Notez que dans l’exemple, lorsque le débogueur démarre, il existe deux invites d’identification : le nom de l’ordinateur sur lequel la session s’exécute et l’invite DBG qui vous indique que vous êtes en mode débogage.

Enter-Pssession -Cn localhost
[localhost]: PS C:\psscripts> Set-PSBreakpoint .\ttest19.ps1 6,11,22,25

ID Script          Line     Command          Variable          Action
-- ------          ----     -------          --------          ------
0 ttest19.ps1          6
1 ttest19.ps1          11
2 ttest19.ps1          22
3 ttest19.ps1          25

[localhost]: PS C:\psscripts> .\ttest19.ps1
Hit Line breakpoint on 'C:\psscripts\ttest19.ps1:11'

At C:\psscripts\ttest19.ps1:11 char:1
+ $winRMName = "WinRM"
# + ~

[localhost]: [DBG]: PS C:\psscripts>> list

6:      1..5 | foreach { sleep 1; Write-Output "hello2day $_" }
7:  }
# 8:

9:  $count = 10
10:  $psName = "PowerShell"
11:* $winRMName = "WinRM"
12:  $myVar = 102
# 13:

14:  for ($i=0; $i -lt $count; $i++)
15:  {
16:      sleep 1
17:      Write-Output "Loop iteration is: $i"
18:      Write-Output "MyVar is $myVar"
# 19:

20:      hello2day
# 21:


[localhost]: [DBG]: PS C:\psscripts>> stepover
At C:\psscripts\ttest19.ps1:12 char:1
+ $myVar = 102
# + ~

[localhost]: [DBG]: PS C:\psscripts>> quit
[localhost]: PS C:\psscripts> Exit-PSSession
PS C:\psscripts>

Exemples

Ce script de test détecte la version du système d’exploitation et affiche un message approprié au système. Il inclut une fonction, un appel de fonction et une variable.

La commande suivante affiche le contenu du fichier de script de test :

PS C:\PS-test>  Get-Content test.ps1

function psversion {
  "PowerShell " + $PSVersionTable.PSVersion
  if ($PSVersionTable.PSVersion.Major -lt 6) {
    "Upgrade to PowerShell 6.0!"
  }
  else {
    "Have you run a background job today (start-job)?"
  }
}

$scriptName = $MyInvocation.MyCommand.Path
psversion
"Done $scriptName."

Pour commencer, définissez un point d’arrêt à un point d’intérêt dans le script, tel qu’une ligne, une commande, une variable ou une fonction.

Commencez par créer un point d’arrêt de ligne sur la première ligne du script Test.ps1 dans le répertoire actif.

PS C:\ps-test> Set-PSBreakpoint -line 1 -script test.ps1

Vous pouvez abréger cette commande :

PS C:\ps-test> spb 1 -s test.ps1

La commande retourne un objet de point d’arrêt de ligne (System.Management.Automation.LineBreakpoint).

Column     : 0
Line       : 1
Action     :
Enabled    : True
HitCount   : 0
Id         : 0
Script     : C:\ps-test\test.ps1
ScriptName : C:\ps-test\test.ps1

À présent, démarrez le script.

PS C:\ps-test> .\test.ps1

Lorsque le script atteint le premier point d’arrêt, le message de point d’arrêt indique que le débogueur est actif. Il décrit le point d’arrêt et affiche un aperçu de la première ligne du script, qui est une déclaration de fonction. L’invite de commandes change également pour indiquer que le débogueur a le contrôle.

La ligne d’aperçu inclut le nom du script et le numéro de ligne de la commande aperçue.

Entering debug mode. Use h or ? for help.

Hit Line breakpoint on 'C:\ps-test\test.ps1:1'

test.ps1:1   function psversion {
# DBG>

Utilisez la ou les commandes Step pour exécuter la première instruction du script et afficher un aperçu de l’instruction suivante. L’instruction suivante utilise la $MyInvocation variable automatique pour définir la valeur de la $scriptName variable sur le chemin d’accès et le nom de fichier du fichier de script.

DBG> s
test.ps1:11  $scriptName = $MyInvocation.MyCommand.Path

À ce stade, la $scriptName variable n’est pas renseignée, mais vous pouvez vérifier la valeur de la variable en affichant sa valeur. Dans ce cas, la valeur est $null.

DBG> $scriptname
# DBG>

Utilisez une ou plusieurs commandes Step pour exécuter l’instruction actuelle et afficher un aperçu de l’instruction suivante dans le script. L’instruction suivante appelle la fonction PsVersion.

DBG> s
test.ps1:12  psversion

À ce stade, la $scriptName variable est renseignée, mais vous vérifiez la valeur de la variable en affichant sa valeur. Dans ce cas, la valeur est définie sur le chemin du script.

DBG> $scriptName
C:\ps-test\test.ps1

Utilisez une autre commande Step pour exécuter l’appel de fonction. Appuyez sur Entrée ou tapez « s » pour Step.

DBG> s
test.ps1:2       "PowerShell " + $PSVersionTable.PSVersion

Le message de débogage inclut un aperçu de l’instruction dans la fonction . Pour exécuter cette instruction et afficher un aperçu de l’instruction suivante dans la fonction, vous pouvez utiliser une Step commande . Mais, dans ce cas, utilisez une commande StepOut (o). Il termine l’exécution de la fonction (sauf si elle atteint un point d’arrêt) et passe à l’instruction suivante dans le script.

DBG> o
Windows PowerShell 2.0
Have you run a background job today (start-job)?
test.ps1:13  "Done $scriptName"

Étant donné que nous sommes sur la dernière instruction du script, les commandes Step, StepOut et Continue ont le même effet. Dans ce cas, utilisez StepOut (o).

Done C:\ps-test\test.ps1
PS C:\ps-test>

La commande StepOut exécute la dernière commande. L’invite de commandes standard indique que le débogueur s’est arrêté et a retourné le contrôle au processeur de commandes.

À présent, réexécutez le débogueur. Tout d’abord, pour supprimer le point d’arrêt actuel, utilisez les applets de Get-PSBreakpoint commande et Remove-PSBreakpoint . (Si vous pensez que vous pourriez réutiliser le point d’arrêt, utilisez l’applet Disable-PSBreakpoint de commande au lieu de Remove-PSBreakpoint.)

PS C:\ps-test> Get-PSBreakpoint| Remove-PSBreakpoint

Vous pouvez abréger cette commande :

PS C:\ps-test> gbp | rbp

Ou exécutez la commande en écrivant une fonction, telle que la fonction suivante :

function delbr { gbp | rbp }

À présent, créez un point d’arrêt sur la $scriptname variable.

PS C:\ps-test> Set-PSBreakpoint -variable scriptname -script test.ps1

Vous pouvez raccourcir la commande comme suit :

PS C:\ps-test> sbp -v scriptname -s test.ps1

À présent, démarrez le script. Le script atteint le point d’arrêt de la variable. Le mode par défaut étant Write, l’exécution s’arrête juste avant l’instruction qui modifie la valeur de la variable.

PS C:\ps-test> .\test.ps1
Hit Variable breakpoint on 'C:\ps-test\test.ps1:$scriptName'
(Write access)

test.ps1:11  $scriptName = $MyInvocation.MyCommand.Path
# DBG>

Affiche la valeur actuelle de la $scriptName variable, qui est $null.

DBG> $scriptName
# DBG>

Utilisez une ou plusieurs commandes Step pour exécuter l’instruction qui remplit la variable. Ensuite, affichez la nouvelle valeur de la $scriptName variable.

DBG> $scriptName
C:\ps-test\test.ps1
```powershell

Use a Step command (s) to preview the next statement in the script.

```powershell
DBG> s
test.ps1:12  psversion

L’instruction suivante est un appel à la fonction PsVersion. Pour ignorer la fonction tout en l’exécutant, utilisez une commande StepOver (v). Si vous êtes déjà dans la fonction lorsque vous utilisez StepOver, elle n’est pas efficace. L’appel de fonction s’affiche, mais il n’est pas exécuté.

DBG> v
Windows PowerShell 2.0
Have you run a background job today (start-job)?
test.ps1:13  "Done $scriptName"

La commande StepOver exécute la fonction et affiche un aperçu de l’instruction suivante dans le script, qui imprime la ligne finale.

Utilisez une commande Stop (t) pour quitter le débogueur. L’invite de commandes revient à l’invite de commandes standard.

C:\ps-test>

Pour supprimer les points d’arrêt, utilisez les applets de Get-PSBreakpoint commande et Remove-PSBreakpoint .

PS C:\ps-test> Get-PSBreakpoint| Remove-PSBreakpoint

Create un nouveau point d’arrêt de commande sur la fonction PsVersion.

PS C:\ps-test> Set-PSBreakpoint -command psversion -script test.ps1

Vous pouvez raccourcir cette commande pour :

PS C:\ps-test> sbp -c psversion -s test.ps1

À présent, exécutez le script.

PS C:\ps-test> .\test.ps1
Hit Command breakpoint on 'C:\ps-test\test.ps1:psversion'

test.ps1:12  psversion
# DBG>

Le script atteint le point d’arrêt au niveau de l’appel de fonction. À ce stade, la fonction n’a pas encore été appelée. Cela vous donne la possibilité d’utiliser le paramètre Action de pour définir des Set-PSBreakpoint conditions pour l’exécution du point d’arrêt ou pour effectuer des tâches préparatoires ou de diagnostic, telles que le démarrage d’un journal ou l’appel d’un script de diagnostic ou de sécurité.

Pour définir une action, utilisez une commande Continuer (c) pour quitter le script et une Remove-PSBreakpoint commande pour supprimer le point d’arrêt actuel. (Les points d’arrêt étant en lecture seule, vous ne pouvez pas ajouter d’action au point d’arrêt actuel.)

DBG> c
Windows PowerShell 2.0
Have you run a background job today (start-job)?
Done C:\ps-test\test.ps1

PS C:\ps-test> Get-PSBreakpoint| Remove-PSBreakpoint
PS C:\ps-test>

À présent, créez un nouveau point d’arrêt de commande avec une action. La commande suivante définit un point d’arrêt de commande avec une action qui journalise la valeur de la $scriptName variable lorsque la fonction est appelée. Étant donné que le mot clé d’arrêt n’est pas utilisé dans l’action, l’exécution ne s’arrête pas. (Le backtick (') est le caractère de continuation de ligne.)

PS C:\ps-test> Set-PSBreakpoint -command psversion -script test.ps1  `
-action { add-content "The value of `$scriptName is $scriptName." `
-path action.log}

Vous pouvez également ajouter des actions qui définissent des conditions pour le point d’arrêt. Dans la commande suivante, le point d’arrêt de commande est exécuté uniquement si la stratégie d’exécution est définie sur RemoteSigned, la stratégie la plus restrictive qui vous permet toujours d’exécuter des scripts. (Le backtick (') est le caractère de continuation.)

PS C:\ps-test> Set-PSBreakpoint -script test.ps1 -command psversion `
-action { if ((Get-ExecutionPolicy) -eq "RemoteSigned") { break }}

L’mot clé d’arrêt dans l’action indique au débogueur d’exécuter le point d’arrêt. Vous pouvez également utiliser l’mot clé Continuer pour indiquer au débogueur de s’exécuter sans rupture. Étant donné que la mot clé par défaut est Continue, vous devez spécifier Break pour arrêter l’exécution.

À présent, exécutez le script.

PS C:\ps-test> .\test.ps1
Hit Command breakpoint on 'C:\ps-test\test.ps1:psversion'

test.ps1:12  psversion

Étant donné que la stratégie d’exécution est définie sur RemoteSigned, l’exécution s’arrête à l’appel de fonction.

À ce stade, vous souhaiterez peut-être case activée la pile des appels. Utilisez l’applet Get-PsCallStack de commande ou la Get-PsCallStack commande de débogueur (k). La commande suivante obtient la pile des appels actuelle.

DBG> k
2: prompt
1: .\test.ps1: $args=[]
0: prompt: $args=[]

Cet exemple illustre quelques-unes des nombreuses façons d’utiliser le débogueur PowerShell.

Pour plus d’informations sur les applets de commande du débogueur, tapez la commande suivante :

help <cmdlet-name> -full

Par exemple, entrez :

help Set-PSBreakpoint -full

Autres fonctionnalités de débogage dans PowerShell

Outre le débogueur PowerShell, PowerShell inclut plusieurs autres fonctionnalités que vous pouvez utiliser pour déboguer des scripts et des fonctions.

Windows PowerShell ISE inclut un débogueur graphique interactif. Pour plus d’informations, démarrez Windows PowerShell ISE et appuyez sur F1.
L’applet Set-PSDebug de commande offre des fonctionnalités de débogage de script très basiques, notamment le pas à pas et le suivi.
Utilisez l’applet Set-StrictMode de commande pour détecter les références à des variables non initialisées, les références à des propriétés inexistantes d’un objet et la syntaxe de fonction qui n’est pas valide.
Ajoutez des instructions de diagnostic à un script, telles que des instructions qui affichent la valeur des variables, des instructions qui lisent l’entrée à partir de la ligne de commande ou des instructions qui signalent l’instruction actuelle. Utilisez les applets de commande qui contiennent le verbe Écrire pour cette tâche, telles que Write-Host, Write-Debug, Write-Warninget Write-Verbose.

Partager via