about_Debuggers

Article
06/21/2023

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 de script. Le débogueur PowerShell peut vous aider à examiner et à identifier les erreurs et les inefficacités dans vos scripts, fonctions, commandes, configurations PowerShell Desired State Configuration (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 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 la fonctionnalité a été mise à jour pour vous permettre de vous reconnecter à et d’entrer 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 comprend 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 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 d’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’elle soit terminée. 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: (Cassez tout dans ISE) Effectue des sauts dans 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 à la fois sur les scripts locaux et distants qui s’exécutent de manière interactive.
o, StepOut: sort de la fonction actuelle ; monter d’un niveau si imbriqué. Si dans le corps main, il passe à 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, 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 d’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 préoccupant, 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 accédez à 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 du 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 par les caractères supérieurs à (ASCII 62) répétés 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

Le fait d’entrer dans le débogueur ne change 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 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 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 variable, le $name débogueur s’interrompt sur n’importe quelle variable dans un $name 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 comporte 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 distante, dans la console ou Windows PowerShell ISE. Enter-PSSession la fonctionnalité a été mise à jour pour vous permettre de vous reconnecter à et d’entrer 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 comprend 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 commande Step (s) 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 autre commande Step (s) pour exécuter l’instruction active et pour 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 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 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 pour 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 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"

É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 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 Get-PSBreakpoint commande et Remove-PSBreakpoint . (Si vous pensez 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 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 commande Step (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
```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 dernière ligne.

Utilisez une commande Arrêter (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 à l’appel de fonction. À ce stade, la fonction n’a pas encore été appelée. Cela vous permet d’utiliser le paramètre Action de pour définir des Set-PSBreakpoint conditions d’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 consigne 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 diriger le débogueur à exécuter sans rupture. Étant donné que le mot clé par défaut est Continuer, 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 de Get-PsCallStack commande ou la Get-PsCallStack commande de débogueur (k). La commande suivante obtient la pile d’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

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

Windows PowerShell ISE comprend 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 de base, 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