{{tag>dev powershell debogage}}


====== PowerShell : Débogage des scripts ======

===== Généralités =====

Lorsque des erreurs se produisent, elles sont stockées dans le tableau **$Error**. Quand une nouvelle erreur est générée, elle est insérée à $Error[0], et l’index des autres erreurs est augmenté d’une unité.

Pour rendre le texte de résolution des problèmes plus facilement identifiable, il existe les cmdlets **Write-Warning**, **Write-Verbose** ou **Write-Debug**


===== Utilisation des switchs Verbose et Debug =====

Un script ou une fonction peut se comporter comme une cmdlet compilée si on lui ajoute l'attribut ''CmdletBinding''. On ajoute l'attribut en utilisant le décorateur ''[CmdletBinding()]'' dans le bloc **Param()**. Une fois l'attribut spécifié, on peut utiliser les options existantes sur les cmdlets compilées comme les switchs ''-Verbose'' et ''-Debug''.


<code powershell>
Param(
   [CmdletBinding()]
   [Parameter(Mandatory)]
   [ValidateSet("Low","Average","High")]
   [String] $BatteryLevel
)


Write-Host "Niveau de batterie : ${1}", $SBatteryLevel

# Ce message n'est affiché que si l'option -Verbose est spécifiée lors de l'appel
Write-Verbose 'Ceci est un message supplémentaire pour mode verbeux'

# Ce message n'est affiché que si l'option -Debug est spécifiée lors de l'appel
Write-Debug 'Ceci est un message de debogage de script'
</code>

L'appel du script sans option :
<code powershell>
.\aTestScript.ps1 -BatteryLevel Low
Niveau de batterie :  Low
</code>

Si le script est appelé avec l'option ''-Verbose'' :
<code powershell>
.\aTestScript.ps1 -BatteryLevel Low -Verbose
Niveau de batterie :  Low
COMMENTAIRES : Ceci est un message supplémentaire pour mode verbeux
</code>

Si le script est appelé avec l'option -Debug :
<code powershell>
.\aTestScript.ps1 -BatteryLevel Low -Debug
Niveau de batterie :  Low
DÉBOGUER : Ceci est un message de debogage de script
</code>

===== Exécution du débogueur =====

L'appel de la cmdlet **Wait-Debugger** dans le script permet de basculer l’exécution du script en mode débogage.

<code powershell>
# L'execution sera stoppée à partir d'ici
Wait-Debugger
</code>

Une console en mode interactif est disponible dans le débogueur, le prompt contient **[DBG]**, saisir <key>?</key> pour afficher les commandes disponibles.


===== Utiliser les points d'arrêts =====

Le point d'arrêt suspend l'exécution du script et bascule en mode débogage : une invite de commande en mode interactif est disponible dans le contexte d'exécution du script. On peut ainsi afficher les valeurs des variables taper des commandes de débogage et analyser le comportement du script pas à pas.

Plusieurs options existent pour la création de points d'arrêts notamment :
  * ''-Line'' : stoppe l'exécution à la ligne spécifiée ;
  * ''-Variable'' : stoppe l’exécution lors de l'accès en lecture/écriture ;
  * ''-Command'' : stoppe l'exécution sur une commande spécifiée.
  
<code powershell>
# Depuis la console on peut définir un ou plusieurs points d'arrêts

# Stoppera l'execution du script à la ligne 10
Set-PSBreakpoint -Script '.\aTestScript.ps1' -Line 10

# Stoppera l'exécution du script à la lecture de la la variable BatteryLevel
Set-PSBreakpoint -Script .\aTestScript.ps1 -Variable BatteryLevel -Mode Read

# Stoppera l'execution du script lors d'un appel a Write-Verbose
Set-PSBreakpoint -Script .\aTestScript.ps1 -Command Write-Verbose
</code>

A ce stade les points d'arrêts sont définis mais le script n'a pas été lancé. Pour lister les points d'arrêts :

<code powershell>
# Lister les points d'arrêts existants
Get-PSBreakpoint

  ID Script                                 Line Command                                Variable                               Action
  -- ------                                 ---- -------                                --------                               ------
   1 aTestScript.ps1                          10
   2 aTestScript.ps1                                                                    BatteryLevel
   3 aTestScript.ps1                             Write-Verbose
</code>

On appelle le script depuis la console, il bascule en mode débogage dès qu'un point d'arrêt est rencontré:
<code powershell>
.\aTestScript.ps1 -BatteryLevel High
Appuyez sur Point d'arrêt de ligne sur « C:\Users\yoann\dev\aTestScript.ps1:10 »

Au caractère C:\Users\yoann\dev\aTestScript.ps1:10 : 6
+ For ($i=0; $i -lt 3; $i++) {
+      ~~~~
[DBG]: PS C:\Users\yoann\dev>>
</code>

===== Supprimer les points d'arrêts =====

Chaque point d'arrêt a un identifiant affiché par **Get-PSBreakpoint**. Utiliser la cmdlet **Remove-PSBreakpoint** pour supprimer les points d'arrêts après utilisation.

<code powershell>
Remove-PSBreakpoint -Id 1
Remove-PSBreakpoint -Id 2 
Remove-PSBreakpoint -Id 3
</code>

===== Gestion des erreurs =====

Quand une commande PowerShell génère une erreur, il peut s’agir d’une erreur avec fin d’exécution (si le traitement ne peut pas se poursuivre) ou d’une erreur sans fin d’exécution. La variable globale **$ErrorActionPreference** permet à l'utilisateur de définir le comportement par défaut à appliquer lorsqu' une erreur sans fin d’exécution est rencontrée :

Les différents valeurs possibles sont :

^ Continue | Afficher le message et continue l'exécution (valeur par défaut) |
^ SilentlyContinue | Continue l'exécution sans affichage des messages. |
^ Inquire | Interrompt l’exécution et demande à l'utilisateur.|
^ Stop | Devra  être géré par le script comme une erreur avec fin d’exécution via les exceptions ou provoquera l'arrêt du script. |


<code powershell>
# Redéfinit le comportement par défaut des erreurs sans fin d’exécution
# pour le processus courant. Demande à l'utilisateur
$ErrorActionPreference = 'Inquire'

</code>
===== Références =====

  * https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-5.1
  * https://www.youtube.com/watch?v=TCs8KmyZCgs