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




Table des matières