Set-PSBreakpoint

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

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

Syntax

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

Description

L’applet Set-PSBreakpoint de commande 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 impossible de 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 Set-PSBreakpoint commande 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 Set-PSBreakpoint commande, mais chaque Set-PSBreakpoint commande ne définit qu’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 change 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 Set-PSBreakpoint de commande 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 Set-PSBreakpoint de commande 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 Increment fonction dans l’applet de commande Sample.ps1. Le script arrête l'exécution juste 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 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 Serveur 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 commençant par « write », par Write-Hostexemple .

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 DiskTest fonction dans le Test.ps1 script uniquement lorsque la valeur de la $Disk variable 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 $Disk variable dans la fonction.

L’action utilise le break mot clé 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 CheckLog fonction. Comme la commande ne spécifie pas de script, le point d'arrêt est défini sur n'importe quel élément qui s'exécute dans la session active. Le débogueur s'arrête quand 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. Elle définit un point d'arrêt sur la colonne 2 de 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

Exemple 8 : Définir un point d’arrêt dans un espace d’exécution

Dans cet exemple, un travail est démarré. L’instance d’exécution est stockée dans une variable et passée à la commande Set-PSBreakPoint avec le paramètre Runspace.

Start-Job -ScriptBlock {
    Start-Sleep -Seconds 10
}

$runspace = Get-Runspace -Id 1

Set-PSBreakpoint -Command Start-Sleep -Runspace $runspace

Paramètres

-Action

Spécifie les commandes qui s'exécutent à chaque point d'arrêt au lieu de s'arrêter. 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 exécuter d'autres tâches, comme les tests ou la journalisation.

Si ce paramètre est omis ou qu'aucune action n'est spécifiées, 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 d’action s’exécute à chaque point d’arrêt. L'exécution ne s'interrompt pas, à moins que le bloc de script ne comporte le mot clé Break. Si vous utilisez le mot clé Continue 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_Break et about_Continue.

Type:ScriptBlock
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Column

Spécifie le numéro de colonne du 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 Line 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 numérotées à partir de la marge gauche en commençant par le numéro 1 (pas 0). Si vous spécifiez une colonne qui n'existe pas dans le script, aucune erreur n'est déclarée, mais le point d'arrêt n'est jamais exécuté.

Type:Int32
Position:2
Default value:1
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Command

Définit un point d'arrêt de commande. Entrez des noms d’applet de commande, tels que Get-Processdes noms de fonction ou des noms de fonctions. 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, ainsi que sur chaque section BEGIN, PROCESS et END.

Type:String[]
Aliases:C
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters: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 une virgule. PowerShell s’arrête immédiatement avant d’exécuter l’instruction qui commence sur chacune des lignes spécifiées.

Les lignes sont numérotées à partir de la marge gauche du fichier de script en commençant par le numéro 1 (pas 0). Si vous spécifiez une ligne vierge, l'exécution s'arrête avant la prochaine ligne non vide. Si la ligne est en dehors de la plage, le point d'arrêt n'est jamais atteint.

Type:Int32[]
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters: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 Write.

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 valides pour ce paramètre sont :

  • Écriture : arrête l’exécution immédiatement avant qu’une nouvelle valeur soit écrite 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
Accepted values:Read, Write, ReadWrite
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Runspace

Spécifie l’ID d’un objet Runspace afin que vous puissiez interagir avec des points d’arrêt dans l’espace d’exécution spécifié.

Ce paramètre a été ajouté dans PowerShell 7.2.

Type:Runspace
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 de plusieurs fichiers de script. Si les fichiers se trouvent dans le répertoire actif, vous pouvez ignorer le chemin d'accès. Les caractères génériques sont autorisés.

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

Type:String[]
Position:0
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 avant qu'une nouvelle valeur ne soit écrite dans la variable.

Type:String[]
Aliases:V
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

Entrées

None

Vous ne pouvez pas diriger les objets vers cette applet de commande.

Sorties

CommandBreakpoint

LineBreakpoint

VariableBreakpoint

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

Notes

PowerShell inclut les alias suivants pour Set-PSBreakpoint:

  • Toutes les plateformes :

    • sbp

  • Set-PSBreakpoint impossible de 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.

  • Lors de la définition d'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 la création de la fonction ou variable.