about_Debuggers

  • Article

Description courte

Décrit le débogueur PowerShell.

Description longue

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

À 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 l’environnement de script intégré Windows PowerShell (ISE) sur des ordinateurs distants.

Remarque

Windows PowerShell ISE prend uniquement en charge Windows PowerShell. Pour PowerShell 6 et versions ultérieures, vous devez utiliser Visual Studio Code avec l’extension pour PowerShell. Pour plus d’informations, consultez Débogage avec Visual Studio Code.

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 des lignes, des variables et des commandes.
  • Get-PSBreakpoint: obtient des 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, puis 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 des commandes dans le menu Débogage.

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: (Interrompre tout dans ISE) Saute dans un script en cours d’exécution dans la console PowerShell ou Windows PowerShell ISE. Notez que l’arrêt Ctrl+dans Windows PowerShell 2.0, 3.0 et 4.0 ferme le programme. Arrêtez tout fonctionne à la fois sur les scripts locaux et distants en cours d’exécution interactive.

  • o, StepOut: Sort de la fonction actuelle ; jusqu’à un niveau s’il est imbriqué. Si, dans le corps principal, il continue à la fin ou au 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, , : StopExitarrê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 si elle était Step (), StepOver (sv) ou List ().l Sinon, représente une action d’envoi.

  • ?, h: affiche l’aide de la commande du débogueur.

Pour quitter le débogueur, vous pouvez utiliser Stop (q).

À compter 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 ou Debug-JobDebug-Runspace.

À l’aide de ces commandes de débogueur, vous pouvez exécuter un script, 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 dans une instruction avec un opérateur de redirection, par >exemple, le débogueur PowerShell effectue des étapes sur toutes les instructions restantes du script.

Affichage des valeurs des variables de script

Pendant que 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

Lorsque vous affichez la valeur de l’une de ces variables, vous obtenez la valeur de cette variable pour un pipeline interne que le débogueur utilise, et non la valeur de la variable dans le script.

Pour afficher la valeur de ces variables pour le script en cours de débogage, ajoutez des lignes à votre script pour enregistrer ces valeurs dans une nouvelle variable. Définissez votre point d’arrêt après ces nouvelles lignes. Vous pouvez ensuite afficher la valeur de la nouvelle variable.

Par exemple,

$scriptArgs = $Args
$scriptname = $MyInvocation.PSCommandPath

Environnement du débogueur

Lorsque vous atteignez un point d’arrêt, vous entrez dans l’environnement du débogueur. L’invite de commandes change afin qu’elle commence par « [DBG] : ». En outre, dans certaines applications hôtes, telles que la console PowerShell, 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 à ceux (ASCII 62) qui apparaissent à l’invite de commandes.

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

Vous pouvez trouver le niveau d’imbrication à l’aide de la $NestedPromptLevel variable automatique. La variable automatique, est $PSDebugContextdéfinie dans l’étendue locale. Vous pouvez utiliser la présence de la $PSDebugContext variable pour déterminer si vous exécutez 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 rupture dans le débogueur ne modifie pas l’étendue dans laquelle vous travaillez, mais lorsque vous atteignez un point d’arrêt dans un script, vous passez à l’étendue du script. L’étendue du 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 commande ou Get-Variable des Get-Alias applets de commande.

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

Get-Variable -scope 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 un point d’arrêt de 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 $name variable, le débogueur s’arrête sur n’importe quelle variable dans n’importe quel $name script, commande, fonction, applet de commande de script ou expression que vous exécutez jusqu’à ce que vous désactivez ou supprimez 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 sont spécifiques aux fichiers de script. Ils sont donc 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 begin, processet end des sections, 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

Vous pouvez exécuter Enter-PSSession pour démarrer une session PowerShell distante 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 vous permet de 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 client 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, Enter-PSSession démarre automatiquement le débogueur de ligne de commande lorsque vous vous reconnectez à la session.

L’exemple suivant montre comment cela fonctionne. Les points d’arrêt ont été définis sur les lignes 6, 11, 22 et 25 du script. Lorsque le débogueur démarre, il existe deux modifications identifiantes à l’invite :

  • Nom de l’ordinateur sur lequel la session est en cours d’exécution
  • 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 de PowerShell et affiche un message approprié à la version. 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 7) {
    "Upgrade to PowerShell 7!"
  }
  else {
    "Have you run a background job today (start-job)?"
  }
}

$scriptName = $MyInvocation.PSCommandPath
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

La commande retourne un objet 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 commande Étape (s) pour exécuter la première instruction dans le 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.PSCommandPath

À ce stade, la $scriptName variable n’est pas remplie, 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 autre Step commande (s) pour exécuter l’instruction active et afficher un aperçu de l’instruction suivante dans le script. L’instruction suivante appelle la psversion fonction.

DBG> s
test.ps1:12  psversion

À ce stade, la $scriptName variable est remplie, 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 Étape pour exécuter l’appel de fonction. Appuyez sur Entrée ou tapez « s » pour l’étape.

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. Toutefois, 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 effectue les étapes de 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"

Comme 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 a quitté et 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 commande et Remove-PsBreakpoint les Get-PsBreakpoint applets de commande. (Si vous pensez que vous pouvez 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 en tant que :

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 est Écriture. L’exécution s’arrête donc 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.PSCommandPath
DBG>

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

DBG> $scriptName
DBG>

Utilisez une Step commande (s) 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

Utilisez une commande Étape (s) pour afficher un aperçu de l’instruction suivante dans le script.

DBG> s
test.ps1:12  psversion

L’instruction suivante est un appel à la psversion fonction. Pour ignorer la fonction, mais toujours l’exécuter, utilisez une StepOver commande (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 StepOver commande exécute la fonction et affiche un aperçu de l’instruction suivante dans le script, qui imprime la ligne finale.

Utilisez une Stop commande (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 commande et Remove-PsBreakpoint les Get-PsBreakpoint applets de commande.

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

Créez un point d’arrêt de commande sur la psversion fonction.

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

Vous pouvez abrégée cette commande pour :

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

Exécutez maintenant 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 à 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 Set-PSBreakpoint définir des conditions pour l’exécution du point d’arrêt ou d’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 sont en lecture seule. Vous ne pouvez donc 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 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 enregistre la valeur de la $scriptName variable lorsque la fonction est appelée. Étant donné que la break mot clé n’est pas utilisée 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.

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

La break mot clé dans l’action dirige le débogueur pour exécuter le point d’arrêt. Vous pouvez également utiliser le continue mot clé pour diriger le débogueur à 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.

Exécutez maintenant 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 pouvez 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.

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.

  • L’applet Set-PSDebug de commande offre des fonctionnalités de débogage de script de base, notamment l’exécution pas à pas et le suivi.

  • Utilisez l’applet Set-StrictMode de commande pour détecter les références à des variables non initialisées, pour faire référence à 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-DebugWrite-Warninget Write-Verbose.

Voir aussi