Sobre depuradores

Artigo
06/21/2023

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 de script. O depurador do PowerShell pode ajudá-lo a examinar e identificar erros e ineficiências em scripts, funções, comandos, configurações de DSC (Desired State Configuration) 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 Windows PowerShell ISE em computadores remotos. Você pode executar Enter-PSSession para iniciar uma sessão interativa remota do PowerShell na qual você pode definir pontos de interrupção e depurar arquivos de script e comandos no computador remoto. Enter-PSSession A funcionalidade foi atualizada para permitir que você se reconecte e insira uma sessão desconectada que esteja 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á atingiu um ponto de interrupção e for interrompida no ponto de interrupção, Enter-PSSession iniciará automaticamente o depurador de linha de comando depois que você se reconectar à sessão.

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

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 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. Em seguida, 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 é 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.

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, 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 percorridas.
Ctrl+Break: (Dividir Tudo no ISE) Divide em um script em execução dentro do console do PowerShell ou Windows PowerShell ISE. 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 que executam interativamente.
o, StepOut: sai da função atual; um nível acima 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 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á 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 linhas <n> 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 Debug-Job cmdlet , o Exit comando 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 Etapa (s), StepOver (v) ou Lista (l). Caso contrário, representa uma ação de envio.
?, h: exibe a Ajuda do comando do depurador.

Para sair do depurador, você pode usar Parar (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-JobDebug-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ê intervir 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 de 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 para as seguintes variáveis automáticas:

$_
$Args
$Input
$MyInvocation
$PSBoundParameters

Se você tentar exibir o valor de qualquer uma dessas variáveis, obterá o valor dessa variável para em um pipeline interno usado pelo depurador, não o valor da variável no script.

Para exibir o valor dessas variáveis para o script que está sendo depurado, no script, atribua o valor da variável automática a uma nova variável. Em seguida, você pode exibir o valor da nova variável.

Por exemplo,

$scriptArgs = $Args
$scriptArgs

No exemplo neste tópico, o valor da $MyInvocation variável é reatribuído da seguinte maneira:

$scriptname = $MyInvocation.MyCommand.Path

O ambiente do depurador

Ao chegar a um ponto de interrupção, você insere o ambiente do depurador. O prompt de comando é alterado para que ele comece com "[DBG]:".

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

Além disso, em alguns aplicativos host, como o console do PowerShell , (mas não em Windows PowerShell ISE [Ambiente de Script Integrado]), 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.

Por exemplo, o seguinte é o prompt de depuração padrão no console do PowerShell:

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

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

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

Por exemplo:

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

Você pode usar o valor da $PSDebugContext variável 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 Get-Alias cmdlets ou Get-Variable .

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

Get-Variable -scope 0

Você pode abreviar o comando como:

gv -s 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 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 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, eles 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 Beginseções , 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

A partir do PowerShell 5.0, você pode executar o depurador do PowerShell em uma sessão remota, no console ou Windows PowerShell ISE. Enter-PSSession A funcionalidade foi atualizada para permitir que você se reconecte e insira uma sessão desconectada em execução em um computador remoto e atualmente executando um script. Se o script em execução atingir um ponto de interrupção, a sessão do cliente iniciará automaticamente o depurador.

Veja a seguir um exemplo que mostra como isso funciona, com pontos de interrupção definidos em um script nas linhas 6, 11, 22 e 25. Observe que, no exemplo, quando o depurador é iniciado, há dois prompts de identificação: o nome do computador no qual a sessão está em execução e o prompt DBG que informa 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 sistema operacional e exibe uma mensagem apropriada ao 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:

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."

Para iniciar, 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

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 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 $MyInvocation variável automática para definir o valor da $scriptName variável para o caminho e o nome do arquivo de script.

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

Neste ponto, a $scriptName variável 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 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, 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 segue 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 comando.

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 da variável. O modo padrão é Write, 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.MyCommand.Path
# DBG>

Exiba o valor atual da $scriptName variável, 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 $scriptName variável.

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

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 ao 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 Get-PSBreakpoint cmdlets 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 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 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 valor da $scriptName variável 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 permitirá que você execute scripts. (O backtick (') é o 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 direciona o depurador para executar o ponto de interrupção. Você também pode usar a palavra-chave Continuar para direcionar o depurador a ser executado sem interrupção. Como a palavra-chave padrão é Continuar, você deve especificar Quebra 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 Get-PsCallStack comando de 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.

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

help <cmdlet-name> -full

Por exemplo, digite:

help Set-PSBreakpoint -full

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.

Windows PowerShell ISE inclui um depurador gráfico interativo. Para obter mais informações, inicie Windows PowerShell ISE e pressione F1.
O Set-PSDebug cmdlet oferece recursos de depuração de script muito básicos, incluindo etapas e rastreamento.
Use o Set-StrictMode cmdlet para detectar referências a variáveis não inicializadas, para referências 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 Write para essa tarefa, como Write-Host, Write-Debug, Write-Warninge Write-Verbose.