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