Debugging no PowerShell

Bem-vindo à aula 68 do nosso curso de PowerShell. Hoje vamos explorar um dos aspectos mais importantes do desenvolvimento: a depuração (debugging). Depurar é o processo de identificar e corrigir erros ou comportamentos inesperados em seus scripts. O PowerShell oferece várias ferramentas para isso, desde cmdlets específicos até integração com editores modernos como o Visual Studio Code.

Nesta aula, você aprenderá a usar breakpoints para pausar a execução em pontos estratégicos, a depurar passo a passo (step-through), e a utilizar mensagens de depuração com Write-Debug para obter informações detalhadas sobre o fluxo do script. Vamos mergulhar nas práticas que tornarão seu processo de depuração mais eficiente e menos frustrante.

Set-PSBreakpoint

O cmdlet Set-PSBreakpoint é uma das ferramentas mais poderosas para depuração no PowerShell. Ele permite definir pontos de interrupção em linhas específicas, variáveis ou comandos, fazendo com que a execução do script seja pausada quando o ponto é alcançado. Isso lhe dá a oportunidade de inspecionar o estado atual das variáveis, o escopo e o fluxo de execução antes de continuar.

Existem três tipos principais de breakpoints que você pode criar com Set-PSBreakpoint:

• Line breakpoint: pausa a execução quando uma linha específica do script é atingida.
• Variable breakpoint: pausa a execução quando o valor de uma variável específica é alterado.
• Command breakpoint: pausa a execução quando um comando ou função específica é invocado.

Para criar um breakpoint de linha, você especifica o caminho do script e o número da linha. Por exemplo:

Set-PSBreakpoint -Script .\meu_script.ps1 -Line 10

Isso fará com que o script pare na linha 10. Quando a execução pausa, você entra no modo de depuração interativo, onde pode usar comandos como step, continue e list para navegar pelo código.

Para breakpoints de variável, você pode usar o parâmetro -Variable:

Set-PSBreakpoint -Script .\meu_script.ps1 -Variable contador

Isso pausará sempre que a variável contador for alterada. Já os breakpoints de comando são criados com -Command:

Set-PSBreakpoint -Script .\meu_script.ps1 -Command Write-Host

Para listar todos os breakpoints ativos, use Get-PSBreakpoint. Para remover um breakpoint, utilize Remove-PSBreakpoint passando o objeto do breakpoint ou o ID. Por exemplo:

Get-PSBreakpoint | Remove-PSBreakpoint

Uma dica importante: os breakpoints definidos por linha são os mais comuns e funcionam bem quando você sabe onde o problema está. Os breakpoints de variável são úteis para rastrear mudanças inesperadas, enquanto os de comando ajudam a identificar quando uma função é chamada com parâmetros inesperados.

Breakpoints no VSCode

O Visual Studio Code (VSCode) é um dos editores mais populares para desenvolvimento com PowerShell, graças à extensão oficial PowerShell. Essa extensão oferece uma experiência integrada de depuração, permitindo que você defina breakpoints diretamente no editor, sem precisar usar comandos no console.

Para usar os breakpoints no VSCode, você precisa ter o arquivo launch.json configurado corretamente. A extensão PowerShell fornece uma configuração padrão que você pode gerar automaticamente. Basta abrir a aba de Executar e Depurar (Ctrl+Shift+D), clicar em "criar um arquivo launch.json" e escolher a opção "PowerShell: Launch Current File".

Uma vez configurado, você pode definir um breakpoint clicando na área à esquerda do número da linha (a margem) ou pressionando F9. Um ponto vermelho aparecerá indicando o breakpoint. Ao iniciar a depuração (F5), a execução pausará nesse ponto, e você poderá inspecionar variáveis no painel de variáveis, observar a pilha de chamadas e usar os controles de depuração.

O VSCode também permite breakpoints condicionais. Clique com o botão direito no breakpoint e selecione "Editar Breakpoint". Você pode adicionar uma condição, por exemplo, $contador -gt 5, para que a pausa ocorra somente quando a condição for verdadeira. Isso é extremamente útil em loops longos.

Outra funcionalidade interessante é o suporte a logpoints, que permitem registrar mensagens no console sem pausar a execução. Isso é útil quando você quer rastrear valores sem interromper o fluxo.

# Exemplo de script para depurar no VSCode
function Get-Quadratic {
    param($a, $b, $c)
    $delta = $b * $b - 4 * $a * $c
    if ($delta -lt 0) {
        Write-Error "Delta negativo"
        return
    }
    $x1 = (-$b + [Math]::Sqrt($delta)) / (2 * $a)
    $x2 = (-$b - [Math]::Sqrt($delta)) / (2 * $a)
    return [PSCustomObject]@{ X1 = $x1; X2 = $x2 }
}

Get-Quadratic -a 1 -b -3 -c 2

Coloque um breakpoint na linha do cálculo de $delta e execute a depuração. Você verá que o script pausa e pode inspecionar os valores de $a, $b e $c.

Write-Debug

O cmdlet Write-Debug é uma maneira de adicionar mensagens de depuração ao seu código que só são exibidas quando você está depurando. Por padrão, essas mensagens são suprimidas, mas você pode habilitá-las com o parâmetro -Debug ao chamar o script ou função, ou definindo a variável $DebugPreference como 'Continue'.

Isso é útil para colocar pontos de observação temporários sem poluir a saída normal do script. Por exemplo:

function Test-Debug {
    [CmdletBinding()]
    param()
    Write-Debug "Iniciando função Test-Debug"
    $valor = 42
    Write-Debug "Valor calculado: $valor"
    return $valor
}

# Execução normal não mostra mensagens de debug
Test-Debug

# Execução com -Debug mostra as mensagens
Test-Debug -Debug

Quando você usa -Debug, o PowerShell pergunta se deseja continuar após cada mensagem. Para evitar a pergunta, você pode definir $DebugPreference = 'Continue' antes de executar. Isso fará com que as mensagens sejam exibidas sem interrupção.

Diferente de Write-Host, que sempre exibe a mensagem, Write-Debug é projetado especificamente para depuração. Em produção, você pode deixar as mensagens no código sem impacto, pois elas não aparecerão a menos que a depuração seja ativada.

É uma boa prática usar Write-Debug para registrar informações detalhadas sobre o estado interno, como valores de variáveis e decisões de fluxo, facilitando a identificação de problemas quando eles ocorrerem.

Step-through

Step-through (ou execução passo a passo) é uma técnica de depuração onde você executa seu script uma linha de cada vez, observando o efeito de cada instrução. No PowerShell, isso é feito no modo de depuração interativo, que você acessa quando um breakpoint é atingido, ou usando o comando Set-PSDebug -Step.

Quando você inicia o modo de depuração, os comandos disponíveis incluem:

• s ou Step-Into: executa a próxima linha e, se for uma chamada de função, entra na função.
• v ou Step-Over: executa a próxima linha sem entrar em funções (trata a chamada como uma única etapa).
• o ou Step-Out: executa até o final da função atual.
• c ou Continue: continua a execução até o próximo breakpoint.
• q ou Quit: sai do depurador.

Para usar o step-through a partir de um breakpoint, você pode simplesmente digitar s para entrar na próxima instrução ou v para passar por cima. Isso é particularmente útil para loops e chamadas de função, onde você deseja inspecionar cada iteração.

Alternativamente, você pode usar Set-PSDebug -Step para iniciar o modo passo a passo antes de executar o script. No entanto, isso pode ser cansativo para scripts longos, pois pausa a cada linha. É mais comum usar breakpoints para ir direto ao ponto de interesse e depois usar step-through a partir dali.

No VSCode, os controles de step-through estão na barra de ferramentas de depuração: F10 (Step Over), F11 (Step Into), Shift+F11 (Step Out). Você também pode usar a paleta de comandos.

Vamos ver um exemplo prático. Crie um script que calcula o fatorial de um número:

function Get-Fatorial {
    param($n)
    if ($n -le 1) { return 1 }
    return $n * (Get-Fatorial -n ($n - 1))
}

Get-Fatorial -n 5

Coloque um breakpoint na linha return $n * (Get-Fatorial -n ($n - 1)) e execute a depuração. Quando pausar, use s para entrar na chamada recursiva. Observe como o valor de $n muda a cada chamada. Isso ajuda a entender a recursão e a verificar se a lógica está correta.

Boas Práticas e Observações Finais

Depurar é uma habilidade que melhora com a prática. Algumas dicas para tornar a depuração mais eficiente:

• Use breakpoints em vez de Write-Host para inspecionar valores, pois eles não poluem o código final.
• Combine Write-Debug com breakpoints para ter um log detalhado quando necessário.
• Em loops grandes, use breakpoints condicionais para parar apenas quando uma condição específica ocorrer.
• Teste scripts em um ambiente de desenvolvimento antes de executá-los em produção.
• Familiarize-se com os comandos do depurador (s, v, o, c) para navegar rapidamente.

Lembre-se de remover breakpoints e mensagens de depuração temporárias antes de compartilhar ou implantar seu script. Manter um código limpo é essencial para a manutenção.

Referências

• Set-PSBreakpoint - Microsoft Learn
• Write-Debug - Microsoft Learn
• Using breakpoints - Microsoft Learn
• Debugging in Visual Studio Code
• Using Visual Studio Code for PowerShell development
• Set-PSDebug - Microsoft Learn

Exercícios

1. Crie um script que calcule a soma dos números de 1 a 10 usando um loop for. Defina um breakpoint na linha do incremento da variável de soma e execute a depuração. Inspecione os valores das variáveis a cada iteração.

Ver resposta

✓ Resposta:
$soma = 0
for ($i = 1; $i -le 10; $i++) {
    $soma += $i
}
Write-Host "Soma: $soma"
Defina o breakpoint na linha $soma += $i. Ao executar, use v para step over e observe os valores de $i e $soma no depurador.
2. Explique a diferença entre breakpoints de linha, variável e comando. Dê um exemplo de quando cada um seria útil.

Ver resposta

✓ Resposta: Breakpoint de linha pausa em uma linha específica, útil quando você sabe onde o erro ocorre. Breakpoint de variável pausa quando o valor de uma variável muda, útil para rastrear alterações inesperadas. Breakpoint de comando pausa quando um comando específico é executado, útil para ver quando uma função é chamada. Exemplo: linha - pausar na linha 10; variável - pausar quando $total mudar; comando - pausar quando Write-Host for chamado.
3. Escreva uma função que calcule o fatorial de um número usando recursão. Adicione Write-Debug para exibir o valor de $n a cada chamada. Execute com -Debug e observe as mensagens.

Ver resposta

✓ Resposta:
function Get-Fatorial {
    [CmdletBinding()]
    param($n)
    Write-Debug "Chamando com n = $n"
    if ($n -le 1) { return 1 }
    return $n * (Get-Fatorial -n ($n - 1))
}
Get-Fatorial -n 5 -Debug
Ao executar, você verá as mensagens de depuração para cada chamada recursiva.
4. No VSCode, como você define um breakpoint condicional? Descreva o processo.

Ver resposta

✓ Resposta: Clique com o botão direito no breakpoint existente (ou crie um) e selecione "Editar Breakpoint". Na caixa de entrada, digite a condição, por exemplo, $i -eq 5. Pressione Enter. O breakpoint agora só será acionado quando a condição for verdadeira.
5. Qual é a função do comando Set-PSDebug -Step? Como ele difere de usar breakpoints?

Ver resposta

✓ Resposta: Set-PSDebug -Step ativa o modo passo a passo, onde o PowerShell pausa após cada linha de script, pedindo confirmação para continuar. Ele difere dos breakpoints porque não requer pontos específicos; você percorre todo o script desde o início. Isso pode ser útil para scripts curtos, mas é menos eficiente em scripts longos.