Сведения об отладчиках
КРАТКОЕ ОПИСАНИЕ
Описывает отладчик PowerShell.
ПОДРОБНОЕ ОПИСАНИЕ
Отладка — это процесс проверки скрипта во время его выполнения для выявления и исправления ошибок в инструкциях скрипта. Отладчик PowerShell помогает изучить и выявить ошибки и неэффективность в сценариях, функциях, командах, конфигурациях PowerShell Desired State Configuration (DSC) или выражениях.
Начиная с PowerShell 5.0, отладчик PowerShell обновлен для отладки скриптов, функций, команд, конфигураций или выражений, которые выполняются в консоли или Windows PowerShell ISE на удаленных компьютерах. Вы можете запустить Enter-PSSession , чтобы запустить интерактивный удаленный сеанс PowerShell, в котором можно задать точки останова и отладить файлы скриптов и команды на удаленном компьютере. Enter-PSSession функциональность была обновлена для повторного подключения и входа в отключенный сеанс, выполняющий скрипт или команду на удаленном компьютере. Если выполняющийся скрипт достигает точки останова, сеанс клиента автоматически запускает отладчик. Если отключенный сеанс, в котором выполняется скрипт, уже достиг точки останова и остановлен в точке останова, Enter-PSSession автоматически запускает отладчик командной строки после повторного подключения к сеансу.
Функции отладчика PowerShell можно использовать для проверки скрипта, функции, команды или выражения PowerShell во время выполнения. Отладчик PowerShell включает набор командлетов, которые позволяют задавать точки останова, управлять точками останова и просматривать стек вызовов.
Командлеты отладчика
Отладчик PowerShell включает следующий набор командлетов:
Set-PSBreakpoint: задает точки останова для строк, переменных и команд.Get-PSBreakpoint: возвращает точки останова в текущем сеансе.Disable-PSBreakpoint: отключает точки останова в текущем сеансе.Enable-PSBreakpoint: повторно включает точки останова в текущем сеансе.Remove-PSBreakpoint: удаляет точки останова из текущего сеанса.Get-PSCallStack: отображает текущий стек вызовов.
Запуск и остановка отладчика
Чтобы запустить отладчик, установите одну или несколько точек останова. Затем запустите скрипт, команду или функцию, которые требуется отладить.
При достижении точки останова выполнение останавливается, а управление переключается на отладчик.
Чтобы остановить отладчик, запустите скрипт, команду или функцию, пока они не будут завершены. Или введите stop или t.
Команды отладчика
При использовании отладчика в консоли PowerShell используйте следующие команды для управления выполнением. В Windows PowerShell ISE используйте команды в меню Отладка.
Примечание. Сведения об использовании отладчика в других ведущих приложениях см. в документации по ведущему приложению.
s,StepInto: выполняет следующую инструкцию, а затем останавливается.v,StepOver— выполняет следующую инструкцию, но пропускает функции и вызовы. Пропущенные операторы выполняются, но в них отладчик не останавливается.Ctrl+Break: (Разорвать все в интегрированной среде сценариев) Выполняется скрипт в консоли PowerShell или Windows PowerShell ISE. Обратите внимание, что принажатииклавиши Ctrl+ Break в Windows PowerShell 2.0, 3.0 и 4.0 программа закрывается. Прерывание всех работает как с локальными, так и с удаленными скриптами, работающими в интерактивном режиме.o,StepOut: выход из текущей функции; на один уровень выше, если вложенный. Если в основном тексте, он продолжается до конца или следующей точки останова. Пропущенные операторы выполняются, но в них отладчик не останавливается.c,Continue: продолжает выполняться до завершения скрипта или до достижения следующей точки останова. Пропущенные операторы выполняются, но в них отладчик не останавливается.l,List: отображает часть выполняемого скрипта. По умолчанию отображается текущая строка, пять предыдущих строк и 10 последующих строк. Чтобы продолжить вывод списка скрипта, нажмите клавишу ВВОД.l <m>,List: отображает 16 строк скрипта, начинающегося с номера строки, указанной параметром<m>.l <m> <n>,List: отображает<n>строки скрипта, начиная с номера строки, указанной параметром<m>.q,Stop,Exit: прекращает выполнение скрипта и завершает работу отладчика. При отладке задания с помощью командлетаDebug-JobExitкоманда отсоединяет отладчик и позволяет ей продолжить выполнение.k,Get-PsCallStack: отображает текущий стек вызовов.<Enter>: повторяет последнюю команду, если она была Step (s), StepOver (v) или List (l). В противном случае представляет действие отправки.?,h: отображает справку команды отладчика.
Чтобы выйти из отладчика, можно использовать команду Stop (q).
Начиная с PowerShell 5.0, можно выполнить команду Выход, чтобы выйти из вложенного сеанса отладки, запущенного с помощью команды Debug-Job или Debug-Runspace.
С помощью этих команд отладчика можно запустить скрипт, остановиться на проблемной точке, изучить значения переменных и состояние системы, а также продолжить выполнение скрипта, пока не будет обнаружена проблема.
Примечание. Если выполнить шаг в инструкцию с оператором перенаправления, например ">", отладчик PowerShell выполняет шаги по всем остальным операторам в скрипте.
Отображение значений переменных скрипта
Находясь в отладчике, можно также вводить команды, отображать значения переменных, использовать командлеты и выполнять скрипты в командной строке.
Вы можете отобразить текущее значение всех переменных в отлаживаемом скрипте, за исключением следующих автоматических переменных:
$_
$Args
$Input
$MyInvocation
$PSBoundParameters
При попытке отобразить значение любой из этих переменных отображается значение переменной из внутреннего конвейера отладчика, а не переменной в сценарии.
Чтобы отобразить значение этих переменных для отлаживаемого скрипта, присвойте значение автоматической переменной новой переменной. Затем можно отобразить значение новой переменной.
Например, примененная к объекту директива
$scriptArgs = $Args
$scriptArgs
В примере в этом разделе значение переменной $MyInvocation переназначается следующим образом:
$scriptname = $MyInvocation.MyCommand.Path
Среда отладчика
При достижении точки останова вы входите в среду отладчика. Командная строка изменится так, что она начинается с "[DBG]:".
Дополнительные сведения о настройке запроса см. в разделе about_Prompts.
Кроме того, в некоторых ведущих приложениях, таких как консоль PowerShell (но не в Windows PowerShell интегрированной среде сценариев [ISE]), открывается вложенный запрос для отладки. Вы можете определить вложенную строку с помощью повторяющихся символов (ASCII 62), которые отображаются в командной строке.
Например, ниже приведен запрос отладки по умолчанию в консоли 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)
Отладка и область
При входе в отладчик не изменяется область, в которой выполняется работа, но при достижении точки останова в скрипте вы переходите в область скрипта. Область скрипта является дочерней по отношению к области, в которой был запущен отладчик.
Чтобы найти переменные и псевдонимы, определенные в области скрипта, используйте параметр Get-Alias Scope командлетов или 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
Entering debug mode. Use h or ? for help.
Hit Command breakpoint on 'prompt:test-cmdlet'
test-cmdlet
[DBG]: C:\PS> c
Process
Entering debug mode. Use h or ? for help.
Hit Command breakpoint on 'prompt:test-cmdlet'
test-cmdlet
[DBG]: C:\PS> c
End
Entering debug mode. Use h or ? for help.
Hit Command breakpoint on 'prompt:test-cmdlet'
test-cmdlet
# [DBG]: C:\PS>
Отладка удаленных скриптов
Начиная с PowerShell 5.0, отладчик PowerShell можно запускать в удаленном сеансе либо в консоли, либо в Windows PowerShell ISE.
Enter-PSSession функциональность была обновлена, чтобы вы смогли повторно подключиться к отключенным сеансам, который выполняется на удаленном компьютере и в настоящее время выполняет скрипт. Если выполняющийся скрипт достигает точки останова, сеанс клиента автоматически запускает отладчик.
Ниже приведен пример, показывающий, как это работает с точками останова, заданными в скрипте в строках 6, 11, 22 и 25. Обратите внимание, что в примере при запуске отладчика отображаются два идентифицирующие запроса: имя компьютера, на котором выполняется сеанс, и запрос DBG, который сообщает, что вы находитесь в режиме отладки.
Enter-Pssession -Cn localhost
[localhost]: PS C:\psscripts> Set-PSBreakpoint .\ttest19.ps1 6,11,22,25
ID Script Line Command Variable Action
-- ------ ---- ------- -------- ------
0 ttest19.ps1 6
1 ttest19.ps1 11
2 ttest19.ps1 22
3 ttest19.ps1 25
[localhost]: PS C:\psscripts> .\ttest19.ps1
Hit Line breakpoint on 'C:\psscripts\ttest19.ps1:11'
At C:\psscripts\ttest19.ps1:11 char:1
+ $winRMName = "WinRM"
# + ~
[localhost]: [DBG]: PS C:\psscripts>> list
6: 1..5 | foreach { sleep 1; Write-Output "hello2day $_" }
7: }
# 8:
9: $count = 10
10: $psName = "PowerShell"
11:* $winRMName = "WinRM"
12: $myVar = 102
# 13:
14: for ($i=0; $i -lt $count; $i++)
15: {
16: sleep 1
17: Write-Output "Loop iteration is: $i"
18: Write-Output "MyVar is $myVar"
# 19:
20: hello2day
# 21:
[localhost]: [DBG]: PS C:\psscripts>> stepover
At C:\psscripts\ttest19.ps1:12 char:1
+ $myVar = 102
# + ~
[localhost]: [DBG]: PS C:\psscripts>> quit
[localhost]: PS C:\psscripts> Exit-PSSession
PS C:\psscripts>
Примеры
Этот тестовый скрипт определяет версию операционной системы и отображает соответствующее системе сообщение. Он включает функцию, вызов функции и переменную.
Следующая команда отображает содержимое файла тестового скрипта:
PS C:\PS-test> Get-Content test.ps1
function psversion {
"PowerShell " + $PSVersionTable.PSVersion
if ($PSVersionTable.PSVersion.Major -lt 6) {
"Upgrade to PowerShell 6.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
Когда скрипт достигает первой точки останова, сообщение точки останова указывает, что отладчик активен. Он описывает точку останова и просматривает первую строку скрипта, который является объявлением функции. Командная строка также изменится, чтобы указать, что отладчик имеет управление.
Строка предварительного просмотра содержит имя скрипта и номер строки предварительной команды.
Entering debug mode. Use h or ? for help.
Hit Line breakpoint on '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 для выполнения текущей инструкции и предварительного просмотра следующей инструкции в скрипте. Следующая инструкция вызывает функцию PsVersion.
DBG> s
test.ps1:12 psversion
На этом этапе $scriptName переменная заполняется, но вы проверяете значение переменной, отображая ее значение. В этом случае в качестве значения задается путь к скрипту.
DBG> $scriptName
C:\ps-test\test.ps1
Используйте другую команду Step, чтобы выполнить вызов функции. Нажмите клавишу ВВОД или введите "s" в поле Шаг.
DBG> s
test.ps1:2 "PowerShell " + $PSVersionTable.PSVersion
Сообщение об отладке содержит предварительный просмотр инструкции в функции . Для выполнения этой инструкции и предварительного просмотра следующей инструкции в функции можно использовать Step команду . Но в этом случае используйте команду StepOut (o). Он завершает выполнение функции (если не достигает точки останова) и выполняет шаги к следующему оператору в скрипте.
DBG> o
Windows PowerShell 2.0
Have you run a background job today (start-job)?
test.ps1:13 "Done $scriptName"
Так как мы работаем с последней инструкцией в скрипте, команды StepOut и Continue имеют одинаковый эффект. В этом случае используйте StepOut (o).
Done C:\ps-test\test.ps1
PS C:\ps-test>
Команда StepOut выполняет последнюю команду. Стандартная командная строка указывает, что отладчик завершил работу и вернул управление обработчику команд.
Теперь снова запустите отладчик. Во-первых, чтобы удалить текущую точку останова Get-PSBreakpoint , используйте командлеты и Remove-PSBreakpoint . (Если вы считаете, что вы можете повторно использовать точку останова Disable-PSBreakpoint , используйте командлет вместо Remove-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
Hit Variable breakpoint on 'C:\ps-test\test.ps1:$scriptName'
(Write access)
test.ps1:11 $scriptName = $MyInvocation.MyCommand.Path
# DBG>
Отображение текущего значения переменной $scriptName , равного $null.
DBG> $scriptName
# DBG>
Используйте команду Step для выполнения инструкции, которая заполняет переменную.
Затем отобразится новое значение переменной $scriptName .
DBG> $scriptName
C:\ps-test\test.ps1
```powershell
Use a Step command (s) to preview the next statement in the script.
```powershell
DBG> s
test.ps1:12 psversion
Следующий оператор является вызовом функции PsVersion. Чтобы пропустить функцию, но выполнить ее, используйте команду StepOver (v). Если вы уже используете функцию StepOver, она не будет действовать. Вызов функции отображается, но не выполняется.
DBG> v
Windows PowerShell 2.0
Have you run a background job today (start-job)?
test.ps1:13 "Done $scriptName"
Команда StepOver выполняет функцию и просматривает следующую инструкцию в скрипте, который выводит заключительную строку.
Используйте команду 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
Hit Command breakpoint on '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
Hit Command breakpoint on '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=[]
В этом примере демонстрируется лишь несколько способов использования отладчика PowerShell.
Для получения дополнительных сведений о командлетах отладчика введите следующую команду:
help <cmdlet-name> -full
Например, введите:
help Set-PSBreakpoint -full
Другие функции отладки в PowerShell
Помимо отладчика PowerShell, PowerShell включает несколько других функций, которые можно использовать для отладки скриптов и функций.
Windows PowerShell ISE включает интерактивный графический отладчик. Для получения дополнительных сведений запустите Windows PowerShell ISE и нажмите клавишу F1.
Командлет
Set-PSDebugпредлагает базовые функции отладки скриптов, включая пошаговое выполнение и трассировку.Set-StrictModeИспользуйте командлет для обнаружения ссылок на неинициализированные переменные, ссылки на несуществующие свойства объекта и недопустимый синтаксис функций.Добавьте диагностические инструкции в скрипт, например операторы, отображающие значение переменных, операторы, считывающие входные данные из командной строки, или операторы, сообщающие о текущей инструкции. Используйте командлеты, содержащие команду Write для этой задачи, например
Write-Host,Write-Debug,Write-WarningиWrite-Verbose.