Udostępnij za pośrednictwem

Set-PSBreakpoint

  • Odwołanie
Moduł:
Microsoft.PowerShell.Utility

Ustawia punkt przerwania w wierszu, poleceniu lub zmiennej.

Składnia

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

Opis

Polecenie cmdlet Set-PSBreakpoint ustawia punkt przerwania w skrycie lub w dowolnym poleceniu uruchomionym w bieżącej sesji. Za pomocą Set-PSBreakpoint można ustawić punkt przerwania przed wykonaniem skryptu lub uruchomieniem polecenia albo podczas debugowania po zatrzymaniu w innym punkcie przerwania.

Set-PSBreakpoint nie można ustawić punktu przerwania na komputerze zdalnym. Aby debugować skrypt na komputerze zdalnym, skopiuj skrypt na komputer lokalny, a następnie debuguj go lokalnie.

Każde polecenie Set-PSBreakpoint tworzy jeden z następujących trzech typów punktów przerwania:

  • Punkt przerwania wiersza — ustawia punkty przerwania na określonych współrzędnych wiersza i kolumny.
  • Punkt przerwania polecenia — ustawia punkty przerwania dla poleceń i funkcji.
  • Punkt przerwania zmiennej — ustawia punkty przerwania dla zmiennych.

Punkt przerwania można ustawić na wielu wierszach, poleceniach lub zmiennych w jednym poleceniu Set-PSBreakpoint, ale każde polecenie Set-PSBreakpoint ustawia tylko jeden typ punktu przerwania.

W punkcie przerwania program PowerShell tymczasowo zatrzymuje wykonywanie i daje kontrolę debugerowi. Wiersz polecenia zmieni się na DBG\>, a zestaw poleceń debugera stanie się dostępny do użycia. Można jednak użyć parametru Action, aby określić alternatywną odpowiedź, taką jak warunki punktu przerwania lub instrukcje wykonywania dodatkowych zadań, takich jak rejestrowanie lub diagnostyka.

Polecenie cmdlet Set-PSBreakpoint to jedno z kilku poleceń cmdlet przeznaczonych do debugowania skryptów programu PowerShell. Aby uzyskać więcej informacji na temat debugera programu PowerShell, zobacz about_Debuggers.

Przykłady

Przykład 1: Ustawianie punktu przerwania w wierszu

W tym przykładzie ustawiono punkt przerwania w wierszu 5 skryptu Sample.ps1. Po uruchomieniu skryptu wykonanie zostanie zatrzymane bezpośrednio przed wykonaniem wiersza 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

Po ustawieniu nowego punktu przerwania według numeru wiersza polecenie cmdlet Set-PSBreakpoint generuje obiekt punktu przerwania wiersza (System.Management.Automation.LineBreakpoint), który zawiera identyfikator punktu przerwania i liczbę trafień.

Przykład 2. Ustawianie punktu przerwania w funkcji

W tym przykładzie tworzony jest punkt przerwania polecenia w funkcji Increment w poleceniu cmdlet Sample.ps1. Skrypt zatrzymuje wykonywanie bezpośrednio przed każdym wywołaniem określonej funkcji.

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

Wynikiem jest obiekt punktu przerwania polecenia. Przed uruchomieniem skryptu wartość właściwości HitCount wynosi 0.

Przykład 3. Ustawianie punktu przerwania dla zmiennej

W tym przykładzie ustawiono punkt przerwania w zmiennej serwera w skry skry skryptie Sample.ps1. Używa parametru Mode z wartością ReadWrite, aby zatrzymać wykonywanie, gdy wartość zmiennej jest odczytywana i tuż przed zmianą wartości.

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

Przykład 4. Ustawianie punktu przerwania dla każdego polecenia rozpoczynającego się od określonego tekstu

W tym przykładzie ustawiono punkt przerwania dla każdego polecenia skryptu Sample.ps1 rozpoczynającego się od ciągu "write", takiego jak Write-Host.

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

Przykład 5. Ustawianie punktu przerwania w zależności od wartości zmiennej

Ten przykład zatrzymuje wykonywanie w funkcji DiskTest w skry skrycie Test.ps1 tylko wtedy, gdy wartość zmiennej $Disk jest większa niż 2.

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

Wartość Action to blok skryptu, który testuje wartość zmiennej $Disk w funkcji.

Akcja używa słowa kluczowego break, aby zatrzymać wykonywanie, jeśli warunek jest spełniony. Alternatywą (i domyślną) jest Kontynuuj.

Przykład 6. Ustawianie punktu przerwania w funkcji

W tym przykładzie ustawiono punkt przerwania w funkcji CheckLog. Ponieważ polecenie nie określa skryptu, punkt przerwania jest ustawiany na wszystko, co działa w bieżącej sesji. Debuger przerywa działanie po wywołaniu funkcji, a nie w przypadku jej zadeklarowania.

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'

Przykład 7. Ustawianie punktów przerwania w wielu wierszach

W tym przykładzie ustawiono trzy wiersze punktów przerwania w skry skryscie Sample.ps1. Ustawia jeden punkt przerwania w kolumnie 2 dla każdego wiersza określonego w skry skrycie. Akcja określona w Akcja parametr dotyczy wszystkich punktów przerwania.

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

Przykład 8. Ustawianie punktu przerwania w przestrzeni uruchomieniowej

W tym przykładzie uruchomiono zadanie. Przestrzeń uruchomieniowa jest przechowywana w zmiennej i przekazywana do polecenia Set-PSBreakPoint za pomocą parametru Runspace.

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

$runspace = Get-Runspace -Id 1

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

Parametry

-Action

Określa polecenia uruchamiane w każdym punkcie przerwania zamiast przerywania. Wprowadź blok skryptu zawierający polecenia. Tego parametru można użyć do ustawiania warunkowych punktów przerwania lub wykonywania innych zadań, takich jak testowanie lub rejestrowanie.

Jeśli ten parametr zostanie pominięty lub nie określono żadnej akcji, wykonanie zostanie zatrzymane w punkcie przerwania, a debuger zostanie uruchomiony.

Gdy jest używany parametr Akcja, blok Skrypt akcji jest uruchamiany w każdym punkcie przerwania. Wykonanie nie zostanie zatrzymane, chyba że blok skryptu zawiera słowo kluczowe Break. Jeśli używasz słowa kluczowego Continue w bloku skryptu, wykonywanie zostanie wznowione do następnego punktu przerwania.

Aby uzyskać więcej informacji, zobacz about_Script_Blocks, about_Breaki about_Continue.

Typ:ScriptBlock
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-Column

Określa numer kolumny w pliku skryptu, na którym kończy się wykonywanie. Wprowadź tylko jeden numer kolumny. Wartość domyślna to kolumna 1.

Wartość Kolumna jest używana z wartością parametru linii w celu określenia punktu przerwania. Jeśli parametr wiersza określa wiele wierszy, parametr Column ustawia punkt przerwania w określonej kolumnie na każdym z określonych wierszy. Program PowerShell przestaje wykonywać operacje przed instrukcją lub wyrażeniem zawierającym znak w określonej pozycji wiersza i kolumny.

Kolumny są liczone z lewego górnego marginesu rozpoczynającego się od numeru kolumny 1 (nie 0). Jeśli określisz kolumnę, która nie istnieje w skryscie, błąd nie zostanie zadeklarowany, ale punkt przerwania nigdy nie zostanie wykonany.

Typ:Int32
Position:2
Domyślna wartość:1
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-Command

Ustawia punkt przerwania polecenia. Wprowadź nazwy poleceń cmdlet, takie jak Get-Processlub nazwy funkcji. Dozwolone są symbole wieloznaczne.

Wykonanie zatrzymuje się tuż przed wykonaniem każdego wystąpienia każdego polecenia. Jeśli polecenie jest funkcją, wykonywanie zatrzymuje się za każdym razem, gdy funkcja jest wywoływana i w każdej sekcji BEGIN, PROCESS i END.

Typ:String[]
Aliasy:C
Position:Named
Domyślna wartość:None
Wymagane:True
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:True

-Line

Ustawia punkt przerwania wiersza w skrycie. Wprowadź co najmniej jeden numer wiersza oddzielony przecinkami. Program PowerShell zatrzymuje się bezpośrednio przed wykonaniem instrukcji rozpoczynającej się w każdym z określonych wierszy.

Wiersze są liczone od lewego górnego marginesu pliku skryptu rozpoczynającego się od numeru wiersza 1 (nie 0). Jeśli określisz pusty wiersz, wykonanie zostanie zatrzymane przed następnym niepustym wierszem. Jeśli linia jest poza zakresem, punkt przerwania nigdy nie zostanie trafiony.

Typ:Int32[]
Position:1
Domyślna wartość:None
Wymagane:True
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-Mode

Określa tryb dostępu wyzwalający punkty przerwania zmiennych. Wartość domyślna to Write.

Ten parametr jest prawidłowy tylko wtedy, gdy parametr zmiennej jest używany w poleceniu . Tryb dotyczy wszystkich punktów przerwania ustawionych w poleceniu . Dopuszczalne wartości tego parametru to:

  • write — zatrzymuje wykonywanie bezpośrednio przed zapisaniem nowej wartości w zmiennej.
  • odczyt — zatrzymuje wykonywanie, gdy zmienna jest odczytywana, czyli gdy jej wartość jest uzyskiwana, ma być przypisana, wyświetlana lub używana. W trybie odczytu wykonanie nie zostanie zatrzymane, gdy wartość zmiennej ulegnie zmianie.
  • ReadWrite — zatrzymuje wykonywanie, gdy zmienna jest odczytywana lub zapisywana.
Typ:VariableAccessMode
Dopuszczalne wartości:Read, Write, ReadWrite
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-Runspace

Określa identyfikator obiektu Runspace, aby można było wchodzić w interakcje z punktami przerwania w określonej przestrzeni uruchomieniowej.

Ten parametr został dodany w programie PowerShell 7.2.

Typ:Runspace
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-Script

Określa tablicę plików skryptów, w których to polecenie cmdlet ustawia punkt przerwania. Wprowadź ścieżki i nazwy plików co najmniej jednego pliku skryptu. Jeśli pliki znajdują się w bieżącym katalogu, możesz pominąć ścieżkę. Dozwolone są symbole wieloznaczne.

Domyślnie punkty przerwania zmiennych i punkty przerwania poleceń są ustawiane na dowolnym poleceniu uruchamianym w bieżącej sesji. Ten parametr jest wymagany tylko podczas ustawiania punktu przerwania wiersza.

Typ:String[]
Position:0
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-Variable

Określa tablicę zmiennych, na których to polecenie cmdlet ustawia punkty przerwania. Wprowadź rozdzielaną przecinkami listę zmiennych bez znaków dolara ($).

Użyj parametru Mode, aby określić tryb dostępu wyzwalający punkty przerwania. Tryb domyślny Write zatrzymuje wykonywanie tuż przed zapisaniem nowej wartości w zmiennej.

Typ:String[]
Aliasy:V
Position:Named
Domyślna wartość:None
Wymagane:True
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

Dane wejściowe

None

Nie można potokować obiektów do tego polecenia cmdlet.

Dane wyjściowe

CommandBreakpoint

LineBreakpoint

VariableBreakpoint

Set-PSBreakpoint zwraca obiekt reprezentujący każdy ustawiany punkt przerwania.

Uwagi

Program PowerShell zawiera następujące aliasy dla Set-PSBreakpoint:

  • Wszystkie platformy:

    • sbp

  • Set-PSBreakpoint nie można ustawić punktu przerwania na komputerze zdalnym. Aby debugować skrypt na komputerze zdalnym, skopiuj skrypt na komputer lokalny, a następnie debuguj go lokalnie.

  • Po ustawieniu punktu przerwania w więcej niż jednym wierszu, poleceniu lub zmiennej Set-PSBreakpoint generuje obiekt punktu przerwania dla każdego wpisu.

  • Podczas ustawiania punktu przerwania w funkcji lub zmiennej w wierszu polecenia można ustawić punkt przerwania przed lub po utworzeniu funkcji lub zmiennej.