PowerShell Write to File: "Out-File" e Técnicas de Saída de Arquivo

Introdução à Geração de Saída no PowerShell

Qualquer pessoa familiarizada com o PowerShell sabe que a saída dos comandos do PowerShell é exibida no terminal por padrão. No entanto, pode haver situações em que você queira redirecionar ou salvar a saída em um arquivo.

• Os comandos podem retornar uma grande quantidade de dados que é difícil de manusear em tempo real. Você pode redirecionar ou salvar esses dados para processá-los ou revisá-los quando lhe for conveniente.
• Para usar os resultados de um comando em outro processo ou script, você pode usar o comando de saída do PowerShell para arquivo para salvar a saída em um arquivo ou variável para reutilização fácil.
• Tarefas agendadas ou outras tarefas automatizadas geralmente costumam ser executadas em segundo plano. Você pode não conseguir ver a saída em tempo real, então salvá-la permite que você a revise mais tarde.
• Às vezes, a saída pode conter mais informações do que você precisa. Portanto, você pode redirecionar ou salvar para filtrar e formatá-la.
• Quando você executa comandos em sistemas remotos, pode não ter acesso ao console para visualizar a saída em tempo real. Salvar ou redirecionar fornece um registro do que aconteceu no sistema remoto.
• As organizações geram relatórios com base em estados de sistemas, configurações ou métricas de desempenho. Utilizando PowerShell, elas podem consultar dados do sistema, gerar relatórios e exportá-los para um arquivo para análise futura.
• O PowerShell pode ser usado para coletar informações de inventário de hardware e software para gestão de ativos e conformidade. Esses dados podem então ser exportados para um arquivo para maior visibilidade e gerenciamento simplificado.
• Ao automatizar tarefas, é essencial rastrear as ações realizadas e os resultados. Redirecionar a saída para um arquivo ajuda a criar registros para auditoria.
• Se um script falhar, você precisa saber a causa raiz. Ao salvar a saída, você pode revisá-la mais tarde para tratamento de erros, depuração e resolução de problemas.

Resumidamente, redirecionar ou salvar a saída do PowerShell aumenta a produtividade, ajuda na depuração, fornece registros úteis e facilita a automação, especialmente em fluxos de trabalho complexos ou ao trabalhar com grandes conjuntos de dados.

Métodos Principais para Exportar Resultados do PowerShell para Arquivos

O Cmdlet Out-File

O método do PowerShell para escrever em arquivo de texto geralmente utiliza o cmdlet Out-File para enviar os resultados dos comandos (saída) diretamente para um arquivo. Na sua forma mais simples, o Out-File exige a especificação de um caminho e nome de arquivo para escrever a saída.

Por padrão, o cmdlet sobrescreve um arquivo existente se um com o mesmo nome existir no caminho especificado, ou cria um novo se ele não existir.

Sintaxe Out-File

Aqui está a sintaxe básica para o cmdlet Out-File:

      Out-File
[-FilePath] <cadena>
[[-Encoding] <Encoding>]
[-Append]
[-Force]
[-NoClobber]
[-Width <int>]
[-NoNewline]
[-InputObject <psobject>]
[-WhatIf]
[-Confirmar]
[<CommonParameters>]
      

Parâmetros

O cmdlet Out-File do PowerShell aceita os seguintes parâmetros:

Casos de Uso

Para escrever a saída diretamente em um arquivo em vez de exibi-la na tela, você pode usar a abordagem do PowerShell de escrever a saída para o arquivo anexando o cmdlet Out-File a um comando ou variável do PowerShell. Essa técnica também funciona para escrever uma string de texto em um arquivo, anexando Out-File diretamente à string.

Anexe Out-File a um cmdlet do PowerShell

Para recuperar uma lista de processos em execução e usar o método de salvar saída no arquivo do PowerShell, salve a saída em um arquivo de texto chamado “Processes” na pasta C:\Temp com o seguinte exemplo:

Get-Process | Out-File -FilePath C:\Temp\processes.txt

Aqui, o cmdlet Get-Process irá listar todos os processos em execução. Com a funcionalidade de redirecionamento de saída do PowerShell para arquivo, você pode pegar a saída de um comando e imediatamente salvá-la em um arquivo de texto para análise posterior.

Anexar Out-File a uma string de texto

Para escrever uma string usando o método do PowerShell de escrever string em arquivo, como adicionar “Hello, World!” a um arquivo de texto chamado “Test” no local C:\Temp, use o seguinte cmdlet:

"Olá, Mundo!" | Out-File -FilePath C:\Temp\Test.txt

Se o arquivo não existir, ele será criado. Se já existir, o conteúdo será sobrescrito por padrão.

Anexar Out-File a uma Variável

Você também pode usar o cmdlet Out-File com uma variável. Por exemplo:

$variable | Out-File -FilePath "C:\path\to\file.txt"

Aqui $variable é a variável que contém os dados (por exemplo, uma saída do PowerShell para arquivo de texto ou saída de comando) que você deseja enviar para um arquivo.

Operadores de Redirecionamento (> e >>)

Os operadores de redirecionamento (> e >>) no PowerShell são uma alternativa simples e rápida ao cmdlet Out-File, permitindo que você redirecione a saída para um arquivo.

• O operador > é equivalente ao cmdlet Out-File sem parâmetros adicionais. Ele sobrescreve o arquivo se ele existir ou cria um novo se não existir.
• O operador >> é equivalente a Out-File -Append. Ele anexa a saída ao arquivo se ele existir ou cria um novo se não existir.

Esses operadores também têm outros usos, como redirecionar fluxos de saída de erro ou verbosos, o que está além do escopo deste artigo.

Sintaxe básica

A sintaxe básica para usar os operadores é a seguinte:

<Command> > <Path> # Sobrescreve

<Command> >> <Path> # Acrescenta

Note que os operadores de redirecionamento não utilizam nenhum parâmetro.

Exemplo 1 – Usando o operador >

Este cmdlet grava a saída do Get-Process no arquivo Processes.txt, substituindo qualquer conteúdo existente caso um arquivo com este nome já exista no destino.

Get-Process > C:\Temp\Processes.txt

Exemplo 2 – Usando o operador >>

Este cmdlet acrescenta a data e hora atuais ao final do arquivo log.txt sem sobrescrever o conteúdo existente.

Get-Date >> C:\Temp\log.txt

Se um arquivo chamado log.txt não existir no caminho especificado, ele cria o arquivo e escreve a data e hora atuais nele.

Cmdlet Out-File versus Operadores de Redirecionamento (> e >>)

Tanto o cmdlet Out-File quanto os operadores de redirecionamento podem escrever e anexar a saída do PowerShell a um arquivo. As principais diferenças entre os dois são discutidas abaixo.

Quando usar cada um

Em comparação, o cmdlet Out-File é mais versátil e ideal para scripts complexos, com opções para codificação, largura e controle de substituição. No entanto, os operadores de redirecionamento são rápidos e convenientes para trabalhos de saída rápidos que não exigem personalização. A seguir, um breve guia sobre quando você deve usar cada um.

Quando usar o cmdlet Out-File

• Para codificações específicas (por exemplo, ASCII, UTF8, Unicode)
• Para evitar sobrescrever arquivos (usando -NoClobber)
• Para controle da largura da linha de saída (usando -Width)
• No modo de acréscimo enquanto mantém outras opções de controle de saída

Quando usar > e >>

• Quando você deseja um redirecionamento rápido para a saída sem formatação ou codificação adicionais
• Quando se deseja sobrescrever (>) ou acrescentar (>>) ao arquivo existente

Técnicas Avançadas de Saída de Arquivos

Gerenciar Sobrescritas

Por padrão, o cmdlet Out-File sobrescreve um arquivo existente se um com o mesmo nome existir no caminho especificado, ou cria um novo arquivo se não existir.

Para evitar sobrescrever um arquivo existente, você pode usar o método de anexar ao escrever em arquivo do PowerShell de duas maneiras:

• Adicione (anexe) a saída ao arquivo existente
• Evite a substituição, de modo que o arquivo existente não seja sobrescrito e o resultado não seja salvo no arquivo

Anexar Saída

Utilize o parâmetro -Append com o cmdlet Out-File para adicionar a nova saída ao final do arquivo especificado sem sobrescrever seu conteúdo existente. Isso é particularmente útil quando, por exemplo, você deseja registrar eventos incrementalmente sem perder dados anteriores.

Este comando anexa as cinco entradas mais recentes do log do Sistema ao arquivo event_log.txt.

Get-EventLog -LogName System -Newest 5 | Out-File -FilePath C:\Temp\event_log.txt -Append

Você também pode usar o operador de redirecionamento >> para acrescentar saídas a um arquivo existente. No exemplo a seguir, o status e os detalhes dos serviços na sua máquina local são acrescentados ao conteúdo no arquivo log.txt.

Get-Service >> C:\Temp\log.txt

Evitar Sobrescrita

Utilize o parâmetro -NoClobber com o cmdlet Out-File para evitar sobrescritas. Assim, se um arquivo com o mesmo nome já existir no local especificado, o PowerShell não o sobrescreverá e lançará um erro. Isso ajuda a proteger arquivos importantes.

O seguinte comando tentará criar um arquivo chamado log.txt na pasta Temp. Mas se um arquivo com esse nome já existir, um erro será exibido e a saída não será salva no arquivo.

Get-Service | Out-File -FilePath C:\Temp\log.txt -NoClobber

Forçar Sobrescrita

Às vezes, você não consegue sobrescrever o conteúdo de um arquivo existente com a saída de um cmdlet do PowerShell, pois o arquivo é somente leitura. Em uma situação como essa, use o parâmetro -Force com o cmdlet Out-File para sobrescrever arquivos somente leitura.

Este cmdlet grava as informações dos serviços no arquivo Services.txt, garantindo que, se o Services.txt já existir, ele será sobrescrito, mesmo que seja somente leitura.

Get-Service | Out-File -FilePath C:\Temp\Services.txt -Force

Formatação e Codificação de Saída

O cmdlet Out-File do PowerShell oferece opções para personalizar a formatação e codificação da saída.

Formatar Saída

O cmdlet Out-File pode não exibir a saída conforme esperado, especialmente quando a saída possui várias colunas. Para uma saída formatada e legível, você pode ajustar a largura ou usar o cmdlet Format-Table.

Exemplo 1 – Defina a Largura

Use o parâmetro -Width com Out-File para especificar a largura da linha para o arquivo de saída (80 caracteres é o padrão).

Este cmdlet grava as informações dos serviços no arquivo Services.txt, definindo a largura da linha para 200 caracteres. Isso permite uma saída mais ampla sem quebra de linha.

Get-Service | Out-File -FilePath C:\Temp\Services.txt -Width 200

Exemplo 2 – Formatar com Format-Table

Utilize o cmdlet Format-Table para estruturar os dados antes de enviá-los ao cmdlet Out-File.

Este cmdlet utiliza Format-Table -AutoSize para ajustar automaticamente a largura das colunas para facilitar a leitura.

Get-Service | Format-Table -AutoSize | Out-File -FilePath C:\Temp\Services.txt

Definir Codificação

Codificar a saída no PowerShell ao usar o cmdlet Out-File garante que os dados sejam corretamente interpretados, exibidos e compatíveis em diferentes sistemas e aplicações.

O parâmetro -Encoding ajuda a especificar como o texto de saída é codificado no arquivo. Os tipos de codificação comuns incluem:

• UTF8 – Comum para aplicações web, suporta todos os caracteres.
• ASCII – Limitado a caracteres básicos do inglês, compacto, mas restritivo.
• Unicode (UTF-16) – Bom para compatibilidade com Windows, pode lidar com uma ampla gama de caracteres especiais, símbolos e texto internacional, mas usa mais espaço.
• Padrão – Utiliza a codificação padrão do sistema, que pode variar e ser imprevisível entre plataformas.

Exemplo 1 — Use a codificação UTF-8

É uma boa ideia usar a codificação UTF-8 se o arquivo de saída contiver caracteres especiais ou se o arquivo for utilizado em ambientes onde UTF-8 é a codificação padrão.

Este cmdlet recupera uma lista de serviços no sistema e exporta as informações para o arquivo Services.txt, definindo a codificação do arquivo como UTF-8.

Get-Service | Out-File -FilePath C:\Temp\Services.txt -Encoding UTF8

Exemplo 2 — Use a Codificação ASCII

A codificação ASCII é comumente usada para arquivos de texto mais simples.

Este cmdlet recupera uma lista de serviços no sistema e encaminha as saídas para o arquivo Services.txt. O parâmetro -Encoding é usado para converter a saída para o formato ASCII.

Get-Service | Out-File -FilePath C:\Temp\Services.txt -Encoding ASCII

Tratando Fluxos de Saída Específicos

O cmdlet Out-File escreve o resultado bem-sucedido do seu comando ou script em um arquivo. Mas ele não escreve erros, avisos ou tipos específicos de mensagens em arquivos. Isso pode ser alcançado com o operador de redirecionamento, que permite especificar qual fluxo você deseja enviar para um arquivo.

Exemplo 1 — Enviar mensagens de erro para arquivo

Este comando tenta listar (ls) um arquivo chamado Readme. Ele procura o arquivo no diretório atual se você não especificar um caminho. Se o arquivo não existir, ele gera uma mensagem de erro. O operador 2> redireciona esse erro para um arquivo chamado error.log. Como resultado, o erro não é exibido na tela, mas salvo em error.log na pasta Temp.

ls Readme 2> C:\Temp\error.log

Exemplo 2 — Enviar Avisos para arquivo

No PowerShell, o fluxo de avisos é o número 3. Você pode usar 3> para redirecionar avisos para um arquivo: É como se segue:

# Comando que gera um aviso

<Your-Command> 3> C:\Temp\warning_log.txt

Métodos Alternativos para Saída

Cmdlets Set-Content e Add-Content

Os cmdlets Set-Content e Add-Content são outra forma de escrever saída para arquivo.

• Set-Content sobrescreve o conteúdo existente no arquivo com o novo conteúdo fornecido. Se o arquivo não existir, ele é criado.
• Add-Content anexa novo conteúdo ao final do conteúdo existente do arquivo. Se o arquivo não existir, ele será criado, mas não substituirá o conteúdo existente.

O cmdlet Set-Content

Use o cmdlet Set-Content para escrever ou substituir o conteúdo de um arquivo por um novo conteúdo.

Este cmdlet sobrescreve o conteúdo existente no arquivo Test.txt. O parâmetro -Value especifica o conteúdo ou texto que substituirá o conteúdo existente.

Set-Content -Path C:\Temp\Test.txt -Value "Adicione conteúdo aqui"

O cmdlet Add-Content

Utilize o cmdlet Add-Content para adicionar conteúdo a um arquivo, o que significa que você pode anexar novos dados a um arquivo existente sem sobrescrevê-lo. Add-Content também pode anexar conteúdo a vários arquivos de uma só vez.

Assim como o cmdlet Out-File e o operador de redirecionamento, o cmdlet Add-Content cria um novo arquivo se um arquivo com o mesmo nome não existir.

Exemplo 1 — Anexar texto a um arquivo

Este cmdlet adiciona novo texto ao arquivo Test.txt. O parâmetro -Value especifica o conteúdo ou texto que você deseja anexar ao arquivo.

Add-Content -Path C:\Temp\Test.txt -Value "Nova linha para adicionar"

Se o arquivo for somente leitura, você deve usar o parâmetro -Force para permitir que o conteúdo seja adicionado.

Exemplo 2 — Adicionar texto a vários arquivos

Para adicionar o mesmo conteúdo a vários arquivos, você tem várias opções.

• Use curingas no caminho para especificar os arquivos que deseja atualizar
• Exclua os nomes de arquivos que você não deseja atualizar

Este cmdlet adiciona a data atual a todos os arquivos .txt na pasta Temp, exceto no arquivo com test no nome do arquivo:

Add-Content -Path C:\Temp\files\*.txt -Value (Get-Date) -Exclude "test*"

Exemplo 3 — Adicionar múltiplas linhas de texto

Este comando adiciona várias linhas de texto ao arquivo Test.txt.

      $lines = @(
"Line 1: Details",
"Line 2: Specific Details"
)
Add-Content -Path C:\Temp\Test.txt -Value $lines
      

.Net Classes

Você pode usar classes .NET para gerar saída para um arquivo, especialmente em cenários avançados que envolvem o manuseio de grandes volumes de dados. Estas classes são:

• BinaryWriter – Escreve tipos de dados primitivos em forma binária para um fluxo.
• StreamWriter – Usado para escrever caracteres em um fluxo em uma codificação específica. Frequentemente utilizado para criar ou modificar arquivos de texto.
• StringWriter – escreve informações em uma string. Com essa classe, o PowerShell armazena as informações da string em um objeto StringBuilder.

Usar a classe StreamWriter em C# para enviar saída para um arquivo é simples. O exemplo a seguir mostra como você pode utilizá-la.

      # Get the directories in C:\
$Dirs = Get-ChildItem -Path C:\ -Directory
# Open a stream writer
$File = 'C:\Temp\Dirs.txt'
$Stream = [System.IO.StreamWriter]::new($File)
# Write the folder names for these folders to the file
foreach($Dir in $Dirs) {
$Stream.WriteLine($Dir.FullName)
}
# Close the stream
$Stream.Close()
      

Este script executa os seguintes passos para listar diretórios no disco C:\ e salvar seus caminhos em um arquivo de texto:

Passo 1:

$Dirs = Get-ChildItem -Path C:\ -Directory

Esta linha utiliza Get-ChildItem com o parâmetro -Directory para obter apenas os diretórios (não arquivos) na unidade C:\. O resultado é armazenado na variável $Dirs como uma lista de objetos de diretório.

Passo 2:

$File = 'C:\Temp\Dirs.txt'

$Stream = [System.IO.StreamWriter]::new($File)

Estas linhas configuram um caminho de arquivo (C:\Temp\Dirs.txt) onde a lista de diretórios será salva e, em seguida, inicializam um objeto StreamWriter para escrever nesse arquivo. Este objeto é atribuído a $Stream.

Passo 3:

foreach($Dir in $Dirs) {

$Stream.WriteLine($Dir.FullName)

}

Este loop percorre cada objeto de diretório em $Dirs. Para cada diretório, ele escreve o caminho completo ($Dir.FullName) no arquivo usando $Stream.WriteLine.

Passo 4:

$Stream.Close()

Após escrever todos os caminhos de diretório, o script fecha o StreamWriter.

Melhores práticas para saída de arquivo no PowerShell

Defina a largura de linha correta para evitar a truncagem

Você deve definir a largura de linha correta com o parâmetro -Width no PowerShell para evitar a truncagem de linhas longas e garantir que as saídas de arquivos sejam formatadas conforme o esperado.

O parâmetro -Width no cmdlet Out-File controla o número máximo de caracteres por linha na saída. Por padrão, está definido para 80 caracteres, o que pode truncar linhas mais longas. Você pode, por exemplo, aumentar a largura para 200 caracteres, conforme mostrado abaixo:

Get-Process | Out-File -FilePath "output.txt" -Width 200

Considere o seguinte:

• Para evitar espaços em branco desnecessários ou truncamento, defina um -Width para corresponder à linha mais longa. Para a maioria das saídas, uma largura de 120–200 caracteres deve funcionar bem.
• Para dados com muitas colunas (como um arquivo CSV), defina uma largura maior para acomodar a linha inteira.
• Em um pipeline, use Out-String -Width para controlar a largura da linha, garantindo que a linha inteira caiba dentro da largura especificada antes de encaminhar para Out-File.

Defina a codificação correta

A codificação padrão que o PowerShell utiliza varia, dependendo do cmdlet e da versão do PowerShell que você está usando. A tabela a seguir mostra a codificação padrão utilizada:

A codificação UTF-8 é recomendada para compatibilidade entre sistemas. Para sistemas legados, no entanto, você pode querer especificar -Encoding ASCII ou -Encoding Unicode.

Use $PSDefaultParameterValues para definir padrões em scripts

$PSDefaultParameterValues no PowerShell permite que você defina valores padrão para parâmetros em scripts e sessões, oferecendo uma maneira de garantir consistência sem especificar opções repetidamente.

Aqui está como você pode definir um padrão global para o Out-File usar codificação UTF8 e largura mais ampla.

$PSDefaultParameterValues["Out-File:Encoding"] = "UTF8"

$PSDefaultParameterValues["Out-File:Width"] = 200

Combine Out-File com Format-Table e Format-List para uma saída mais estruturada

Combinar o cmdlet Out-File com Format-Table ou Format-List é uma ótima maneira de produzir arquivos de texto de saída bem estruturados e legíveis.

Format-Table

Format-Table é melhor para dados com uma estrutura clara de linhas e colunas. Ele cria um formato organizado e fácil de ler, semelhante a uma tabela. No entanto, para usá-lo com o cmdlet Out-File, considere o seguinte:

• Utilize o parâmetro -Property para especificar apenas as colunas que precisa. Isso evitará desordem no arquivo de saída.
• Use o parâmetro -AutoSize para otimizar a largura da coluna de modo a ajustar-se ao conteúdo. Isso reduzirá o espaço em branco extra ou a truncagem.
• Use o parâmetro -Width para evitar a truncagem e manter o alinhamento da saída.

Aqui está um exemplo:

Get-Process | Format-Table -Property Name, ID, CPU, WS -AutoSize | Out-File -FilePath "ProcessList.txt" -Width 200

Format-List

Format-List exibe dados verticalmente, com uma propriedade por linha. Utilize-o quando você tiver muitas propriedades ou campos com valores extensos, de modo a evitar a truncagem desses valores. Este formato é adequado para relatórios e registros detalhados.

Aqui está um exemplo de uso do Format-List com Out-File:

Get-Process | Format-List -Property Name, ID, CPU, StartTime | Out-File -FilePath "DetailedProcessList.txt"

Assim como no Format-Table, selecione apenas as propriedades de que você precisa.

Evite conflitos de arquivo com Test-Path para verificar se os arquivos existem antes de escrever

É sempre prudente verificar se um arquivo existe antes de tentar escrever nele. Assim, você pode evitar sobrescritas acidentais e decidir o que fazer quando um arquivo já existe. O cmdlet Test-Path no PowerShell permite que você verifique a existência de um arquivo.

A seguir estão os passos que você deve seguir:

1. Atribua o caminho do arquivo a uma variável.
2. Use o cmdlet Test-Path para verificar se o arquivo existe.
3. Decida se deseja anexar, sobrescrever, renomear ou pular a escrita.
4. Utilize o cmdlet Out-File para criar ou escrever no arquivo.

Erros Comuns e Soluções

O cmdlet Out-File no PowerShell pode às vezes levar a armadilhas comuns, especialmente em relação ao manuseio de arquivos, codificação e adição de conteúdo. Alguns problemas comuns e suas soluções são discutidos abaixo.

Evite a perda de dados por sobrescrita

Por padrão, o cmdlet Out-File sobrescreve o conteúdo de um arquivo existente sem aviso, se um arquivo com o mesmo nome já existir. Algumas maneiras de evitar isso são:

• Adicione a saída ao arquivo existente em vez de substituí-lo, utilizando o parâmetro -Append.
• Verifique se o arquivo existe com Test-Path e decida como deseja prosseguir com Out-File.

Evite a perda de dados através de codificação inadequada

Por padrão, o Out-File usa codificação Unicode no PowerShell 5.1 e versões anteriores. Ele usa codificação UTF-8 no PowerShell Core e versões posteriores.

A codificação padrão pode não ser compatível com o seu sistema ou aplicações que esperam uma codificação diferente. Portanto, você deve especificar a codificação explicitamente usando o parâmetro -Encoding.

Gerencie a saída em scripts de longa duração para garantir o desempenho

Em ambientes restritos como o PowerShell ISE, executar scripts com o cmdlet Out-File pode levar a problemas como:

• Falha ao manipular estruturas de dados complexas conforme esperado
• Truncamento de saídas longas

Para gerenciar saídas longas, você pode:

• Use o parâmetro -Width para definir uma largura adequada
• Exporte dados complexos para formatos estruturados como CSV ou JSON utilizando os cmdlets Export-Csv ou ConvertTo-Json

Lide com o registro e o tratamento de erros em scripts PowerShell

Às vezes, um arquivo está em uso ou bloqueado por outro processo. Nesse caso, o cmdlet Out-File gerará um erro, pois não será capaz de escrever nele. Você pode lidar com este e outros erros com um bloco try/catch. Um exemplo é o seguinte:

      $content = "Write content to file"
$filePath = "C:\Temp\Errors.txt"
try {
$content | Out-File -FilePath $filePath
Write-Host "File written successfully."
} catch {
Write-Host "File is in use or locked by another process."
}