Set-PSBreakpoint

  • Referenz
Modul:
Microsoft.PowerShell.Utility

Legt einen Haltepunkt in einer Zeile, einem Befehl oder einer Variable fest.

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>]

Beschreibung

Das Set-PSBreakpoint Cmdlet legt einen Haltepunkt in einem Skript oder in einem beliebigen Befehl fest, der in der aktuellen Sitzung ausgeführt wird. Sie können Set-PSBreakpoint einen Haltepunkt festlegen, bevor Sie ein Skript ausführen oder einen Befehl ausführen oder während des Debuggens, wenn an einem anderen Haltepunkt angehalten wird.

Set-PSBreakpoint Auf einem Remotecomputer kann kein Haltepunkt festgelegt werden. Um ein Skript auf einem Remotecomputer zu debuggen, kopieren Sie das Skript auf den lokalen Computer, und debuggen Sie es dann lokal.

Jeder Set-PSBreakpoint Befehl erstellt einen der folgenden drei Typen von Haltepunkten:

  • Zeilenumbruchpunkt – Legt Haltepunkte an bestimmten Linien- und Spaltenkoordinaten fest.
  • Befehlshaltepunkt – Legt Haltepunkte für Befehle und Funktionen fest.
  • Variabler Haltepunkt – Legt Haltepunkte für Variablen fest.

Sie können einen Haltepunkt für mehrere Zeilen, Befehle oder Variablen in einem einzigen Set-PSBreakpoint Befehl festlegen, aber jeder Set-PSBreakpoint Befehl legt nur einen Haltepunkttyp fest.

An einem Haltepunkt beendet PowerShell vorübergehend die Ausführung und gibt dem Debugger die Steuerung. Die Eingabeaufforderung ändert sich in DBG\>, und eine Reihe von Debuggerbefehlen sind für die Verwendung verfügbar. Sie können jedoch den Aktionsparameter verwenden, um eine alternative Antwort anzugeben, z. B. Bedingungen für den Haltepunkt oder Anweisungen zum Ausführen zusätzlicher Aufgaben wie Protokollierung oder Diagnose.

Das Set-PSBreakpoint Cmdlet ist eines von mehreren Cmdlets zum Debuggen von PowerShell-Skripts. Weitere Informationen zum PowerShell-Debugger finden Sie unter about_Debuggers.

Beispiele

Beispiel 1: Festlegen eines Haltepunkts in einer Zeile

In diesem Beispiel wird ein Haltepunkt in Zeile 5 im Skript "Sample.ps1" festgelegt. Wenn das Skript ausgeführt wird, wird die Ausführung unmittelbar vor Zeile 5 beendet.

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

Wenn Sie einen neuen Haltepunkt nach Zeilennummer festlegen, generiert das Set-PSBreakpoint Cmdlet ein Zeilenhaltepunktobjekt (System.Management.Automation.LineBreakpoint), das die Haltepunkt-ID und die Trefferanzahl enthält.

Beispiel 2: Festlegen eines Haltepunkts für eine Funktion

In diesem Beispiel wird ein Befehlstrennpunkt für die Increment Funktion im Cmdlet Sample.ps1 erstellt. Das Skript wird unmittelbar vor jedem Aufruf der angegebenen Funktion beendet.

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

Das Ergebnis ist ein Befehlshaltepunktobjekt. Bevor das Skript ausgeführt wird, ist der Wert der HitCount-Eigenschaft 0.

Beispiel 3: Festlegen eines Haltepunkts für eine Variable

In diesem Beispiel wird ein Haltepunkt für die Servervariable im Skript Sample.ps1 festgelegt. Er verwendet den Parameter Mode mit dem Wert "ReadWrite ", um die Ausführung zu beenden, wenn der Wert der Variablen gelesen wird und unmittelbar bevor der Wert geändert wird.

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

Beispiel 4: Festlegen eines Haltepunkts für jeden Befehl, der mit angegebenem Text beginnt

In diesem Beispiel wird für jeden Befehl im Skript "Sample.ps1" ein Haltepunkt festgelegt, der mit "write" beginnt, z Write-Host. B. .

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

Beispiel 5: Festlegen eines Haltepunkts abhängig vom Wert einer Variablen

In diesem Beispiel wird die DiskTest Ausführung der Funktion im Test.ps1 Skript nur beendet, wenn der Wert der $Disk Variablen größer als 2 ist.

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

Der Wert der Aktion ist ein Skriptblock, der den Wert der $Disk Variablen in der Funktion testet.

Die Aktion verwendet die break Schlüsselwort (keyword), um die Ausführung zu beenden, wenn die Bedingung erfüllt ist. Die Alternative (und die Standardeinstellung) ist "Continue".

Beispiel 6: Festlegen eines Haltepunkts für eine Funktion

In diesem Beispiel wird ein Haltepunkt für die CheckLog Funktion festgelegt. Da der Befehl kein Skript angibt, wird der Haltepunkt für alles festgelegt, was in der aktuellen Sitzung ausgeführt wird. Der Debugger wird unterbrochen, sobald die Funktion aufgerufen wird, nicht wenn sie deklariert wird.

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'

Beispiel 7: Festlegen von Haltepunkten in mehreren Zeilen

In diesem Beispiel werden drei Zeilenumbruchpunkte im Skript Sample.ps1 festgelegt. Es wird ein Haltepunkt in Spalte 2 für jede im Skript angegebene Zeile festgelegt. Die im Parameter "Action " angegebene Aktion gilt für alle Haltepunkte.

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

Beispiel 8: Festlegen eines Haltepunkts in einem Runspace

In diesem Beispiel wird ein Auftrag gestartet. Der Runspace wird in einer Variablen gespeichert und mit dem Runspace-Parameter an den Set-PSBreakPoint-Befehl übergeben.

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

$runspace = Get-Runspace -Id 1

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

Parameter

-Action

Gibt die Befehle an, die an jedem Haltepunkt ausgeführt werden, anstatt unterbrochen zu werden. Geben Sie einen Skriptblock ein, der die Befehle enthält. Sie können diesen Parameter verwenden, um bedingte Haltepunkte festzulegen oder um andere Aufgaben auszuführen, z. B. Tests oder Protokollierung.

Wenn dieser Parameter nicht festgelegt ist oder keine Aktion angegeben ist, wird die Ausführung am Haltepunkt beendet, und der Debugger startet.

Wenn der Aktionsparameter verwendet wird, wird der Aktionsskriptblock an jedem Haltepunkt ausgeführt. Die Ausführung wird nicht beendet, es sei denn, der Skriptblock enthält das Schlüsselwort „Break“. Wenn Sie im Skriptblock das Schlüsselwort „Continue“ verwenden, wird die Ausführung bis zum nächsten Haltepunkt fortgesetzt.

Weitere Informationen finden Sie unter about_Script_Blocks, about_Break und about_Continue.

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

-Column

Gibt die Spaltennummer der Spalte in der Skriptdatei an, bei der die Ausführung angehalten wird. Geben Sie nur eine Spaltennummer an. Der Standardwert ist „Spalte 1“.

Der Wert "Column" wird mit dem Wert des Parameters "Line " verwendet, um den Haltepunkt anzugeben. Wenn der Parameter Line mehrere Zeilen angibt, legt der Parameter Column einen Haltepunkt an der angegebenen Spalte in jeder der angegebenen Zeilen fest. PowerShell beendet die Ausführung vor der Anweisung oder dem Ausdruck, die das Zeichen an der angegebenen Zeilen- und Spaltenposition enthält.

Spalten werden vom oberen linken Rand aus beginnend mit Spaltennummer 1 (nicht 0) gezählt. Wenn Sie eine Spalte angeben, die sich nicht im Skript befindet, wird kein Fehler ausgegeben, doch der Haltepunkt wird nie ausgeführt.

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

-Command

Legt einen Befehlshaltepunkt fest. Geben Sie Cmdlet-Namen ein, z Get-Process. B. Funktionsnamen. Platzhalter sind zulässig.

Die Ausführung wird sofort angehalten, bevor jede Instanz des jeweiligen Befehls ausgeführt wird. Wenn der Befehl eine Funktion ist, wird die Ausführung jedes Mal angehalten, wenn die Funktion aufgerufen wird, sowie bei jedem BEGIN-, PROCESS- und END-Abschnitt.

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

-Line

Legt einen Zeilenhaltepunkt in einem Skript fest. Geben Sie mindestens eine durch Kommas getrennte Zeilennummer ein. PowerShell stoppt unmittelbar vor dem Ausführen der Anweisung, die für jede der angegebenen Zeilen beginnt.

Zeilen werden vom oberen linken Rand der Skriptdatei aus beginnend mit Zeilennummer 1 (nicht 0) gezählt. Wenn Sie eine leere Zeile angeben, endet die Ausführung vor der nächsten nicht leeren Zeile. Wenn die Zeile außerhalb des Bereichs liegt, wird der Haltepunkt niemals erreicht.

Type:Int32[]
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Mode

Gibt den Zugriffsmodus an, der variable Haltepunkte auslöst. Der Standardwert ist Write.

Dieser Parameter ist nur gültig, wenn der Parameter Variable im Befehl verwendet wird. Der Modus gilt für alle im Befehl festgelegten Haltepunkte. Zulässige Werte für diesen Parameter:

  • Write – Stoppt die Ausführung unmittelbar, bevor ein neuer Wert in die Variable geschrieben wird.
  • Lesen – Beendet die Ausführung, wenn die Variable gelesen wird, d. h., wenn auf den Wert zugegriffen wird, entweder zugewiesen, angezeigt oder verwendet werden soll. Im Lesemodus wird die Ausführung nicht beendet, wenn sich der Wert der Variablen ändert.
  • ReadWrite – Beendet die Ausführung, wenn die Variable gelesen oder geschrieben wird.
Type:VariableAccessMode
Accepted values:Read, Write, ReadWrite
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Runspace

Gibt die ID eines Runspace-Objekts an, damit Sie mit Haltepunkten im angegebenen Runspace interagieren können.

Dieser Parameter wurde in PowerShell 7.2 hinzugefügt.

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

-Script

Gibt ein Array von Skriptdateien an, in denen dieses Cmdlet einen Haltepunkt festlegt. Geben Sie die Pfade und Dateinamen von mindestens einer Datei ein. Wenn die Dateien sich im aktuellen Verzeichnis befinden, können Sie den Pfad weglassen. Platzhalter sind zulässig.

Standardmäßig werden Variablenhaltepunkte und Befehlshaltepunkte für einen beliebigen Befehl festgelegt, der in der aktuellen Sitzung ausgeführt wird. Dieser Parameter ist nur erforderlich, wenn Sie einen Zeilenhaltepunkt festlegen.

Type:String[]
Position:0
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Variable

Gibt ein Array von Variablen an, für das dieses Cmdlet Haltepunkte festlegt. Geben Sie eine durch Trennzeichen getrennte Liste von Variablen ohne Dollarzeichen ($) ein.

Verwenden Sie den Parameter Mode , um den Zugriffsmodus zu bestimmen, der die Haltepunkte auslöst. Der Standardmodus „Write“ beendet die Ausführung, kurz bevor ein neuer Wert in die Variable geschrieben wird.

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

Eingaben

None

Sie können keine Objekte an dieses Cmdlet weiterleiten.

Ausgaben

CommandBreakpoint

LineBreakpoint

VariableBreakpoint

Set-PSBreakpoint gibt ein Objekt zurück, das jeden von ihr festgelegten Haltepunkt darstellt.

Hinweise

PowerShell enthält die folgenden Aliase für Set-PSBreakpoint:

  • Alle Plattformen:

    • sbp

  • Set-PSBreakpoint Auf einem Remotecomputer kann kein Haltepunkt festgelegt werden. Um ein Skript auf einem Remotecomputer zu debuggen, kopieren Sie das Skript auf den lokalen Computer, und debuggen Sie es dann lokal.

  • Wenn Sie einen Haltepunkt für mehr als eine Zeile, einen Befehl oder eine Variable festlegen, Set-PSBreakpoint wird für jeden Eintrag ein Haltepunktobjekt generiert.

  • Beim Festlegen eines Haltepunkts für eine Funktion oder Variable an der Eingabeaufforderung können Sie den Haltepunkt festlegen, bevor oder nachdem Sie die Funktion oder Variable erstellen.