RUBRIQUE
about_Debuggers
DESCRIPTION COURTE
Décrit le débogueur Windows PowerShell.
DESCRIPTION LONGUE
Le débogage est le processus consistant à examiner un script
pendant son exécution pour identifier et corriger des erreurs dans ses
instructions. Le débogueur Windows PowerShell est conçu pour vous aider
à examiner et identifier des erreurs et des anomalies dans vos scripts.
Remarque : le débogueur Windows PowerShell ne s'exécute pas à
distance. Pour déboguer un script sur un ordinateur distant,
copiez-le sur l'ordinateur local.
Vous pouvez utiliser les fonctionnalités du débogueur Windows
PowerShell pour examiner un script, une fonction, une commande ou une
expression Windows PowerShell pendant leur exécution. Le débogueur Windows
PowerShell inclut un jeu d'applets de commande qui vous permettent de
définir ou de gérer des points d'arrêt, ainsi que de consulter la pile
des appels.
Windows PowerShell offre plusieurs méthodes pour déboguer des scripts,
des fonctions et des commandes.
Méthode 1 : L'applet de commande Set-PsDebug offre des fonctionnalités
de débogage de script de base, telles que l'exécution
par étape et le traçage. Pour plus d'informations, tapez :
"get-help set-psdebug".
Méthode 2 : Utilisez l'applet de commande Set-StrictMode pour détecter
des références à des variables non initialisées, à des
propriétés inexistantes d'un objet et à une syntaxe de
fonction non valide.
Méthode 3 : Ajoutez à un script des instructions de diagnostic
permettant notamment d'afficher la valeur des variables,
de lire les données entrées à partir de la ligne de
commande ou de signaler l'instruction actuelle. Utilisez
les applets de commande contenant le verbe Write pour
cette tâche (par exemple, Write-Host, Write-Debug,
Write-Warning et Write-Verbose).
Méthode 4 : Utilisez le débogueur Windows PowerShell pour déboguer
un script. Vous pouvez également utiliser le débogueur
pour déboguer une fonction ou un bloc de script que
vous avez tapé à l'invite de commandes. Vous avez la
possibilité de définir des points d'arrêt, de parcourir
le script pas à pas, d'examiner les valeurs des
variables, d'exécuter des diagnostics et des commandes
de journalisation, ou bien encore d'afficher la pile
des appels.
Applets de commande de débogueur
Le débogueur Windows PowerShell inclut le jeu suivant d'applets de
commande :
Set-PsBreakpoint : définit les points d'arrêt sur des lignes,
des variables et des commandes.
Get-PsBreakpoint : obtient les points d'arrêt de la session
active.
Disable-PsBreakpoint : désactive les points d'arrêt de la
session active.
Enable-PsBreakpoint : réactive les points d'arrêt de 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. Exécutez ensuite 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 débogueur reprend le contrôle.
Pour arrêter le débogueur, exécutez complètement le script, la
commande ou la fonction. Vous pouvez également taper " stop "
ou " t ".
Commandes de débogueur
Lorsque vous employez le débogueur dans la console Windows
PowerShell, utilisez les commandes ci-dessous pour contrôler
l'exécution.
Remarque : pour plus d'informations sur l'utilisation du
débogueur dans d'autres applications hôtes, consultez la
documentation de ces applications.
s, Step-into Exécute l'instruction suivante, puis
s'arrête.
v, Step-over Exécute l'instruction suivante, mais ignore
les fonctions et les appels. Les instructions
ignorées sont exécutées, mais pas en mode pas à pas.
o, Step-out Effectue un pas à pas hors de la fonction
actuelle, en remontant d'un niveau si elle
est imbriquée. Si elle se trouve dans le
corps principal, l'exécution se poursuit
jusqu'à la fin ou jusqu'au point d'arrêt
suivant. Les instructions ignorées sont
exécutées, mais pas en mode pas à pas.
c, Continue Continue à s'exécuter jusqu'à ce que le
script soit terminé ou que le point d'arrêt
suivant soit atteint. Les instructions
ignorées sont exécutées, mais pas en mode
pas à pas.
l, List Affiche la partie du script qui
s'exécute. Par défaut, la commande
affiche la ligne en cours, les cinq lignes
précédentes et les 10 lignes suivantes. Pour
continuer à lister le script, appuyez sur ENTRÉE.
l <m>, List Affiche 16 lignes du début de script avec
le numéro de ligne spécifié par <m>.
l <m> <n>, List Affiche <n> lignes du script commençant par
le numéro de ligne spécifié par <m>.
q, Stop Arrête l'exécution du script et quitte le
débogueur.
k, Get-PsCallStack Affiche la pile des appels actuelle.
<Entrée> Répète la dernière commande s'il s'agit de Step (s),
Step-over (v) ou List (l). Dans les autres cas,
représente une action d'envoi.
?, h Affiche l'aide sur les commandes du débogueur.
Pour quitter le débogueur, utilisez Stop (q).
À partir du débogueur, vous pouvez également entrer des commandes,
afficher la valeur de variables, utiliser des applets de commande
et exécuter des scripts.
En utilisant ces commandes de débogueur, vous pouvez exécuter
un script, vous arrêter sur un point à étudier, 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.
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 façon à commencer par "[DBG]:". Vous pouvez personnaliser
l'invite.
Par ailleurs, dans certaines applications hôtes, telles que la
console Windows PowerShell (mais pas dans l'environnement Windows
PowerShell Integrated Scripting Environnement [ISE]), une invite
imbriquée s'ouvre pour le débogage. Vous pouvez détecter l'invite
imbriquée par le biais des caractères " supérieur à " répétés
(ASCII 62) qui apparaissent à l'invite de commandes.
Par exemple, les éléments suivants correspondent à l'invite de
débogage par défaut de la console Windows PowerShell :
[DBG]: PS (get-location)>>>
Vous pouvez rechercher le niveau d'imbrication à l'aide de la
variable automatique $NestedPromptLevel.
En outre, une variable automatique, $PSDebugContext, est
définie dans l'étendue locale. La présence de la variable
$PsDebugContext permet de déterminer si le débogueur est actif.
Par exemple :
if ($psdebugcontext) {"Debugging"} else {"Not Debugging"}
Vous pouvez utiliser la valeur de la variable $PSDebugContext
lors du débogage.
[DBG]: PS>>> $psdebugcontext.invocationinfo
Name CommandLineParameters UnboundArguments Location
---- --------------------- ---------------- --------
= {} {} C:\ps-test\vote.ps1 (1)
Débogage et étendue
Si vous interrompez l'exécution du débogueur, vous ne modifiez pas
l'étendue dans laquelle il s'exécute, mais lorsque vous atteignez
un point d'arrêt dans un script, vous passez dans l'étendue du script.
L'étendue du script est un élément 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 Get-Alias
ou Get-Variable.
Par exemple, la commande suivante permet d'obtenir les
variables dans l'étendue locale (script) :
get-variable -scope 0
Vous pouvez abréger la commande comme suit :
gv -s 0
Cette méthode s'avère utile pour consulter uniquement les
variables que vous avez définies dans le script et pendant le
débogage.
Débogage au niveau de la ligne de commande
Vous ne pouvez définir un point d'arrêt de variable ou un point
d'arrêt de commande que dans un fichier de script. Toutefois,
le point d'arrêt est défini par défaut sur tout élément
s'exécutant dans la session active.
Par exemple, si vous définissez un point d'arrêt sur la
variable $name, le débogueur s'arrête sur toutes les variables
$name dans tous les scripts, commandes, fonctions, expressions
ou applets de commande de script 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 où ils peuvent être affectés par les fonctions, les
variables et les autres scripts de la session et du profil de
l'utilisateur.
Les points d'arrêt de ligne étant spécifiques aux fichiers de
script, ils sont définis uniquement dans ces fichiers.
Débogage de fonctions
Lorsque vous définissez un point d'arrêt sur une fonction
comportant des sections Begin, Process et 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
Passage en mode débogage. Utilisez h ou ? pour obtenir de
l'aide.
Point d'arrêt de commande sur 'prompt:test-cmdlet'
test-cmdlet
[DBG]: C:\PS> c
Process
Passage en mode débogage. Utilisez h ou ? pour obtenir de
l'aide.
Point d'arrêt de commande sur 'prompt:test-cmdlet'
test-cmdlet
[DBG]: C:\PS> c
End
Passage en mode débogage. Utilisez h ou ? pour obtenir de
l'aide.
Point d'arrêt de commande sur 'prompt:test-cmdlet'
test-cmdlet
[DBG]: C:\PS>
Débogage de scripts distants
Vous ne pouvez pas exécuter le débogueur Windows PowerShell dans une
session à distance. Pour déboguer un script sur un ordinateur distant,
copiez-le sur l'ordinateur local.
La commande suivante copie le script Test.ps1 de l'ordinateur
distant Server01 sur l'ordinateur local :
invoke-command -computername Server01 `
{get-content c:\ps-test\test.ps1} | set-location c:\ps-test\test.ps1
Exemples
Ce script de test détecte la version du système d'exploitation
et affiche un message système approprié. Il inclut une
fonction, un appel de fonction et une variable.
La commande suivante affiche le contenu du fichier script de test :
c:>\PS-test> get-content test.ps1
function psversion {
"Windows Powershell " + $psversiontable.psversion if
($psversiontable.psversion.major -lt 2) {
"Upgrade to Windows PowerShell 2.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 au niveau d'un
élément du script présentant un intérêt, 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 comme suit :
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 correspond à 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 dont vous affichez un aperçu.
Passage en mode débogage. Utilisez h ou ? pour obtenir de
l'aide.
Point d'arrêt de ligne sur '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 variable automatique
$MyInvocation pour définir la valeur de la variable $ScriptName
sur le chemin d'accès et le nom du fichier de script.
DBG> s
test.ps1:11 $scriptname = $MyInvocation.MyCommand.Path
À ce stade, la variable $ScriptName n'est pas remplie, mais
vous pouvez vérifier sa valeur en l'affichant. Dans ce cas, la
valeur est $null.
DBG> $scriptname
DBG>
Utilisez une autre commande Step (s) pour exécuter
l'instruction actuelle et afficher un aperçu de l'instruction
suivante du script. L'instruction suivante appelle la fonction
PsVersion.
DBG> s
test.ps1:12 psversion
À ce stade, la variable $ScriptName est remplie et vous pouvez
vérifier sa valeur en l'affichant. Dans ce cas, la valeur est
définie sur le chemin d'accès 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 "Windows Powershell " +
$psversiontable.psversion
Le message de débogage inclut un aperçu de l'instruction
présente dans la fonction. Pour exécuter cette instruction
et afficher un aperçu de l'instruction suivante de la fonction,
vous pouvez utiliser une commande Step. Toutefois, dans ce cas,
employez une commande Step-Out (o). Elle termine l'exécution de
la fonction (jusqu'à ce qu'elle atteigne un point d'arrêt) et
passe à l'instruction suivante du 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 avons atteint la dernière instruction du
script, les commandes Step, Step-Out et Continue ont le même
effet. Dans ce cas, utilisez Step-Out (o).
Done C:\ps-test\test.ps1
PS C:\ps-test>
La commande Step-Out exécute la dernière commande. L'invite de
commandes standard indique que vous avez quitté le débogueur et
qu'il a redonné le contrôle au processeur de commandes.
Maintenant, réexécutez le débogueur. Tout d'abord, pour
supprimer le point d'arrêt actuel, utilisez les applets de
commande Get-PsBreakpoint et Remove-PsBreakpoint.
(Si vous pensez pouvoir réutiliser le point d'arrêt, employez
l'applet de commande Disable-PsBreakpoint au lieu de
Remove-PsBreakpoint.)
PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint
Vous pouvez abréger cette commande comme suit :
PS C:\ps-test> gbp | rbp
Vous pouvez également exécuter la commande en écrivant une fonction,
semblable à la suivante :
function delbr { gbp | rbp }
À présent, créez un point d'arrêt sur la variable $scriptname.
PS C:\ps-test> set-psbreakpoint -variable scriptname -script test.ps1
Vous pouvez abréger 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
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
Point d'arrêt de variable sur 'C:\ps-test\test.ps1:$scriptname'
(Write access)
test.ps1:11 $scriptname = $MyInvocation.mycommand.path
DBG>
Affichez la valeur actuelle de la variable $scriptname, qui
correspond à $null.
DBG> $scriptname
DBG>
Utilisez une commande Step (s) pour exécuter l'instruction qui
remplit la variable. Affichez ensuite la nouvelle valeur de la
variable $scriptname.
DBG> $scriptname
C:\ps-test\test.ps1
Utilisez une commande Step (s) pour afficher un aperçu de
l'instruction suivante du script.
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 Step-Over (v). Si vous vous trouvez déjà dans la
fonction lorsque vous utilisez Step-Over, la commande n'a pas
d'effet. L'appel de fonction s'affiche, mais 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 Step-Over exécute la fonction et affiche un aperçu de
l'instruction suivante du script, qui affiche la dernière ligne.
Utilisez une commande Stop (t) pour quitter le débogueur.
L'invite de commandes standard est rétablie.
C:\ps-test>
Pour supprimer les points d'arrêt, utilisez les applets de
commande Get-PsBreakpoint et Remove-PsBreakpoint.
PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint
Créez un point d'arrêt de commande sur la fonction PsVersion.
PS C:\ps-test> Set-PsBreakpoint -command psversion -script test.ps1
Vous pouvez abréger cette commande comme suit :
PS C:\ps-test> sbp -c psversion -s test.ps1
À présent, exécutez le script.
PS C:\ps-test> .\test.ps1
Point d'arrêt de commande sur 'C:\ps-test\test.ps1:psversion'
test.ps1:12 psversion
DBG>
Le script atteint le point d'arrêt à l'appel de la fonction. À
ce stade, la fonction n'a pas encore été appelée. Cela vous permet
d'utiliser le paramètre Action de Set-PsBreakpoint afin de définir des
conditions pour l'exécution du point d'arrêt ou d'effectuer des tâches de
préparation ou de diagnostic, telles que le démarrage d'un journal ou bien
encore l'appel d'un script de diagnostic ou de sécurité.
Pour définir une action, utilisez une commande Continue (c)
pour quitter le script et une commande Remove-PsBreakpoint 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 point d'arrêt de commande avec une action.
La commande ci-dessous définit un point d'arrêt de commande avec une
action qui enregistre la valeur de la variable $scriptname lorsque
la fonction est appelée. Étant donné que le mot clé Break n'est pas
utilisé dans l'action, l'exécution ne s'arrête pas. (Le symbole de
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 définissant des
conditions pour le point d'arrêt. Dans la commande ci-dessous,
le point d'arrêt de commande est exécuté uniquement si la stratégie
d'exécution est définie sur RemoteSigned, qui correspond à la
stratégie la plus restrictive permettant d'exécuter des scripts.
(Le symbole de 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 }}
Le mot clé Break de l'action demande au débogueur d'exécuter
le point d'arrêt. Vous pouvez également utiliser le mot clé
Continue pour demander au débogueur de procéder à l'exécution sans
interruption. Étant donné que le 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
Point d'arrêt de commande sur '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 la fonction.
À ce stade, vous pouvez vérifier la pile des appels. Utilisez
l'applet de commande Get-PsCallStack ou la commande de débogueur
Get-PsCallStack (k). La commande suivante permet d'obtenir
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 Windows PowerShell.
Pour plus d'informations sur les applets de commande de
débogueur, tapez la commande suivante :
help <nom de l'applet de commande> -full
Par exemple, tapez :
help set-psbreakpoint -full
VOIR AUSSI
Disable-PsBreakpoint
Get-PsBreakpoint
Remove-PsBreakpoint
Set-PsBreakpoint
Set-PsDebug
Set-Strictmode
Write-Debug
Write-Verbose
Enable-PsBreakpoint
Get-PsCallStack