Freigeben über

Set-PSBreakpoint

  • Referenz
Modul:
Microsoft.PowerShell.Utility

Legt einen Haltepunkt für eine Zeile, einen Befehl oder eine 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 Cmdlet Set-PSBreakpoint 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 verwenden, um einen Haltepunkt festzulegen, 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 können keinen Haltepunkt auf einem Remotecomputer festlegen. 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 einzelnen 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 stehen zur Verwendung zur Verfügung. Sie können jedoch den parameter Action 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 cmdlet Set-PSBreakpoint 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 Cmdlet Set-PSBreakpoint 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 funktion Increment im Cmdlet Sample.ps1 erstellt. Das Skript wird nicht mehr unmittelbar vor jedem Aufruf der angegebenen Funktion ausgeführt.

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 Server- Variable 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 sich der Wert ändert.

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. B. Write-Host.

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

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

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

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

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

Die Aktion verwendet das Schlüsselwort break, um die Ausführung zu beenden, wenn die Bedingung erfüllt ist. Die Alternative (und der Standardwert) 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 alle Elemente festgelegt, die in der aktuellen Sitzung ausgeführt werden. Der Debugger wird unterbrochen, wenn 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. Er legt einen Haltepunkt in Spalte 2 für jede der im Skript angegebenen Zeilen fest. Die im Action Parameter 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 parameter Runspace an den befehl Set-PSBreakPoint übergeben.

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

$runspace = Get-Runspace -Id 1

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

Parameter

-Action

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

Wenn dieser Parameter nicht angegeben wird oder keine Aktion angegeben wird, wird die Ausführung an dem Haltepunkt beendet, und der Debugger wird gestartet.

Wenn der Action Parameter verwendet wird, wird der Aktionsskriptblock an jedem Haltepunkt ausgeführt. Die Ausführung wird erst beendet, wenn der Skriptblock das Schlüsselwort Break enthält. Wenn Sie das Schlüsselwort Continue im Skriptblock verwenden, wird die Ausführung bis zum nächsten Haltepunkt fortgesetzt.

Weitere Informationen finden Sie unter about_Script_Blocks, about_Breakund about_Continue.

Typ:ScriptBlock
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Column

Gibt die Spaltennummer der Spalte in der Skriptdatei an, in der die Ausführung beendet wird. Geben Sie nur eine Spaltennummer ein. Der Standardwert ist Spalte 1.

Der Spaltenwert wird mit dem Wert des Line-Parameters 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 beginnend mit der Spaltennummer 1 (nicht 0) gezählt. Wenn Sie eine Spalte angeben, die nicht im Skript vorhanden ist, wird kein Fehler deklariert, der Haltepunkt wird jedoch nie ausgeführt.

Typ:Int32
Position:2
Standardwert:1
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Command

Legt einen Befehlstrennpunkt fest. Geben Sie Cmdlet-Namen ein, z. B. Get-Processoder Funktionsnamen. Wildcards sind zulässig.

Die Ausführung wird vor jeder Instanz jedes Befehls beendet. Wenn der Befehl eine Funktion ist, beendet die Ausführung jedes Mal, wenn die Funktion aufgerufen wird, und bei jedem BEGIN-, PROCESS- und END-Abschnitt.

Typ:String[]
Aliase:C
Position:Named
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:True

-Line

Legt einen Zeilenumbruchpunkt in einem Skript fest. Geben Sie eine oder mehrere Zeilennummern ein, getrennt durch Kommas. 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 ab Zeile 1 (nicht 0) gezählt. Wenn Sie eine leere Zeile angeben, wird die Ausführung vor der nächsten nicht leeren Zeile beendet. Wenn die Linie außerhalb des Zulässigen liegt, wird der Haltepunkt nie erreicht.

Typ:Int32[]
Position:1
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren: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 Haltepunkte, die im Befehl festgelegt sind. Die zulässigen Werte für diesen Parameter sind:

  • Write – Beendet die Ausführung unmittelbar, bevor ein neuer Wert in die Variable geschrieben wird.
  • Lese- – 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.
Typ:VariableAccessMode
Zulässige Werte:Read, Write, ReadWrite
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Runspace

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

Dieser Parameter wurde in PowerShell 7.2 hinzugefügt.

Typ:Runspace
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Script

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

Standardmäßig werden variable Haltepunkte und Befehlshaltepunkte für alle Befehle festgelegt, die in der aktuellen Sitzung ausgeführt werden. Dieser Parameter ist nur erforderlich, wenn ein Zeilenumbruchpunkt festgelegt wird.

Typ:String[]
Position:0
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren: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 "Schreiben" beendet die Ausführung unmittelbar vor dem Schreiben eines neuen Werts in die Variable.

Typ:String[]
Aliase:V
Position:Named
Standardwert:None
Erforderlich:True
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren: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 können keinen Haltepunkt auf einem Remotecomputer festlegen. 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 mehrere Zeilen, Befehle oder Variablen festlegen, generiert Set-PSBreakpoint für jeden Eintrag ein Haltepunktobjekt.

  • Wenn Sie an der Eingabeaufforderung einen Haltepunkt für eine Funktion oder Variable festlegen, können Sie den Haltepunkt vor oder nach dem Erstellen der Funktion oder Variable festlegen.