РАЗДЕЛ
about_Debuggers
КРАТКОЕ ОПИСАНИЕ
Описывает отладчик Windows PowerShell.
ПОЛНОЕ ОПИСАНИЕ
Отладка представляет собой процесс проверки скрипта во время его
выполнения с целью выявления и исправления ошибок в инструкциях
скрипта. Отладчик Windows PowerShell помогает выполнять проверку
и находить в скриптах ошибки и неэффективные фрагменты.
Примечание. Отладчик Windows PowerShell не выполняется удаленно. Чтобы
отладить скрипт на удаленном компьютере, скопируйте его на
локальный компьютер.
Функции отладчика Windows PowerShell позволяют проверять скрипты,
функции, команды и выражения Windows PowerShell во время их
выполнения. Отладчик Windows PowerShell включает набор командлетов,
позволяющих устанавливать точки останова, управлять ими, а также
просматривать стек вызова.
В Windows PowerShell имеется несколько методов отладки скриптов,
функций и команд.
Метод 1. Командлет Set-PsDebug реализует базовые функции отладки
скриптов, включая пошаговое выполнение и трассировку.
Чтобы получить дополнительные сведения, введите следующую
команду: "get-help set-psdebug".
Метод 2. Командлет Set-StrictMode позволяет обнаруживать ссылки на
неинициализированные переменные, ссылки на несуществующие
свойства объектов, а также недопустимый синтаксис функций.
Метод 3. В скрипт добавляются диагностические инструкции, например
инструкции, выводящие на экран значения переменных, считывающие
данные из командной строки или сообщающие об инструкции, которая
выполняется в текущий момент. Для этого следует использовать
командлеты, содержащие слово Write, например Write-Host, Write-Debug,
Write-Warning или Write-Verbose.
Метод 4. Для отладки скрипта используется отладчик Windows
PowerShell. Либо с помощью отладчика можно выполнять отладку
функции или блока скрипта, введенных в командной строке. Можно
задавать точки останова, выполнять скрипты по шагам, проверять
значения переменных, выполнять команды диагностики и ведения
журнала, а также отображать содержимое стека вызова.
Командлеты отладчика
Отладчик Windows PowerShell включает следующий набор командлетов:
Set-PsBreakpoint: устанавливает точки останова на строках,
переменных и командах.
Get-PsBreakpoint: получает точки останова в текущем сеансе.
Disable-PsBreakpoint: отключает точки останова в текущем сеансе.
Enable-PsBreakpoint: заново включает точки останова в текущем сеансе.
Remove-PsBreakpoint: удаляет точки останова из текущего сеанса.
Get-PsCallStack: отображает текущий стек вызова.
Запуск и остановка отладчика
Чтобы запустить отладчик, установите одну или несколько точек
останова. После этого выполните скрипт, команду или функцию,
которые требуется отладить.
При достижении точки останова выполнение останавливается,
а управление передается отладчику.
Чтобы остановить отладчик, выполните скрипт, команду или
функцию до конца. Либо введите команду "stop" или "t".
Команды отладчика
При использовании отладчика в консоли Windows PowerShell управление
выполнением осуществляется с помощью следующих команд.
Примечание. Дополнительные сведения об использовании отладчика
в других ведущих приложениях см. в документации по конкретному
ведущему приложению.
s, Step-into Выполняет следующую инструкцию и останавливается.
v, Step-over Выполняет следующую инструкцию, но пропускает
функции и вызовы. Пропущенные инструкции выполняются,
но в них отладчик не останавливается.
o, Step-out Выходит из текущей функции; на один уровень
вверх, если функция является вложенной. Если управление
находится в теле главной функции, выполнение продолжается
до конца функции или до очередной точки останова. Пропущенные
инструкции выполняются, но в них отладчик не останавливается.
c, Continue Продолжает выполнение до завершения
скрипта или до достижения очередной точки
останова. Пропущенные инструкции выполняются,
но в них отладчик не останавливается.
l, List Отображает выполняющуюся часть скрипта. По
умолчанию отображается текущая строка, пять
предыдущих и десять следующих строк. Чтобы
продолжить вывод скрипта, нажмите клавишу ВВОД.
l <m>, List Отображает 16 строк скрипта, начиная со строки,
которая задается значением <m>.
l <m> <n>, List Отображает <n> строк скрипта, начиная со строки,
которая задается значением <m>.
q, Stop Останавливает выполнение скрипта и закрывает отладчик.
k, Get-PsCallStack Отображает текущий стек вызова.
<Ввод> Повторение последней команды, если это была команда (s),
Step-over (v) или List (l). В противном случае выполняет
действие отправки.
?, h Отображает команду Help отладчика.
Чтобы выйти из отладчика, воспользуйтесь командой Stop (q).
Находясь в режиме отладчика, можно также вводить команды, отображать
значения переменных, использовать командлеты и выполнять скрипты.
Используя эти команды отладчика, можно выполнять скрипты,
останавливаться в сомнительных местах, проверять значения
переменных и состояние системы, а также продолжать выполнение
скриптов, пока не будут найдены неполадки.
Среда отладчика
При достижении точки останова происходит вход в среду
отладчика. Командная строка изменяется и начинается с "[DBG]:".
Командную строку можно настраивать.
Кроме того, в некоторых приложениях, например в консоли Windows
PowerShell (но не в интегрированной среде скриптов Windows
PowerShell), для отладки открывается вложенная командная
строка. Вложенная командная строка отличается повторяющимися знаками
"больше" (код ASCII 62).
Например, ниже показана командная строка по умолчанию в консоли
Windows PowerShell:
[DBG]: PS (get-location)>>>
Уровень вложенности можно определить с помощью автоматической
переменной $NestedPromptLevel.
Кроме того, в локальной области определена автоматическая переменная
$PSDebugContext. По наличию переменной можно $PsDebugContext можно
определить, что включен отладчик.
Пример:
if ($psdebugcontext) {"Debugging"} else {"Not Debugging"}
Значение переменной $PSDebugContext можно использовать при отладке.
[DBG]: PS>>> $psdebugcontext.invocationinfo
Name CommandLineParameters UnboundArguments Location
---- --------------------- ---------------- --------
= {} {} C:\ps-test\vote.ps1 (1)
Отладка и область
Запуск отладчика не изменяет текущую рабочую область, однако при
достижении точки останова в скрипте происходит переход в область скрипта.
Область скрипта является дочерней для области, в которой запущен отладчик.
Чтобы найти переменные и псевдонимы, определенные в области скрипта,
следует использовать параметр Scope командлетов Get-Alias or Get-Variable.
Например, следующая команда получает переменные в локальной области
(области скрипта):
get-variable -scope 0
Эту команду можно сократить следующим образом:
gv -s 0
Это удобный способ, позволяющий видеть только переменные,
определенные в скрипте и определенные во время отладки.
Отладка в командной строке
Точки останова переменной или команды можно устанавливать
только в файле скрипта. Однако по умолчанию точка останова
устанавливается в любом выполняемом в текущем сеансе компоненте.
Например, если установить точку останова на переменной $name,
отладчик остановит выполнение на любой переменной $name в любом
выполняемом скрипте, команде, функции, командлете скрипта или
выражении, если не отключить или удалить эту точку останова.
Это позволяет отлаживать скрипты в более реалистичном
контексте, когда на них могут оказывать влияние другие функции,
переменные и скрипты из сеанса и профиля пользователя.
Точки останова строк связаны с конкретными файлами скриптов,
поэтому они задаются только в файлах скриптов.
Отладка функций
При установке точки останова на функции, имеющей разделы Begin,
Process и End, отладчик будет останавливать выполнение на
первой строке каждого из разделов.
Пример:
function test-cmdlet
{
begin
{
write-output "Begin"
}
process
{
write-output "Process"
}
end
{
write-output "End"
}
}
C:\PS> set-psbreakpoint -command test-cmdlet
C:\PS> test-cmdlet
Begin
Выполняется запуск в режиме отладки. Введите "h" или "?"
для получения справки.
Выполнение Точка останова команды на "prompt:test-cmdlet"
test-cmdlet
[DBG]: C:\PS> c
Process
Выполняется запуск в режиме отладки. Введите "h" или "?"
для получения справки.
Выполнение Точка останова команды на "prompt:test-cmdlet"
test-cmdlet
[DBG]: C:\PS> c
End
Выполняется запуск в режиме отладки. Введите "h" или "?"
для получения справки.
Выполнение Точка останова команды на "prompt:test-cmdlet"
test-cmdlet
[DBG]: C:\PS>
Отладка удаленных скриптов
Отладчик Windows PowerShell нельзя запускать в удаленных
сеансах. Чтобы отладить скрипт на удаленном компьютере,
скопируйте его на локальный компьютер.
Следующая команда копирует скрипт Test.ps1 с удаленного компьютера
Server01 на локальный компьютер:
invoke-command -computername Server01 `
{get-content c:\ps-test\test.ps1} | set-location c:\ps-test\test.ps1
Примеры
Этот тестовый скрипт определяет версию операционной системы и
отображает сообщение, соответствующее конкретной системе. Он
включает функцию, вызов функции и переменную.
Следующая команда отображает содержимое файла тестового скрипта:
c:>\PS-test> get-content test.ps1
function psversion {
"Windows Powershell " + $psversiontable.psversion
if ($psversiontable.psversion.major -lt 2) {
"Upgrade to Windows PowerShell 2.0!"
}
else {
"Have you run a background job today (start-job)?"
}
}
$scriptname = $MyInvocation.MyCommand.Path
psversion
"Done $scriptname."
Сначала установите точку останова в нужном месте скрипта,
например на строке, команде, переменной или функции.
Начните с создания точки останова строки на первой строке
скрипта Test.ps1 в текущем каталоге.
PS C:\ps-test> set-psbreakpoint -line 1 -script test.ps1
Эту команду можно сократить следующим образом:
PS C:\ps-test> spb 1 -s test.ps1
Эта команда возвращает объект точки останова строки
(System.Management.Automation.LineBreakpoint).
Column : 0
Line : 1
Action :
Enabled : True
HitCount : 0
Id : 0
Script : C:\ps-test\test.ps1
ScriptName : C:\ps-test\test.ps1
Теперь запустите скрипт.
PS C:\ps-test> .\test.ps1
Когда выполнение скрипта дойдет до первой точки останова,
сообщение точки останова покажет, что работает отладчик.
Сообщение будет содержать описание точки останова и предварительный
просмотр первой строки скрипта, которая представляет собой объявление
функции. Кроме того, изменится командная строка, что будет указывать
на то, что управление находится у отладчика.
Строка предварительного просмотра будет включать имя скрипта и номер
строки с показываемой командой.
Выполняется запуск в режиме отладки. Введите "h" или "?"
для получения справки.
Выполнение Точка останова строки на "C:\ps-test\test.ps1:1"
test.ps1:1 function psversion {
DBG>
Воспользуйтесь командой Step (s), чтобы выполнить первую инструкцию
скрипта и увидеть следующую инструкцию. В следующей инструкции
используется автоматическая переменная $MyInvocation, позволяющая
присвоить переменной $ScriptName путь и имя файла скрипта.
DBG> s
test.ps1:11 $scriptname = $MyInvocation.MyCommand.Path
В этот момент значение переменной $ScriptName не присваивается;
значение переменной можно проверить, отобразив его. В данном случае
переменная имеет значение $null.
DBG> $scriptname
DBG>
С помощью еще одной команды Step (s) выполните текущую инструкцию и
отобразите следующую инструкцию скрипта. Следующая инструкция
вызывает функцию PsVersion.
DBG> s
test.ps1:12 psversion
В этот момент переменной $ScriptName присваивается значение, и
его можно проверить, отобразив. Теперь оно имеет значение пути
к скрипту.
DBG> $scriptname
C:\ps-test\test.ps1
Воспользуйтесь еще одной командой Step, чтобы выполнить вызов
функции. Чтобы выполнить команду Step, нажмите клавишу ВВОД или
введите "s".
DBG> s
test.ps1:2 "Windows Powershell " + $psversiontable.psversion
Сообщение отладки включает предварительный просмотр инструкции
в функции. Чтобы выполнить эту инструкцию и увидеть следующую
инструкцию в функции, можно использовать команду Step. Но в данном
случае воспользуйтесь командой Step-Out (o). Она завершит выполнение
функции (если не будет достигнута точка останова) и перейдет к следующей
инструкции в скрипте.
DBG> o
Windows Powershell 2.0
Have you run a background job today (start-job)?
test.ps1:13 "Done $scriptname"
Поскольку достигнута последняя инструкция в скрипте, результат
выполнения команд Step, Step-Out и Continue одинаков. В данном
случае воспользуйтесь командой Step-Out (o).
Done C:\ps-test\test.ps1
PS C:\ps-test>
Командлет Step-Out выполняет последнюю команду. Стандартный вид
командной строки указывает на то, что работа отладчика завершена, а
управление передано обработчику команд.
Снова запустите отладчик. Сначала удалите текущую точку останова
(воспользуйтесь командлетами Get-PsBreakpoint и Remove-PsBreakpoint).
(Если эта точка останова может понадобиться позже, вместо командлета
Remove-PsBreakpoint используйте командлет Disable-PsBreakpoint.)
PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint
Эту команду можно сократить следующим образом:
PS C:\ps-test> gbp | rbp
Либо выполните команду, написав функцию, например следующим образом:
function delbr { gbp | rbp }
После этого создайте точку останова на переменной $scriptname.
PS C:\ps-test> set-psbreakpoint -variable scriptname -script test.ps1
Эту команду можно сократить следующим образом:
PS C:\ps-test> sbp -v scriptname -s test.ps1
Теперь запустите скрипт. Скрипт достигнет точки останова
переменной. По умолчанию используется режим Write, поэтому
выполнение будет остановлено непосредственно перед тем, как
инструкция изменит значение переменной.
PS C:\ps-test> .\test.ps1
Выполнение Точка останова переменной на "C:\ps-
test\test.ps1:$scriptname" (доступ к Write)
test.ps1:11 $scriptname = $MyInvocation.mycommand.path
DBG>
Отобразите текущее значение переменной $scriptname, которое
равняется $null.
DBG> $scriptname
DBG>
Воспользуйтесь командой Step (s), чтобы выполнить инструкцию,
которая присваивает значение переменной. Затем выведите новое
значение переменной $scriptname.
DBG> $scriptname
C:\ps-test\test.ps1
Воспользуйтесь командой Step (s), чтобы увидеть следующую
инструкцию в скрипте.
DBG> s
test.ps1:12 psversion
Следующая инструкция представляет собой вызов функции
PsVersion. Чтобы пропустить функцию, но выполнить ее, воспользуйтесь
командой Step-Over (v). Если во время использования команды Step-Over
функция уже выполняется, она не действует. Вызов функции
отображается, но она не выполняется.
DBG> v
Windows Powershell 2.0
Have you run a background job today (start-job)?
test.ps1:13 "Done $scriptname"
Команда Step-Over выполняет функцию и выводит предварительный
просмотр следующей инструкции скрипта, которая выводит
последнюю строку.
Чтобы выйти из отладчика, воспользуйтесь командой Stop (t).
Командная строка снова примет стандартный вид.
C:\ps-test>
Чтобы удалить точки останова, воспользуйтесь командлетами
Get-PsBreakpoint и Remove-PsBreakpoint.
PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint
Создайте новую точку останова команды на функции PsVersion.
PS C:\ps-test> Set-PsBreakpoint -command psversion -script test.ps1
Эту команду можно сократить следующим образом:
PS C:\ps-test> sbp -c psversion -s test.ps1
Теперь выполните скрипт.
PS C:\ps-test> .\test.ps1
Выполнение Точка останова команды на "C:\ps-test\test.ps1:psversion"
test.ps1:12 psversion
DBG>
Скрипт достигает точки останова на вызове функции. В этот
момент функция еще не была вызвана. Это позволяет воспользоваться
параметром Action команды Set-PsBreakpoint, чтобы задать условия
выполнения точки останова или выполнить подготовительные или
диагностические задачи, например запустить ведение журнала или
вызвать скрипт диагностики или обеспечения безопасности.
Для задания действия воспользуйтесь командой Continue (c),
чтобы выйти из скрипта, и командой Remove-PsBreakpoint, чтобы
удалить текущую точку останова. (Точки останова доступны только для
чтения, поэтому добавить действие в текущую точку останова невозможно.)
DBG> c
Windows PowerShell 2.0
Have you run a background job today (start-job)?
Done C:\ps-test\test.ps1
PS C:\ps-test> get-psbreakpoint | remove-psbreakpoint
PS C:\ps-test>
После этого создайте новую точку останова команды с действием.
Следующая команда устанавливает точку останова команды с действием,
которое при вызове функции записывает в журнал значение переменной
$scriptname. Поскольку в действии не используется ключевое слово Break,
выполнение не останавливается. (Обратный апостроф (`) является знаком
продолжения строки.)
PS C:\ps-test> set-psbreakpoint -command psversion -script test.ps1 `
-action { add-content "The value of `$scriptname is $scriptname." `
-path action.log}
Кроме того, можно добавлять действия, которые задают условия
для точки останова. В следующей команде точка останова команды
выполняется только в том случае, если задана политика выполнения
RemoteSigned - наиболее строгая политика, которая позволяет выполнять
скрипты. (Обратный апостроф (`) является знаком продолжения строки.)
PS C:\ps-test> set-psbreakpoint -script test.ps1 -command psversion `
-action { if ((get-executionpolicy) -eq "RemoteSigned") { break }}
Ключевое слово Break в действии указывает отладчику, что необходимо
выполнить точку останова. Кроме того, можно воспользоваться ключевым
словом Continue, чтобы отладчик выполнялся без останова. Поскольку по
умолчанию используется ключевое слово Continue, чтобы остановить
выполнение, необходимо задать ключевое слово Break.
Теперь выполните скрипт.
PS C:\ps-test> .\test.ps1
Выполнение Точка останова команды на "C:\ps-test\test.ps1:psversion"
test.ps1:12 psversion
Поскольку задана политика выполнения RemoteSigned, выполнение
останавливается на вызове функции.
На этом этапе может потребоваться проверить стек вызова.
Воспользуйтесь командлетом Get-PsCallStack или командой
отладчика Get-PsCallStack (k). Следующая команда возвращает
текущий стек вызова.
DBG> k
2: prompt
1: .\test.ps1: $args=[]
0: prompt: $args=[]
Этот пример демонстрирует лишь один из множества способов
использования отладчика Windows PowerShell.
Чтобы получить дополнительные сведения о командлетах отладчика,
введите следующую команду:
help <cmdlet-name> -full
Например, введите следующую команду:
help set-psbreakpoint -full
СМ. ТАКЖЕ
Disable-PsBreakpoint
Get-PsBreakpoint
Remove-PsBreakpoint
Set-PsBreakpoint
Set-PsDebug
Set-Strictmode
Write-Debug
Write-Verbose
Enable-PsBreakpoint
Get-PsCallStack