Partager via

Set-PSBreakpoint

  • Référence
Module:
Microsoft.PowerShell.Utility

Définit un point d’arrêt sur une ligne, une commande ou une variable.

Syntaxe

Set-PSBreakpoint
   [-Action <ScriptBlock>]
   [[-Column] <Int32>]
   [-Line] <Int32[]>
   [-Script] <String[]>
   [<CommonParameters>]
Set-PSBreakpoint
   [-Action <ScriptBlock>]
   -Command <String[]>
   [[-Script] <String[]>]
   [<CommonParameters>]
Set-PSBreakpoint
   [-Action <ScriptBlock>]
   [[-Script] <String[]>]
   -Variable <String[]>
   [-Mode <VariableAccessMode>]
   [<CommonParameters>]

Description

L’applet de commande Set-PSBreakpoint définit un point d’arrêt dans un script ou dans une commande exécutée dans la session active. Vous pouvez utiliser Set-PSBreakpoint pour définir un point d’arrêt avant d’exécuter un script ou d’exécuter une commande, ou pendant le débogage, lorsqu’il est arrêté à un autre point d’arrêt.

Set-PSBreakpoint ne peut pas définir un point d’arrêt sur un ordinateur distant. Pour déboguer un script sur un ordinateur distant, copiez le script sur l’ordinateur local, puis déboguez-le localement.

Chaque commande Set-PSBreakpoint crée l’un des trois types suivants de points d’arrêt :

  • Point d’arrêt de ligne : définit des points d’arrêt à des coordonnées de ligne et de colonne particulières.
  • Point d’arrêt de commande : définit des points d’arrêt sur les commandes et les fonctions.
  • Point d’arrêt de variable : définit des points d’arrêt sur des variables.

Vous pouvez définir un point d’arrêt sur plusieurs lignes, commandes ou variables dans une seule commande Set-PSBreakpoint, mais chaque commande Set-PSBreakpoint définit un seul type de point d’arrêt.

À un point d’arrêt, PowerShell arrête temporairement l’exécution et donne le contrôle au débogueur. L’invite de commandes passe à DBG\>, et un ensemble de commandes de débogueur deviennent disponibles pour une utilisation. Toutefois, vous pouvez utiliser le paramètre Action pour spécifier une autre réponse, telle que des conditions pour le point d’arrêt ou des instructions pour effectuer des tâches supplémentaires telles que la journalisation ou les diagnostics.

L’applet de commande Set-PSBreakpoint est l’une des plusieurs applets de commande conçues pour le débogage de scripts PowerShell. Pour plus d’informations sur le débogueur PowerShell, consultez about_Debuggers.

Exemples

Exemple 1 : Définir un point d’arrêt sur une ligne

Cet exemple montre comment définir un point d’arrêt à la ligne 5 du script Sample.ps1. Lorsque le script s’exécute, l’exécution s’arrête immédiatement avant l’exécution de la ligne 5.

Set-PSBreakpoint -Script "sample.ps1" -Line 5

Column     : 0
Line       : 5
Action     :
Enabled    : True
HitCount   : 0
Id         : 0
Script     : C:\ps-test\sample.ps1
ScriptName : C:\ps-test\sample.ps1

Lorsque vous définissez un nouveau point d’arrêt par numéro de ligne, l’applet de commande Set-PSBreakpoint génère un objet de point d’arrêt de ligne (System.Management.Automation.LineBreakpoint) qui inclut l’ID de point d’arrêt et le nombre d’accès.

Exemple 2 : Définir un point d’arrêt sur une fonction

Cet exemple crée un point d’arrêt de commande sur la fonction Increment dans l’applet de commande Sample.ps1. Le script arrête l’exécution immédiatement avant chaque appel à la fonction spécifiée.

Set-PSBreakpoint -Command "Increment" -Script "sample.ps1"

Command    : Increment
Action     :
Enabled    : True
HitCount   : 0
Id         : 1
Script     : C:\ps-test\sample.ps1
ScriptName : C:\ps-test\sample.ps1

Le résultat est un objet de point d’arrêt de commande. Avant l’exécution du script, la valeur de la propriété HitCount est 0.

Exemple 3 : Définir un point d’arrêt sur une variable

Cet exemple montre comment définir un point d’arrêt sur la variable Server dans le script Sample.ps1. Il utilise le paramètre Mode avec la valeur ReadWrite pour arrêter l’exécution lorsque la valeur de la variable est lue et juste avant la modification de la valeur.

Set-PSBreakpoint -Script "sample.ps1" -Variable "Server" -Mode ReadWrite

Exemple 4 : Définir un point d’arrêt sur chaque commande commençant par du texte spécifié

Cet exemple montre comment définir un point d’arrêt sur chaque commande du script Sample.ps1 qui commence par « write », par exemple Write-Host.

Set-PSBreakpoint -Script Sample.ps1 -Command "write*"

Exemple 5 : Définir un point d’arrêt en fonction de la valeur d’une variable

Cet exemple arrête l’exécution à la fonction DiskTest dans le script Test.ps1 uniquement lorsque la valeur de la variable $Disk est supérieure à 2.

Set-PSBreakpoint -Script "test.ps1" -Command "DiskTest" -Action { if ($Disk -gt 2) { break } }

La valeur de l'Action est un bloc de script qui teste la valeur de la variable $Disk dans la fonction.

L’action utilise le mot clé break pour arrêter l’exécution si la condition est remplie. L’alternative (et la valeur par défaut) est Continuer.

Exemple 6 : Définir un point d’arrêt sur une fonction

Cet exemple montre comment définir un point d’arrêt sur la fonction CheckLog. Étant donné que la commande ne spécifie pas de script, le point d’arrêt est défini sur tout ce qui s’exécute dans la session active. Le débogueur s’arrête lorsque la fonction est appelée, et non quand elle est déclarée.

PS> Set-PSBreakpoint -Command "checklog"
Id       : 0
Command  : checklog
Enabled  : True
HitCount : 0
Action   :

function CheckLog {
>> get-eventlog -log Application |
>> where {($_.source -like "TestApp") -and ($_.Message -like "*failed*")}
>>}
>>
PS> Checklog
DEBUG: Hit breakpoint(s)
DEBUG:  Function breakpoint on 'prompt:Checklog'

Exemple 7 : Définir des points d’arrêt sur plusieurs lignes

Cet exemple montre comment définir trois points d’arrêt de ligne dans le script Sample.ps1. Il définit un point d’arrêt à la colonne 2 sur chacune des lignes spécifiées dans le script. L’action spécifiée dans le paramètre Action s’applique à tous les points d’arrêt.

PS C:\> Set-PSBreakpoint -Script "sample.ps1" -Line 1, 14, 19 -Column 2 -Action {&(log.ps1)}

Column     : 2
Line       : 1
Action     :
Enabled    : True
HitCount   : 0
Id         : 6
Script     : C:\ps-test\sample.ps1
ScriptName : C:\ps-test\sample.ps1


Column     : 2
Line       : 14
Action     :
Enabled    : True
HitCount   : 0
Id         : 7
Script     : C:\ps-test\sample.ps1
ScriptName : C:\ps-test\sample.ps1


Column     : 2
Line       : 19
Action     :
Enabled    : True
HitCount   : 0
Id         : 8
Script     : C:\ps-test\sample.ps1
ScriptName : C:\ps-test\sample.ps1

Paramètres

-Action

Spécifie les commandes qui s’exécutent à chaque point d’arrêt au lieu de rompre. Entrez un bloc de script qui contient les commandes. Vous pouvez utiliser ce paramètre pour définir des points d’arrêt conditionnels ou pour effectuer d’autres tâches, telles que le test ou la journalisation.

Si ce paramètre est omis ou qu’aucune action n’est spécifiée, l’exécution s’arrête au point d’arrêt et le débogueur démarre.

Lorsque le paramètre Action est utilisé, le bloc de script Action s’exécute à chaque point d’arrêt. L’exécution ne s’arrête pas, sauf si le bloc de script inclut le mot clé Break. Si vous utilisez le mot clé Continuer dans le bloc de script, l’exécution reprend jusqu’au point d’arrêt suivant.

Pour plus d’informations, consultez about_Script_Blocks, about_Breaket about_Continue.

Type:ScriptBlock
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Column

Spécifie le numéro de colonne de la colonne dans le fichier de script sur lequel l’exécution s’arrête. Entrez un seul numéro de colonne. La valeur par défaut est la colonne 1.

La valeur column est utilisée avec la valeur du paramètre Line pour spécifier le point d’arrêt. Si le paramètre ligne de spécifie plusieurs lignes, le paramètre Column définit un point d’arrêt à la colonne spécifiée sur chacune des lignes spécifiées. PowerShell arrête l’exécution avant l’instruction ou l’expression qui inclut le caractère à la position de ligne et de colonne spécifiée.

Les colonnes sont comptées à partir de la marge supérieure gauche commençant par le numéro de colonne 1 (et non 0). Si vous spécifiez une colonne qui n’existe pas dans le script, une erreur n’est pas déclarée, mais le point d’arrêt n’est jamais exécuté.

Type:Int32
Position:2
Valeur par défaut:1
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Command

Définit un point d’arrêt de commande. Entrez des noms d’applets de commande, tels que Get-Processou des noms de fonction. Les caractères génériques sont autorisés.

L’exécution s’arrête juste avant l’exécution de chaque instance de chaque commande. Si la commande est une fonction, l’exécution s’arrête chaque fois que la fonction est appelée et à chaque section BEGIN, PROCESS et END.

Type:String[]
Alias:C
Position:Named
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:True

-Line

Définit un point d’arrêt de ligne dans un script. Entrez un ou plusieurs numéros de ligne, séparés par des virgules. PowerShell s’arrête immédiatement avant d’exécuter l’instruction qui commence sur chacune des lignes spécifiées.

Les lignes sont comptées à partir de la marge supérieure gauche du fichier de script commençant par le numéro de ligne 1 (et non 0). Si vous spécifiez une ligne vide, l’exécution s’arrête avant la ligne non vide suivante. Si la ligne est hors limites, le point d’arrêt n’est jamais atteint.

Type:Int32[]
Position:1
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Mode

Spécifie le mode d’accès qui déclenche des points d’arrêt de variables. La valeur par défaut est d’écriture .

Ce paramètre est valide uniquement lorsque le paramètre variable est utilisé dans la commande. Le mode s’applique à tous les points d’arrêt définis dans la commande. Les valeurs acceptables pour ce paramètre sont les suivantes :

  • écriture : arrête l’exécution immédiatement avant l’écriture d’une nouvelle valeur dans la variable.
  • Lecture : arrête l’exécution lorsque la variable est lue, c’est-à-dire lorsque sa valeur est accessible, à attribuer, afficher ou utiliser. En mode lecture, l’exécution ne s’arrête pas lorsque la valeur de la variable change.
  • ReadWrite : arrête l’exécution lorsque la variable est lue ou écrite.
Type:VariableAccessMode
Valeurs acceptées:Read, Write, ReadWrite
Position:Named
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Script

Spécifie un tableau de fichiers de script dans lequel cette applet de commande définit un point d’arrêt. Entrez les chemins d’accès et les noms de fichiers d’un ou plusieurs fichiers de script. Si les fichiers se trouvent dans le répertoire actif, vous pouvez omettre le chemin d’accès. Les caractères génériques sont autorisés.

Par défaut, les points d’arrêt de variable et les points d’arrêt de commande sont définis sur n’importe quelle commande qui s’exécute dans la session active. Ce paramètre est obligatoire uniquement lors de la définition d’un point d’arrêt de ligne.

Type:String[]
Position:0
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Variable

Spécifie un tableau de variables sur lesquelles cette applet de commande définit des points d’arrêt. Entrez une liste séparée par des virgules de variables sans signes dollar ($).

Utilisez le paramètre mode pour déterminer le mode d’accès qui déclenche les points d’arrêt. Le mode par défaut, Write, arrête l’exécution juste avant qu’une nouvelle valeur soit écrite dans la variable.

Type:String[]
Alias:V
Position:Named
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

Entrées

None

Vous ne pouvez pas diriger l’entrée vers Set-PSBreakpoint.

Sorties

Breakpoint object (System.Management.Automation.LineBreakpoint, System.Management.Automation.VariableBreakpoint, System.Management.Automation.CommandBreakpoint)

Set-PSBreakpoint retourne un objet qui représente chaque point d’arrêt qu’il définit.

Notes

  • Set-PSBreakpoint ne peut pas définir un point d’arrêt sur un ordinateur distant. Pour déboguer un script sur un ordinateur distant, copiez le script sur l’ordinateur local, puis déboguez-le localement.
  • Lorsque vous définissez un point d’arrêt sur plusieurs lignes, commandes ou variables, Set-PSBreakpoint génère un objet de point d’arrêt pour chaque entrée.
  • Lorsque vous définissez un point d’arrêt sur une fonction ou une variable à l’invite de commandes, vous pouvez définir le point d’arrêt avant ou après avoir créé la fonction ou la variable.