Compartilhar via

about_Debuggers

Descrição curta

Descreve o depurador do PowerShell.

Descrição longa

A depuração é o processo de examinar um script enquanto ele está em execução para identificar e corrigir erros nas instruções de script. O depurador do PowerShell pode ajudá-lo a examinar e identificar erros e ineficiências em seus scripts, funções, comandos, configurações de DSC (Configuração de Estado Desejado) do PowerShell ou expressões.

A partir do PowerShell 5.0, o depurador do PowerShell foi atualizado para depurar scripts, funções, comandos, configurações ou expressões que estão em execução no console ou no ISE (Ambiente de Script Integrado) do Windows PowerShell em computadores remotos.

Nota

O ISE do Windows PowerShell só dá suporte ao Windows PowerShell. Para o PowerShell 6 e superior, você deve usar o Visual Studio Code com a extensão do PowerShell. Para obter mais informações, consulte Depuração com o Visual Studio Code.

Cmdlets do depurador

O depurador do 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 os pontos de interrupção na sessão atual.
  • Enable-PSBreakpoint: habilita novamente os 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 e execute o script, o comando ou a função que você deseja depurar.

Quando você chega a um ponto de interrupção, a execução é interrompida e o controle é entregue ao depurador.

Para interromper o depurador, execute o script, o comando ou a função até que ele seja concluído. Ou digite stop ou t.

Comandos do depurador

Ao usar o depurador no console do PowerShell, use os comandos a seguir para controlar a execução. No ISE do Windows PowerShell, use comandos no menu Depurar.

Nota

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

  • s, StepInto: executa a próxima instrução e, em seguida, para.

  • v, StepOver: executa a próxima instrução, mas ignora funções e invocações. As instruções ignoradas são executadas, mas não executadas.

  • Ctrl+Break: (Dividir Tudo no ISE) divide um script em execução no console do PowerShell ou no ISE do Windows PowerShell. Observe que Ctrl+Break no Windows PowerShell 2.0, 3.0 e 4.0 fecha o programa. O Break All funciona em scripts locais e remotos em execução interativa.

  • o, StepOut: sai da função atual; até um nível se aninhado. Se estiver no corpo principal, ele continuará até o final ou o próximo ponto de interrupção. As instruções ignoradas são executadas, mas não executadas.

  • c, Continue: continua a ser executado até que o script seja concluído ou até que o próximo ponto de interrupção seja atingido. As instruções ignoradas são executadas, mas não executadas.

  • l, List: exibe a parte do script em execução. Por padrão, ele exibe a linha atual, cinco linhas anteriores e 10 linhas subsequentes. Para continuar listando o script, pressione ENTER.

  • l <m>, List: exibe 16 linhas do script começando com o número de linha especificado por <m>.

  • l <m> <n>, List: exibe <n> linhas do script, começando com o número de linha especificado por <m>.

  • q, Stop, Exit: interrompe a execução do script e sai do depurador. Se você estiver depurando um trabalho executando o cmdlet Debug-Job, o comando Exit desanexa o depurador e permite que o trabalho continue em execução.

  • k, Get-PSCallStack: exibe a pilha de chamadas atual.

  • <Enter>: repete o último comando se for Step (s), StepOver (v) ou List (l). Caso contrário, representa uma ação de envio.

  • ?, h: exibe a Ajuda de comando do depurador.

Para sair do depurador, você pode usar Stop (q).

A partir do PowerShell 5.0, você pode executar o comando Exit para sair de uma sessão de depuração aninhada iniciada executando Debug-Job ou Debug-Runspace.

Usando esses comandos de depurador, você pode executar um script, parar em um ponto de preocupação, examinar os valores das variáveis e o estado do sistema e continuar executando o script até que você tenha identificado um problema.

Nota

Se você entrar em uma instrução com um operador de redirecionamento, como >, o depurador do PowerShell percorrerá todas as instruções restantes no script.

Exibindo os valores das variáveis de script

Enquanto estiver no depurador, você também pode inserir comandos, exibir o valor das variáveis, usar cmdlets e executar scripts na linha de comando. Você pode exibir o valor atual de todas as variáveis no script que está sendo depurado, exceto pelas seguintes variáveis automáticas:

$_
$args
$input
$MyInvocation
$PSBoundParameters

Quando você exibe o valor de qualquer uma dessas variáveis, obtém o valor dessa variável para um pipeline interno que o depurador usa, não o valor da variável no script.

Para exibir o valor dessas variáveis para o script que está sendo depurado, adicione linhas ao script para salvar esses valores em uma nova variável. Defina o ponto de interrupção após essas novas linhas. Em seguida, você pode exibir o valor da nova variável.

Por exemplo

$scriptArgs = $args
$scriptname = $MyInvocation.PSCommandPath

O ambiente do depurador

Quando você chegar a um ponto de interrupção, insira o ambiente do depurador. O prompt de comando é alterado para que ele comece com "[DBG]:". Além disso, em alguns aplicativos host, como o console do PowerShell, um prompt aninhado é aberto para depuração. Você pode detectar o prompt aninhado repetindo caracteres maiores que (ASCII 62) que aparecem no prompt de comando.

Para obter mais informações sobre como personalizar o prompt, consulte about_Prompts.

Você pode encontrar o nível de aninhamento usando a variável $NestedPromptLevel automática. A variável automática, $PSDebugContext, é definida no escopo local. Você pode usar a presença da variável $PSDebugContext para determinar se você está executando dentro do depurador.

Por exemplo:

if ($PSDebugContext) {"Debugging"} else {"Not Debugging"}

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

[DBG]: PS>>> $PSDebugContext.InvocationInfo

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

Depuração e escopo

Invadir o depurador não altera o escopo no qual você está operando, mas quando você atinge um ponto de interrupção em um script, você passa para o 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 no escopo local (script):

Get-Variable -Scope 0

Essa é uma maneira útil de ver apenas as variáveis que você definiu no script e que você definiu durante a depuração.

Depuração na linha de comando

Ao definir um ponto de interrupção de variável ou um ponto de interrupção de comando, você pode definir o ponto de interrupção apenas em um arquivo de script. No entanto, por padrão, o ponto de interrupção é definido em qualquer coisa que seja executada na sessão atual.

Por exemplo, se você definir um ponto de interrupção na variável $name, o depurador será interrompido em qualquer variável de $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 podem ser afetados por funções, variáveis e outros scripts na sessão e no perfil do usuário.

Os pontos de interrupção de linha são específicos para arquivos de script, portanto, são definidos apenas em arquivos de script.

Funções de depuração

Quando você define um ponto de interrupção em uma função que tem seções begin, processe 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
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>

Depurando scripts remotos

Você pode executar Enter-PSSession para iniciar uma sessão interativa do PowerShell remota na qual você pode definir pontos de interrupção e depurar arquivos de script e comandos no computador remoto. Enter-PSSession permite reconectar uma sessão desconectada que está executando um script ou comando em um computador remoto. Se o script em execução atingir um ponto de interrupção, a sessão do cliente iniciará automaticamente o depurador. Se a sessão desconectada que está executando um script já tiver atingido um ponto de interrupção, Enter-PSSession iniciará automaticamente o depurador de linha de comando quando você se reconectar à sessão.

O exemplo a seguir mostra como isso funciona. Os pontos de interrupção foram definidos nas linhas 6, 11, 22 e 25 do script. Quando o depurador é iniciado, há duas alterações de identificação no prompt:

  • O nome do computador no qual a sessão está em execução
  • O prompt DBG que permite que você saiba que você está no modo de depuração
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>

Exemplos

Esse script de teste detecta a versão do PowerShell e exibe uma mensagem apropriada à versão. 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:

PS C:\PS-test>  Get-Content test.ps1

function psversion {
  "PowerShell " + $PSVersionTable.PSVersion
  if ($PSVersionTable.PSVersion.Major -lt 7) {
    "Upgrade to PowerShell 7!"
  }
  else {
    "Have you run a background job today (Start-Job)?"
  }
}

$scriptName = $MyInvocation.PSCommandPath
psversion
"Done $scriptName."

Para começar, defina um ponto de interrupção em um ponto de interesse no script, como uma linha, um comando, uma variável ou uma 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

O comando retorna um objeto 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 atinge o primeiro ponto de interrupção, a mensagem de 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 controle.

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

Entering debug mode. Use h or ? for help.

Hit Line breakpoint on 'C:\ps-test\test.ps1:1'

test.ps1:1   function psversion {
DBG>

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

DBG> s
test.ps1:11  $scriptName = $MyInvocation.PSCommandPath

Neste ponto, a variável $scriptName não é preenchida, 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 visualizar a próxima instrução no script. A próxima instrução chama a função psversion.

DBG> s
test.ps1:12  psversion

Neste ponto, a $scriptName variável é preenchida, mas você verifica o valor da variável. Nesse caso, o valor é definido como o caminho do script.

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

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

DBG> s
test.ps1:2       "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, você pode usar um comando Step. Mas, nesse caso, use um comando StepOut (o). Ele conclui a execução da função (a menos que atinja um ponto de interrupção) e etapas para a próxima instrução no script.

DBG> o
Windows PowerShell 2.0
Have you run a background job today (Start-Job)?
test.ps1:13  "Done $scriptName"

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

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

O comando StepOut executa o último comando. O prompt de comando padrão indica que o depurador saiu e retornou o controle para o processador de comandos.

Agora, execute o depurador novamente. Primeiro, 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 este comando como:

PS C:\ps-test> gbp | rbp

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

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

Você pode abreviar o comando como:

PS C:\ps-test> sbp -V scriptname -S test.ps1

Agora, inicie o script. O script atinge o ponto de interrupção variável. O modo padrão é Gravação, portanto, a execução é interrompida pouco antes da instrução que altera o valor da variável.

PS C:\ps-test> .\test.ps1
Hit Variable breakpoint on 'C:\ps-test\test.ps1:$scriptName'
(Write access)

test.ps1:11  $scriptName = $MyInvocation.PSCommandPath
DBG>

Exiba o valor atual da variável $scriptName, que é $null.

DBG> $scriptName
DBG>

Use um comando Step (s) para executar a instrução que preenche 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 StepOver (v). Se você já estiver na função quando usar StepOver, ela não será eficaz. A chamada de função é exibida, mas não é executada.

DBG> v
Windows PowerShell 2.0
Have you run a background job today (Start-Job)?
test.ps1:13  "Done $scriptName"

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

Use um comando Stop (t) para sair do depurador. O prompt de comando é revertido 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 este comando para:

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

Agora, execute o script.

PS C:\ps-test> .\test.ps1
Hit Command breakpoint on 'C:\ps-test\test.ps1:psversion'

test.ps1:12  psversion
DBG>

O script atinge o ponto de interrupção na chamada de função. Neste ponto, a função ainda não foi chamada. Isso oferece 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 de segurança.

Para definir uma ação, use um comando Continue (c) para sair do script e um comando Remove-PSBreakpoint para excluir o ponto de interrupção atual. (Os pontos de interrupção são somente leitura, portanto, você não pode adicionar uma ação ao ponto de interrupção atual.)

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>

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 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 é interrompida. O backtick (`) é o caractere de continuação de linha.

PS C:\ps-test> Set-PSBreakpoint -Command psversion -Script test.ps1  `
-Action { Add-Content "The value of `$scriptName is $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 será executado somente se a política de execução estiver definida como RemoteSigned, a política mais restritiva que ainda permite executar scripts.

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 orienta o depurador a executar o ponto de interrupção. Você também pode usar a palavra-chave continue para direcionar o depurador a ser executado sem interrupções. Como a palavra-chave padrão é continue, você deve especificar break para interromper a execução.

Agora, execute o script.

PS C:\ps-test> .\test.ps1
Hit Command breakpoint on 'C:\ps-test\test.ps1:psversion'

test.ps1:12  psversion

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

Neste ponto, talvez você queira verificar a pilha de chamadas. Use o cmdlet Get-PSCallStack ou o comando Get-PSCallStack depurador (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 apenas algumas das várias maneiras de usar o depurador do PowerShell.

Outros recursos de depuração no PowerShell

Além do depurador do PowerShell, o PowerShell inclui vários outros recursos que você pode usar para depurar scripts e funções.

  • O cmdlet Set-PSDebug oferece recursos de depuração de script muito básicos, incluindo etapas e rastreamento.

  • Use o cmdlet Set-StrictMode para detectar referências a variáveis não inicializadas, para fazer referência a propriedades inexistentes de um objeto e para a sintaxe de função que não é válida.

  • Adicione instruções de diagnóstico a um script, como instruções que exibem o valor de variáveis, instruções que leem a entrada da linha de comando ou instruções que relatam a instrução atual. Use os cmdlets que contêm o verbo De gravação para esta tarefa, como Write-Host, Write-Debug, Write-Warninge Write-Verbose.

Consulte também

  • Last updated on