TÓPICO
    about_Debuggers

DESCRIÇÃO RESUMIDA
    Descreve o depurador do Windows PowerShell.


DESCRIÇÃO LONGA
    A depuração é o processo de examinar um script durante sua 
    execução para identificar e corrigir erros nas instruções do script. O 
    depurador do Windows PowerShell foi criado para ajudar você a examinar e 
    identificar erros e ineficiências em seus scripts.
  

    Observação: o depurador do Windows PowerShell não é executado 
    		remotamente. Para depurar um script em um computador remoto, 
    		copie o script para o computador local.


    Você pode usar os recursos do depurador do Windows PowerShell 
    para examinar um script, uma função, um comando ou uma expressão 
    do Windows PowerShell durante a execução. O depurador do Windows 
    PowerShell inclui um conjunto de cmdlets que permitem definir 
    pontos de interrupção, gerenciar pontos de interrupção e exibir a 
    pilha de chamadas.
 

    O Windows PowerShell oferece vários métodos para depurar scripts, 
    funções e comandos.


    Método 1: o cmdlet Set-PsDebug oferece recursos básicos de 
    	      depuração de scripts, como inspeção e rastreamento. Para obter 
    	      informações, digite:
              "get-help set-psdebug".


    Método 2: use o cmdlet Set-StrictMode para detectar referências a 
    	      variáveis não inicializadas, referências a propriedades 
    	      inexistentes de um objeto e à sintaxe de função inválida.


    Método 3: adicione instruções de diagnóstico a um script, como 
    	      instruções que exibem o valor de variáveis, instruções que leem 
    	      entradas da linha de comando ou instruções que informam a 
    	      instrução atual. Use os cmdlets que contêm o verbo Write para 
    	      essa tarefa, como Write-Host, Write-Debug, Write-Warning e 
    	      Write-Verbose.

    Método 4: use o depurador do Windows PowerShell para depurar um 
    	      script. Ou use o depurador para depurar um bloco de função ou 
    	      script que você digitou no prompt de comando. Você pode definir 
    	      pontos de interrupção, inspecionar o script, examinar os valores de 
    	      variáveis, executar diagnósticos e comandos de log e exibir a pilha 
    	      de chamadas. 
    
  Cmdlets do depurador
      O depurador do Windows PowerShell inclui o seguinte conjunto de 
      cmdlets:


          Set-PsBreakpoint: define pontos de interrupção em linhas, 
          		    variáveis e comandos. 

          Get-PsBreakpoint: obtém pontos de interrupção na sessão atual.

          Disable-PsBreakpoint: desativa pontos de interrupção na 
          			sessão atual.

          Enable-PsBreakpoint: reabilita pontos de interrupção na 
          		       sessão atual.

          Remove-PsBreakpoint: exclui pontos de interrupção da sessão 
          		       atual.

          Get-PsCallStack: exibe a pilha de chamadas atual. 


  Iniciando e parando o depurador
      Para iniciar o depurador, defina um ou mais pontos de 
      interrupção. Em seguida, execute o script, o comando ou a 
      função que você deseja depurar. 


      Quando você alcançar um ponto de interrupção, a execução será 
      parada e o controle será repassado ao depurador.


      Para parar o depurador, execute o script, comando ou função até 
      que a conclusão. Ou digite "stop" ou "t". 
  

  Comandos de depurador
      Quando usar o depurador no console do Windows PowerShell, use 
      os seguintes comandos para controlar a execução.
    

      Observação: para obter informações sobre como usar o depurador 
      		  em outros aplicativos host, consulte a documentação do 
      		  aplicativo host.


 	s, Step-into        Executa a próxima instrução e para.


 	v, Step-over        Executa a próxima instrução, mas ignora 
 			    funções e invocações. As instruções ignoradas 
			    são executadas, mas não inspecionadas.


 	o, Step-out         Sai da função atual; um nível acima se 
 			    aninhado. Se estiver no corpo principal, 
 			    continua até o término do próximo ponto de 
 			    interrupção. As instruções ignoradas são 
 			    executadas, mas não inspecionadas.


 	c, Continue         Continua a execução até que o script seja 
 			    concluído ou até alcançar o próximo ponto 
 			    de interrupção. As instruções ignoradas 
 			    são executadas, mas não inspecionadas.


        l, List             Exibe a parte do script que está em 
 			    execução. Por padrão, exibe a linha atual, 
 			    as cinco linhas anteriores e as 10 linhas 
 			    subsequentes. Para continuar listando 
 			    o script, pressione ENTER.
                        

        l <m>, List         Exibe 16 linhas do script 
 			    começando no número da linha especificado por <m>.                           

        l <m> <n>, List     Exibe <n> linhas de script, começando no 
 			    número da linha especificado por <m>.                           

        q, Stop             Para a execução do script e fecha o depurador.


        k, Get-PsCallStack  Exibe a pilha de chamadas atual.


	<Enter>             Repete o último comando caso tenha sido Step (s), 
 			    Step-over (v) ou List (l). Caso contrário, 
 			    representa um ação de envio. 
                           

	?, h                Exibe o comando Ajuda do depurador.


      Para fechar o depurador, use Stop (q).


      Enquanto estiver no depurador, você poderá também inserir 
      comandos, exibir o valor de variáveis, usar cmdlets e executar 
      scripts.


      Usando esses comandos do depurador, você pode executar um 
      script, parar em um ponto de interesse, examinar os valores de 
      variáveis e o estado do sistema e continuar a executar o script até 
      identificar um problema. 


  O ambiente do depurador
      Ao alcançar um ponto de interrupção, você entra no ambiente do 
      depurador. O prompt de comando se altera para começar com 
      "[DBG]:". Você pode personalizar o prompt.

     
      Além disso, em alguns aplicativos host, como o console do Windows 
      PowerShell (mas não no Windows PowerShell ISE (Integrated Scripting 
      Environment)), um aviso aninhado é aberto para depuração. Você pode 
      detectar o aviso aninhado pela repetição de caracteres maior que 
      (ASCII 62) que aparecem no prompt de comando.


      Por exemplo, a seguir é mostrado o prompt de depuração padrão 
      no Windows PowerShell.


          [DBG]: PS (get-location)>>>


      Você pode descobrir o nível de aninhamento usando a variável 
      automática $NestedPromptLevel.


      Além disso, uma variável automática, $PSDebugContext, é 
      definida no escopo local. É possível usar a presença da variável 
      $PsDebugContext para determinar se você está no depurador.


      Por exemplo:

 
          if ($psdebugcontext) {"Depurando"} else {"Não depurando"}


      Você pode usar o valor da variável $PSDebugContext em sua depuração.


	[DBG]: PS>>> $psdebugcontext.invocationinfo

        Name   CommandLineParameters  UnboundArguments  Location
        ----   ---------------------  ----------------  --------
        =      {}                     {}                C:\ps-test\vote.ps1 (1)
        

  Depuração e escopo
      Interromper o depurador não altera o escopo em que você está 
      operando, mas ao alcançar um ponto de interrupção em um script, 
      você entra no escopo do script. O escopo do script é um filho 
      do escopo no qual você executou o depurador.


      Para localizar as variáveis e os aliases definidos no escopo do 
      script, use o parâmetro Scope dos cmdlets Get-Alias ou Get-Variable.


      Por exemplo, o comando a seguir obtém as variáveis visíveis no 
      escopo (de script) local:


	  get-variable -scope 0


      É possível abreviar o comando como:


	gv -s 0


      Esta é uma maneira útil de ver apenas as variáveis definidas no 
      script e definidas durante a depuração.


  Depurando na linha de comando
      Ao definir um ponto de interrupção de variável ou um ponto de 
      interrupção de comando, você só pode definir o ponto de 
      interrupção em um arquivo de script. Porém, por padrão, o ponto de 
      interrupção é definido em algo que seja executado na sessão atual. 


      Por exemplo, se você definir um ponto de interrupção na 
      variável $name, o depurador interromperá qualquer variável $name em 
      qualquer script, comando, função, cmdlet de script ou expressão que você 
      executar até desabilitar ou remover o ponto de interrupção.


      Isso permite que você depure seus scripts em um contexto mais 
      realista no qual eles possam ser afetados por funções, 
      variáveis e outros scripts na sessão e no perfil do usuário.


      Pontos de interrupção de linha são específicos de arquivos de 
      script, razão pela qual são definidos apenas em arquivos de script. 


  Depurando funções
      Quando você define um ponto de interrupção em uma função que 
      tem seções Begin, Process e End, o depurador é interrompido na 
      primeira linha de cada seção.


      Por exemplo:


              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
          Entrando no modo de depuração. Use h ou ? para obter ajuda.

          Atingir Ponto de interrupção de comando em 'prompt:my-alias'

          test-cmdlet

          [DBG]: C:\PS> c
          Process
          Entrando no modo de depuração. Use h ou ? para obter ajuda.

          Atingir Ponto de interrupção de comando em 'prompt:my-alias'

          test-cmdlet

          [DBG]: C:\PS> c
          End
          Entrando no modo de depuração. Use h ou ? para obter ajuda.

          Atingir Ponto de interrupção de comando em 'prompt:my-alias'

          test-cmdlet

          [DBG]: C:\PS> 


  Depurando scripts remotos
      Você não pode executar o depurador do Windows PowerShell em uma 
      sessão remota. Para depurar um script em um computador remoto, 
      copie o script para o computador local.


      O comando a seguir copia o script Test.ps1 do computador remoto 
      Servidor01 para o computador local. 


          invoke-command -computername Servidor01 ` 
	  {get-content c:\ps-test\test.ps1} | set-location c:\ps-test\test.ps1


  Exemplos
      Este script de teste detecta a versão do sistema operacional e 
      exibe uma mensagem apropriada do sistema. Ele inclui uma função, uma 
      chamada de função e uma variável. 


      O comando a seguir exibe o conteúdo do arquivo de script de teste:

	
	  c:>\PS-test> get-content test.ps1


	  function psversion {
             "Windows Powershell " + $psversiontable.psversion if 
             ($psversiontable.psversion.major -lt 2) { 
		 "Atualize para o Windows PowerShell 2.0!" 
	      }
              else {
                  "Já executou um trabalho em segundo plano hoje 
                  (start-job)?" 
	      }
          }

	  $scriptname = $MyInvocation.MyCommand.Path
	  psversion
	  "$scriptname concluído."


      Para iniciar, defina um ponto de interrupção em um ponto de 
      interesse no script, como uma linha, um comando, uma variável 
      ou função.
 

      Comece criando um ponto de interrupção de linha na primeira linha do 
      script Test.ps1 no diretório atual.


          PS C:\ps-test> set-psbreakpoint -line 1 -script test.ps1 


      Você pode abreviar esse comando como:


          PS C:\ps-test> spb 1 -s test.ps1

        
      O comando retorna um objeto de ponto de interrupção de linha 
      (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
	

      Agora, inicie o script.


	  PS C:\ps-test> .\test.ps1


      Quando o script alcança o primeiro ponto de interrupção, a 
      mensagem do ponto de interrupção indica que o depurador está 
      ativo. Ele descreve o ponto de interrupção e visualiza a 
      primeira linha do script, que é uma declaração de função. O 
      prompt de comando também é alterado para indicar que o 
      depurador tem o controle.


      A linha de visualização inclui o nome do script e o número da 
      linha do comando visualizado.


          Entrando no modo de depuração. Use h ou ? para obter ajuda.

          Atingir Ponto de interrupção de linha em 'C:\ps-test\test.ps1:1'

          test.ps1:1  function psversion {
          DBG>


      Use o comando Step (s) para executar a primeira instrução no 
      script e para visualizar a próxima instrução. A próxima 
      instrução usa a variável automática $MyInvocation para definir 
      o valor da variável $ScriptName como o caminho e o nome do 
      arquivo de script.


          DBG> s
          test.ps1:11 $scriptname = $MyInvocation.MyCommand.Path


      Nesse momento, a variável $ScriptName não é populada, mas você pode 
      verificar o valor da variável exibindo seu valor. Nesse caso, o valor 
      é $null.


          DBG> $scriptname
          DBG>

    
      Use outro comando Step (s) para executar a instrução atual e para 
      visualizar a próxima instrução no script. A próxima instrução chama a 
      função PsVersion.


	  DBG> s
	  test.ps1:12 psversion


      Nesse momento, a variável $ScriptName é populada, mas você 
      verifica o valor da variável exibindo seu valor. Nesse caso, o 
      valor é definido como o caminho de script.


          DBG> $scriptname
          C:\ps-test\test.ps1
   

      Use outro comando Step para executar a chamada de função. 
      Pressione ENTER ou digite "s" de Step.


	  DBG> s
	  test.ps1:2       "Windows Powershell " + $psversiontable.psversion
	  

      A mensagem de depuração inclui uma visualização da instrução na 
      função.Para executar essa instrução e visualizar a próxima instrução 
      na função, use um comando Step. Mas, nesse caso, use um comando 
      Step-Out (o). Ele conclui a execução da função (a menos que 
      alcance um ponto de interrupção) e avança até a próxima instrução no 
      script.


	  DBG> o
	  Windows PowerShell 2.0
	  Já executou um trabalho em segundo plano hoje (start-job)?
	  test.ps1:13 "$scriptname concluído"


      Como estamos na última instrução no script, os comandos Step, 
      Step-Out e Continue têm o mesmo efeito. Nesse caso, use 
      Step-Out (o). 


	  C:\ps-test\test.ps1 concluído
	  PS C:\ps-test>


      O comando Step-Out executa o último comando. O prompt de 
      comando padrão indica que o depurador foi fechado e devolveu o 
      controle ao processador de comandos.


      Agora, execute o depurador novamente. Em primeiro lugar, para 
      excluir o ponto de interrupção atual, use os cmdlets 
      Get-PsBreakpoint e Remove-PsBreakpoint.(Se você acha que pode 
      reutilizar o ponto de interrupção, use o cmdlet 
      Disable-PsBreakpoint em vez de Remove-PsBreakpoint.)


	  PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint


      Você pode abreviar esse comando como:


	  PS C:\ps-test> gbp | rbp


      Ou execute o comando escrevendo uma função, como a seguinte:


	  function delbr { gbp | rbp }


      Agora, crie um ponto de interrupção na variável $scriptname. 


	  PS C:\ps-test> set-psbreakpoint -variable scriptname -script test.ps1


      É possível abreviar o comando como: 


	  PS C:\ps-test> sbp -v scriptname -s test.ps1


      Agora, inicie o script. O script alcança o ponto de interrupção da 
      variável. O modo padrão é Write, para que a execução seja interrompida 
      imediatamente antes da instrução que altera o valor da variável.


	  PS C:\ps-test> .\test.ps1
	  Atingir Ponto de interrupção de variável em 'C:\ps-
	  test\test.ps1:$scriptname' (acesso para gravação)

	  test.ps1:11 $scriptname = $MyInvocation.mycommand.path 


      Exibe o valor atual da variável $scriptname, que é $null.


          DBG> $scriptname
          DBG>

      Use um comando Step (s) para executar a instrução que popula a 
      variável. Em seguida, exiba o novo valor da variável $scriptname.


	  DBG> $scriptname
	  C:\ps-test\test.ps1


      Use um comando Step (s) para visualizar a próxima instrução no 
      script.


	  DBG> s
	  test.ps1:12 psversion

   
      A próxima instrução é uma chamada para a função PsVersion. Para 
      ignorar a função mas ainda executá-la, use um comando Step-Over 
      (v). Se você ainda estiver na função quando usar Step-Over, ele não 
      funcionará. A chamada de função é exibida, mas não é executada.

	
	  DBG> v
	  Windows PowerShell 2.0
	  Já executou um trabalho em segundo plano hoje (start-job)?
	  test.ps1:13 "$scriptname concluído"  


      O comando Step-Over executa a função e visualiza a próxima 
      instrução no script, que imprime a linha final.


      Use um comando Stop (t) para fechar o depurador. O prompt de comando 
      reverte para o prompt de comando padrão.


	  C:\ps-test>


      Para excluir os pontos de interrupção, use os cmdlets 
      Get-PsBreakpoint e Remove-PsBreakpoint.


	  PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint


      Crie um novo ponto de interrupção de comando na função PsVersion.


          PS C:\ps-test> Set-PsBreakpoint -command psversion -script test.ps1 


      Você pode abreviar esse comando para:


          PS C:\ps-test> sbp -c psversion -s test.ps1 


      Agora, execute o script.	


          PS C:\ps-test> .\test.ps1
          Atingir Ponto de interrupção de comando em 'C:\ps-
          test\test.ps1:psversion'

          test.ps1:12 psversion
          DBG>


      O script alcança o ponto de interrupção na chamada de função. Nesse 
      momento, a função ainda não foi chamada. Isso dá a você a oportunidade 
      de usar o parâmetro Action de Set-PsBreakpoint para definir condições 
      para a execução do ponto de interrupção ou para executar tarefas 
      preparatórias ou de diagnóstico, como iniciar um log ou invocar um 
      script de diagnóstico ou segurança.


      Para definir uma ação, use um comando Continue (c) para fechar 
      o script e um comando Remove-PsBreakpoint para excluir o ponto de 
      interrupção atual. (Pontos de interrupção são somente leitura, para 
      que você não possa adicionar uma ação ao ponto de interrupção atual.)


	  DBG> c
	  Windows PowerShell 2.0
	  Já executou um trabalho em segundo plano hoje (start-job)?
	  C:\ps-test\test.ps1 concluído

	  PS C:\ps-test> get-psbreakpoint | remove-psbreakpoint
	  PS C:\ps-test>


      Agora, crie um novo ponto de interrupção de comando com uma ação. O 
      comando a seguir define um ponto de interrupção de comando com uma 
      ação que registra em log o valor da variável $scriptname quando a 
      função é chamada. Como a palavra-chave Break não é usada na ação, 
      a execução não para. (O indicador de crase (`) é o caractere de 
      continuação de linha.)


         PS C:\ps-test> set-psbreakpoint -command psversion -script test.ps1 `
         -action { add-content "O valor de `$scriptname é $scriptname." ` 
         -path action.log}


      Você também pode adicionar ações que definem condições para o 
      ponto de interrupção. No comando a seguir, o ponto de interrupção de 
      comando é executado apenas se a diretiva de execução estiver definida como 
      RemoteSigned, a diretiva mais restritiva que ainda permite executar 
      scripts. (O acento indicador de crase (`) é um caractere de 
      continuação.)  


          PS C:\ps-test> set-psbreakpoint -script test.ps1 -command psversion `
          -action { if ((get-executionpolicy) -eq "RemoteSigned") { break }}


      A palavra-chave Break na ação conduz o depurador para a 
      execução do ponto de interrupção. Você também pode usar a 
      palavra-chave Continue para conduzir o depurador a executar sem 
      interromper. Como a palavra-chave padrão é Continue, você precisa 
      especificar Break para parar a execução.


      Agora, execute o script.


	  PS C:\ps-test> .\test.ps1
	  Atingir Ponto de interrupção de comando em 'C:\ps-
	  test\test.ps1:psversion'

	  test.ps1:12 psversion

    
      Como a diretiva de execução está definida como RemoteSigned, a 
      execução é interrompida na chamada de função.


      Nesse momento, convém verificar a pilha de chamadas. Use the Get-
      PsCallStack cmdlet or the Get-PsCallStack debugger command (k).
      O comando a seguir obtém a pilha de chamadas atual.


	  DBG> k
	  2: prompt
	  1: .\test.ps1: $args=[]
	  0: prompt: $args=[]


      Este exemplo demonstra alguns dos muitos modos de usar o 
      depurador do Windows PowerShell. 


      Para obter mais informações sobre os cmdlets do depurador, digite o 
      comando a seguir:


          help <nome-cmdlet> -full


      Por exemplo, digite:


          help set-psbreakpoint -full


CONSULTE TAMBÉM
    Disable-PsBreakpoint
    Get-PsBreakpoint  
    Remove-PsBreakpoint
    Set-PsBreakpoint 
    Set-PsDebug
    Set-Strictmode
    Write-Debug
    Write-Verbose  
    Enable-PsBreakpoint
    Get-PsCallStack




Sumário