Поделиться через

Set-PSBreakpoint

  • Ссылка
Модуль:
Microsoft.PowerShell.Utility

Задает точку останова в строке, команде или переменной.

Синтаксис

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

Описание

Командлет Set-PSBreakpoint задает точку останова в скрипте или любой команде, выполняемой в текущем сеансе. Вы можете использовать Set-PSBreakpoint, чтобы задать точку останова перед выполнением скрипта или выполнением команды или во время отладки при остановке в другой точке останова.

Set-PSBreakpoint не удается задать точку останова на удаленном компьютере. Чтобы выполнить отладку скрипта на удаленном компьютере, скопируйте скрипт на локальный компьютер и отладите его локально.

Каждая команда Set-PSBreakpoint создает один из следующих трех типов точек останова:

  • Точка останова строки — задает точки останова в определенных координатах линии и столбца.
  • Точка останова команд — задает точки останова для команд и функций.
  • Переменная точка останова — задает точки останова для переменных.

Точку останова можно задать в нескольких строках, командах или переменных в одной команде Set-PSBreakpoint, но каждая команда Set-PSBreakpoint задает только один тип точки останова.

В точке останова PowerShell временно останавливает выполнение и позволяет управлять отладчиком. Командная строка изменяется на DBG\>, а набор команд отладчика становится доступным для использования. Однако можно использовать параметр Action для указания альтернативного ответа, например условий для точки останова или инструкций для выполнения дополнительных задач, таких как ведение журнала или диагностика.

Командлет Set-PSBreakpoint является одним из нескольких командлетов, предназначенных для отладки скриптов PowerShell. Дополнительные сведения об отладчике PowerShell см. в about_Debuggers.

Примеры

Пример 1. Установка точки останова в строке

В этом примере устанавливается точка останова в строке 5 в скрипте Sample.ps1. При запуске скрипта выполнение останавливается непосредственно перед выполнением строки 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

При установке новой точки останова по номеру строки командлет Set-PSBreakpoint создает объект точки останова строки (System.Management.Automation.LineBreakpoint), содержащий идентификатор точки останова и число попаданий.

Пример 2. Установка точки останова для функции

В этом примере создается точка останова команды для функции Increment в командлете Sample.ps1. Скрипт перестает выполняться непосредственно перед каждым вызовом указанной функции.

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

Результатом является объект точки останова команды. Перед выполнением скрипта значение свойства HitCount равно 0.

Пример 3. Установка точки останова для переменной

В этом примере устанавливается точка останова в переменной сервера в скрипте Sample.ps1. Он использует параметр mode со значением ReadWrite, чтобы остановить выполнение, когда значение переменной считывается и непосредственно перед изменением значения.

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

Пример 4. Установка точки останова для каждой команды, начинающейся с указанного текста

В этом примере устанавливается точка останова для каждой команды в скрипте Sample.ps1, который начинается с "записи", например Write-Host.

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

Пример 5. Установка точки останова в зависимости от значения переменной

Этот пример останавливает выполнение функции DiskTest в скрипте Test.ps1, только если значение переменной $Disk больше 2.

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

Значение действия — это блок скрипта, который проверяет значение переменной $Disk в функции.

Действие использует ключевое слово break для остановки выполнения, если условие выполнено. Альтернатива (и значение по умолчанию) — "Продолжить".

Пример 6. Установка точки останова для функции

В этом примере устанавливается точка останова для функции CheckLog. Так как команда не задает скрипт, точка останова устанавливается на все, что выполняется в текущем сеансе. Отладчик прерывается при вызове функции, а не при объявлении.

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'

Пример 7. Установка точек останова в нескольких строках

В этом примере задаются три точки останова строки в скрипте Sample.ps1. Он задает одну точку останова в столбце 2 на каждой строке, указанной в скрипте. Действие, указанное в параметре действия, применяется ко всем точкам останова.

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

Пример 8. Установка точки останова в пространстве выполнения

В этом примере запускается задание. Пространство выполнения хранится в переменной и передается команде Set-PSBreakPoint с параметром Runspace.

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

$runspace = Get-Runspace -Id 1

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

Параметры

-Action

Задает команды, которые выполняются в каждой точке останова вместо нарушения. Введите блок скрипта, содержащий команды. Этот параметр можно использовать для задания условных точек останова или выполнения других задач, таких как тестирование или ведение журнала.

Если этот параметр не указан или действие не указано, выполнение останавливается в точке останова и запускается отладчик.

Если используется параметр Action, блок скрипта действия выполняется в каждой точке останова. Выполнение не останавливается, если блок скрипта не включает ключевое слово Break. Если в блоке скрипта используется ключевое слово "Продолжить", выполнение возобновляется до следующей точки останова.

Дополнительные сведения см. в разделе about_Script_Blocks, about_Breakи about_Continue.

Тип:ScriptBlock
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Column

Указывает номер столбца в файле скрипта, на котором останавливается выполнение. Введите только один номер столбца. Значение по умолчанию — столбец 1.

Значение столбца используется со значением параметра Line для указания точки останова. Если параметр строки задает несколько строк, параметр column задает точку останова в указанном столбце для каждой из указанных строк. PowerShell останавливает выполнение перед оператором или выражением, которое включает символ в указанной строке и позиции столбца.

Столбцы учитываются из левого верхнего поля, начиная с номера 1 столбца (не 0). Если указать столбец, который не существует в скрипте, ошибка не объявляется, но точка останова никогда не выполняется.

Тип:Int32
Position:2
Default value:1
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Command

Задает точку останова команды. Введите имена командлетов, например Get-Processили имена функций. Разрешены подстановочные знаки.

Выполнение останавливается непосредственно перед выполнением каждого экземпляра каждой команды. Если команда является функцией, выполнение останавливается при каждом вызове функции и в каждом разделе BEGIN, PROCESS и END.

Тип:String[]
Aliases:C
Position:Named
Default value:None
Обязательно:True
Принять входные данные конвейера:False
Принять подстановочные знаки:True

-Line

Задает точку останова строки в скрипте. Введите один или несколько номеров строк, разделенных запятыми. PowerShell останавливается непосредственно перед выполнением инструкции, начинающейся с каждой из указанных строк.

Строки учитываются в левом верхнем поле файла скрипта, начиная с номера строки 1 (не 0). Если указать пустую строку, выполнение останавливается до следующей непустой строки. Если строка выходит за пределы диапазона, точка останова никогда не попадает.

Тип:Int32[]
Position:1
Default value:None
Обязательно:True
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Mode

Указывает режим доступа, который активирует точки останова переменных. Значение по умолчанию — записи.

Этот параметр действителен, только если параметр переменной используется в команде. Режим применяется ко всем точкам останова, заданным в команде. Допустимые значения для этого параметра:

  • записи — останавливает выполнение непосредственно перед записью нового значения в переменную.
  • чтение. Останавливает выполнение при чтении переменной, то есть при доступе к его значению, назначению, отображению или использованию. В режиме чтения выполнение не останавливается при изменении значения переменной.
  • ReadWrite — останавливает выполнение при чтении или записи переменной.
Тип:VariableAccessMode
Допустимые значения:Read, Write, ReadWrite
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Runspace

Задает идентификатор объекта Runspace, чтобы можно было взаимодействовать с точками останова в указанном пространстве выполнения.

Этот параметр был добавлен в PowerShell 7.2.

Тип:Runspace
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Script

Указывает массив файлов скриптов, в котором этот командлет задает точку останова. Введите пути и имена файлов одного или нескольких файлов скриптов. Если файлы находятся в текущем каталоге, можно опустить путь. Разрешены подстановочные знаки.

По умолчанию переменные точки останова и точки останова команд задаются в любой команде, которая выполняется в текущем сеансе. Этот параметр требуется только при задании точки останова строки.

Тип:String[]
Position:0
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Variable

Указывает массив переменных, на которые этот командлет устанавливает точки останова. Введите разделенный запятыми список переменных без знаков доллара ($).

Используйте параметр режима, чтобы определить режим доступа, который активирует точки останова. Режим записи по умолчанию останавливает выполнение непосредственно перед записью нового значения в переменную.

Тип:String[]
Aliases:V
Position:Named
Default value:None
Обязательно:True
Принять входные данные конвейера:False
Принять подстановочные знаки:False

Входные данные

None

Невозможно передать объекты в этот командлет.

Выходные данные

CommandBreakpoint

LineBreakpoint

VariableBreakpoint

Set-PSBreakpoint возвращает объект, представляющий каждую точку останова, которую он задает.

Примечания

PowerShell включает следующие псевдонимы для Set-PSBreakpoint:

  • Все платформы:

    • sbp

  • Set-PSBreakpoint не удается задать точку останова на удаленном компьютере. Чтобы выполнить отладку скрипта на удаленном компьютере, скопируйте скрипт на локальный компьютер и отладите его локально.

  • При установке точки останова для нескольких строк, команд или переменной Set-PSBreakpoint создает объект точки останова для каждой записи.

  • При настройке точки останова в функции или переменной в командной строке можно задать точку останова до или после создания функции или переменной.