Compartilhar via

about_Debuggers

  • Artigo

Descrição breve

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 do 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 sendo executados no console ou no ISE (Ambiente de Script Integrado) do Windows PowerShell em computadores remotos.

Observação

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 para o PowerShell. Para obter mais informações, consulte Depuração com 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: Reativa 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ê atinge um ponto de interrupção, a execução é interrompida e o controle é transferido para o 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.

Observação

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 depois 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 percorridas.

  • Ctrl+Break: (Quebrar tudo no ISE) Interrompe 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. Interromper tudo funciona em scripts locais e remotos em execução interativa.

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

  • 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 percorridas.

  • l, List: Exibe a parte do script que está sendo executada. 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> as linhas do script, começando com o número da 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 Debug-Job cmdlet, o Exit comando desanexará o depurador e permitirá 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 o comando do depurador Help.

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 ou Debug-Job Debug-Runspace.

Usando esses comandos do 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é identificar um problema.

Observação

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

Exibindo os valores das variáveis de script

Enquanto estiver no depurador, você também poderá 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 as seguintes variáveis automáticas:

$_
$Args
$Input
$MyInvocation
$PSBoundParameters

Ao exibir o valor de qualquer uma dessas variáveis, você 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 seu 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

Ao atingir um ponto de interrupção, você entra no ambiente do depurador. O prompt de comando muda para que 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 pelos caracteres maiores que repetidos (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 $NestedPromptLevel variável automática. A variável automática, $PSDebugContext, é definida no escopo local. Você pode usar a $PSDebugContext presença da variável para determinar se está executando no depurador.

Por exemplo:

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

Você pode usar o $PSDebugContext valor da variável em sua 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 aliases definidos no escopo do script, use o parâmetro Scope dos Get-Alias cmdlets or 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 definiu durante a depuração.

Depuração na linha de comando

Ao definir um ponto de interrupção variável ou um ponto de interrupção de comando, você pode definir o ponto de interrupção somente 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 $name variável, o depurador interromperá qualquer $name variável em qualquer script, comando, função, cmdlet de script ou expressão executada 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 begin, processe seções 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 remota interativa do PowerShell 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á sendo executada
  • O prompt DBG que permite que você saiba que 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 para a 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, comando, 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

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 da 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(s) comando(s) Step para executar a primeira instrução no script e visualizar a próxima instrução. A próxima instrução usa a $MyInvocation variável automática para definir o valor da $scriptName variável como o caminho e o nome do arquivo de script.

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

Neste ponto, a $scriptName variável não está preenchida, mas você pode verificar o valor da variável exibindo seu valor. Nesse caso, o valor é $null.

DBG> $scriptname
DBG>

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

DBG> s
test.ps1:12  psversion

Neste ponto, a $scriptName variável é preenchida, mas você verifica o valor da variável exibindo seu valor. 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 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 Step comando. Mas, neste caso, use um comando StepOut (o). Ele conclui a execução da função (a menos que atinja um ponto de interrupção) e passa 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 do 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 Get-PsBreakpoint cmdlets e Remove-PsBreakpoint . (Se você acha que pode reutilizar o ponto de interrupção, use o Disable-PsBreakpoint cmdlet 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 função:

function delbr { gbp | rbp }

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

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 é Write, portanto, a execução é interrompida logo 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 $scriptName variável, que é $null.

DBG> $scriptName
DBG>

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

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

Use um (s) comando (s) Etapa (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 psversion função. Para ignorar a função, mas ainda executá-la, use um StepOver comando (v). Se você já estiver na função quando usar StepOvero , 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 StepOver comando executa a função e visualiza a próxima instrução no script, que imprime a linha final.

Use um Stop comando (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 Get-PsBreakpoint cmdlets e Remove-PsBreakpoint .

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

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

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 lhe dá 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 Continuar (c) para sair do script e um Remove-PsBreakpoint comando 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 $scriptName valor da variável quando a função é chamada. Como a break palavra-chave não é usada na ação, a execução não é interrompida. O acento grave (`) é 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 do comando será executado somente se a política de execução estiver definida como RemoteSigned, a política mais restritiva que ainda permite a execução de scripts.

PS C:\ps-test> Set-PSBreakpoint -script test.ps1 -command psversion `
-action { if ((Get-ExecutionPolicy) -eq "RemoteSigned") { break }}

A break palavra-chave na ação direciona o depurador para executar o ponto de interrupção. Você também pode usar a continue palavra-chave para direcionar o depurador para ser executado sem interrupção. 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 é definida como RemoteSigned, a execução é interrompida na chamada de função.

Neste ponto, talvez você queira verificar a pilha de chamadas. Use o Get-PsCallStack cmdlet ou o comando do 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 muitas 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 Set-PSDebug cmdlet oferece recursos muito básicos de depuração de script, incluindo depuração e rastreamento.

  • Use o Set-StrictMode cmdlet para detectar referências a variáveis não inicializadas, a referências a propriedades inexistentes de um objeto e 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 Write para esta tarefa, como Write-Host, Write-Debug, Write-Warning, e Write-Verbose.

Confira também