about_Debuggers

Breve descrição

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.

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, comando ou 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 parar o depurador, execute o script, o comando ou a função até que esteja concluído. Ou, digite stop ou t.

Comandos do depurador

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

• s, : Executa a próxima instrução e, StepIntoem 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: (Quebrar tudo no ISE) Quebra em 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. Break All funciona em scripts locais e remotos executados interativamente.

• o, StepOut: Sai da função atual; sobe um nível se aninhado. Se estiver no corpo principal, continua até ao fim ou ao 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 esteja 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 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> linhas do script, começando com o número de linha especificado por <m>.

• q, Stop, Exit: Para de executar o 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 foi Step (s), StepOver (v), ou List (l). Caso contrário, representa uma ação de envio.

• ?, h: Exibe o comando do depurador Ajuda.

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

Exibindo os valores das variáveis de script

Enquanto estiver no depurador, você também pode inserir comandos, exibir o valor de 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

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

Quando você atinge um ponto de interrupção, você entra no ambiente do depurador. O prompt de comando é alterado 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 detetar o prompt aninhado pelos caracteres maiores que a repetição (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 âmbito local. Você pode usar a presença da $PSDebugContext variável para determinar se está executando dentro do 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 é 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 você definiu durante a depuração.

Depuração na linha de comando

Quando você define 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 quebrará em qualquer $name variável em qualquer script, comando, função, cmdlet de script ou expressão que você executar até que você desabilite ou remova 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 begin, processe end seções, o depurador quebra 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 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 deteta a versão do PowerShell e exibe uma mensagem apropriada à versão. 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 muda 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(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 variável para o caminho e o nome do $scriptName 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. Neste 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 Step.

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 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 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 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 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 $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 para 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 $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 o $scriptName novo valor da variável.

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

Use o(s) comando(s) 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 psversion função. Para ignorar a função, mas ainda executá-la, use um StepOver comando (v). Se você já está na função quando você usa StepOver, não é 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 reverte 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. Até o momento, a função ainda não foi chamada. Isso lhe dá a oportunidade de usar o parâmetro Action de 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 Set-PSBreakpoint diagnóstico ou 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, não é possível 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 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 do comando será executado somente se a diretiva de execução estiver definida como RemoteSigned, a diretiva 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 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 executar sem quebrar. 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 diretiva de execução é definida como RemoteSigned, a execução para na chamada de função.

Neste ponto, convém verificar a pilha de chamadas. Use o Get-PsCallStack cmdlet ou o Get-PsCallStack comando do 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 de depuração de script muito básicos, incluindo revisão e rastreamento.

• Use o Set-StrictMode cmdlet para detetar 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-Warninge Write-Verbose.

Consulte também

• Desativar-PSBreakpoint
• Enable-PSBreakpoint
• Get-PSBreakpoint
• Remove-PSBreakpoint
• Set-PSBreakpoint
• Get-PSCallStack
• Gravação-depuração
• Escrever-Verbose