Windows Server 2025 / Tratar erros do PowerShell e registrar logs de execução

Um comando concluído não é necessariamente uma tarefa administrativa bem-sucedida. Os blocos try, catch e finally do PowerShell, o tratamento explícito de erros e logs por execução ajudam a identificar falhas e mostram quando apenas parte de uma tarefa foi concluída.

Torne as falhas visíveis

Este exercício lê um arquivo sem alterar as funções do servidor. Um script real de instalação ou gerenciamento de contas também deve registrar as alterações deixadas por uma falha intermediária. Entrar no catch não desfaz automaticamente ações anteriores.

Alguns erros do PowerShell permitem que a execução continue. Apenas colocar um comando dentro do try não torna todos os erros capturáveis; -ErrorAction Stop transforma os erros da operação em erros que interrompem o comando e podem ser capturados pelo catch. Revise tratamento de erros do PowerShell para a distinção.

Prepare um arquivo de entrada e o script completo

Crie primeiro a pasta C:\LabScripts se ela não existir e depois o arquivo C:\LabScripts\input.txt contendo uma linha. Salve o código completo abaixo como Read-LabFile.ps1 na mesma pasta usando UTF-8. O exemplo do Windows PowerShell 5.1 lê arquivos e escreve logs; ele não altera serviços do servidor ou rede.

param(
    [Parameter(Mandatory=$true)]
    [string]$InputPath
)
$logDirectory = 'C:\LabLogs'
New-Item -ItemType Directory -Path $logDirectory -Force -ErrorAction Stop | Out-Null
$runLabel = (Get-Date -Format 'yyyyMMdd-HHmmss') + '-' + ([guid]::NewGuid().ToString('N').Substring(0,6))
$logPath = Join-Path $logDirectory ($runLabel + '.json')
$result = [ordered]@{
    StartedAt = (Get-Date).ToString('o')
    ComputerName = $env:COMPUTERNAME
    InputPath = $InputPath
    Success = $false
    LineCount = $null
    ErrorId = $null
    ErrorMessage = $null
}
$exitStatus = 0
try {
    $lines = @(Get-Content -LiteralPath $InputPath -ErrorAction Stop)
    $result.LineCount = $lines.Count
    $result.Success = $true
}
catch {
    $result.ErrorId = $_.FullyQualifiedErrorId
    $result.ErrorMessage = $_.Exception.Message
    $exitStatus = 1
    Write-Warning $result.ErrorMessage
}
finally {
    $result.FinishedAt = (Get-Date).ToString('o')
    $result | ConvertTo-Json | Set-Content -LiteralPath $logPath -Encoding UTF8 -ErrorAction Stop
}
Write-Output $logPath
exit $exitStatus

Compare sucesso e falha sob as mesmas condições

A primeira execução lê o arquivo existente. A segunda usa missing-input.txt, que deve realmente estar ausente. Você não precisa excluir o arquivo de entrada ou modificar um arquivo do sistema para criar uma falha:

powershell.exe -NoProfile -File 'C:\LabScripts\Read-LabFile.ps1' -InputPath 'C:\LabScripts\input.txt'
$LASTEXITCODE
powershell.exe -NoProfile -File 'C:\LabScripts\Read-LabFile.ps1' -InputPath 'C:\LabScripts\missing-input.txt'
$LASTEXITCODE

Inspecione imediatamente cada código de saída. O caso de sucesso esperado retorna 0 com Success=true. O arquivo ausente retorna 1 com Success=false e detalhes do erro. Cada execução cria um registro distinto no formato JSON (JavaScript Object Notation, um formato de dados estruturados); abra os caminhos relatados e compare InputPath e ErrorId.

Se a política de script bloquear a execução, siga a política da organização e os requisitos de assinatura, em vez de enfraquecer configurações globais para este exemplo.

Entenda cada seção de tratamento de erros

A referência de try, catch e finally da Microsoft explica o tratamento de erros que interrompem a execução do comando. Um bloco finally não pode garantir um disco de log gravável. Uma falha na criação da pasta antes do bloco try também pode encerrar o script antes de finally ser executado. Armazenamento cheio ou acesso negado ainda podem impedir a gravação, então as escritas de log também usam -ErrorAction Stop. Não reporte sucesso apenas porque não existe log.

Programas externos retornam seus próprios códigos de saída. No Windows PowerShell 5.1, não presuma que uma saída diferente de zero automaticamente entra no catch. Inspecione $LASTEXITCODE imediatamente e lance uma exceção quando apropriado; outro comando externo pode substituir esse valor.

Adicione critérios de reexecução controlada aos scripts operacionais

• Registre o servidor, o alvo, e os horários de início e término.
• Consulte o estado existente para evitar a criação duplicada ou a sobrescrição não intencional.
• Acompanhe etapas bem-sucedidas e com falha separadamente.
• Mantenha senhas, tokens e conteúdos desnecessários de arquivos de usuário fora dos logs.
• Se estiver implementando reversão de alterações (rollback), registre seu escopo suportado e qualquer falha de recuperação.

Restaure o caminho de entrada válido e execute novamente para confirmar um novo resultado bem-sucedido. Preserve as evidências necessárias antes de remover apenas os arquivos temporários deste laboratório. Adicionar SilentlyContinue em todos os lugares oculta falhas em vez de tornar a administração confiável.