РАЗДЕЛ
    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




Содержание