Escrever arquivos é uma operação fundamental em qualquer linguagem de script, e o PowerShell oferece várias maneiras de fazer isso. Nesta aula, vamos explorar os principais cmdlets para gravar dados em arquivos: Set-Content, Add-Content e Out-File. Você aprenderá não apenas a sintaxe básica, mas também as nuances de cada um, como o comportamento do encoding e as boas práticas para evitar problemas comuns.

Entender as diferenças entre esses cmdlets é crucial para escolher a ferramenta certa para cada tarefa. Por exemplo, Set-Content substitui o conteúdo de um arquivo, enquanto Add-Content adiciona ao final. Já Out-File é frequentemente usado para salvar a saída de comandos, mas tem particularidades que precisam ser consideradas. Vamos mergulhar em cada um deles.

Set-Content e Add-Content

O cmdlet Set-Content é usado para gravar conteúdo em um arquivo, substituindo qualquer conteúdo existente. Ele é ideal quando você deseja criar um novo arquivo ou sobrescrever completamente um existente. A sintaxe básica é Set-Content -Path <caminho> -Value <conteúdo>. O valor pode ser uma string simples ou uma lista de strings, que serão gravadas como linhas separadas.

Já o Add-Content funciona de forma semelhante, mas adiciona o conteúdo ao final do arquivo, preservando o que já existe. Isso é útil para logs, onde você quer anexar novas entradas sem apagar as anteriores. Ambos os cmdlets aceitam o parâmetro -Encoding para especificar a codificação do arquivo, e -Force para sobrescrever arquivos somente leitura.

Vejamos um exemplo prático:

# Criando um arquivo com Set-Content
Set-Content -Path "C:\temp\exemplo.txt" -Value "Linha 1"

# Adicionando mais linhas com Add-Content
Add-Content -Path "C:\temp\exemplo.txt" -Value "Linha 2", "Linha 3"

# Verificando o conteúdo
Get-Content "C:\temp\exemplo.txt"

No exemplo acima, primeiro criamos o arquivo com uma linha, depois adicionamos duas linhas. O resultado final será um arquivo com três linhas. Observe que passamos uma matriz de strings para -Value no Add-Content — isso grava cada elemento em uma linha separada.

Out-File

O cmdlet Out-File é usado para enviar a saída de comandos para um arquivo. Ele é frequentemente utilizado para capturar a saída de um script ou comando em um arquivo de texto. A diferença principal em relação ao Set-Content é que Out-File formata a saída da mesma forma que seria exibida no console, enquanto Set-Content grava strings diretamente.

Por exemplo, ao usar Get-Process para listar processos, a saída é uma tabela formatada. Se você usar Out-File, essa formatação será preservada no arquivo. Já com Set-Content você precisaria converter os dados em strings. Além disso, Out-File também tem o parâmetro -Append para adicionar conteúdo, e -Encoding para especificar a codificação.

Exemplo:

# Salvando a lista de processos em um arquivo
Get-Process | Out-File -FilePath "C:\temp\processos.txt"

# Adicionando mais conteúdo com -Append
Get-Service | Out-File -FilePath "C:\temp\processos.txt" -Append

Note que Out-File usa o encoding Unicode por padrão em versões anteriores do PowerShell, mas no PowerShell 7 o padrão é utf8NoBOM. Isso pode causar confusão se você estiver acostumado com o comportamento antigo. É sempre bom especificar explicitamente o encoding quando a interoperabilidade for importante.

Encoding

Encoding (ou codificação) refere-se à forma como os caracteres são representados em bytes. No PowerShell, você pode especificar o encoding usando o parâmetro -Encoding nos cmdlets de escrita. As opções mais comuns são ASCII, UTF8, Unicode (UTF-16LE) e UTF8BOM.

Escolher o encoding correto é crucial, especialmente se você vai ler o arquivo em outro sistema ou aplicativo. Por exemplo, arquivos com caracteres acentuados (como português) precisam de um encoding que suporte esses caracteres, como UTF-8 ou Unicode. Se você usar ASCII, os caracteres especiais serão perdidos ou corrompidos.

No PowerShell 5.1, o default é Unicode (UTF-16LE) para Out-File e ASCII para Set-Content e Add-Content. Já no PowerShell 7, o default para todos é utf8NoBOM. É importante verificar a versão que você está usando e especificar o encoding quando necessário.

Exemplo de definição de encoding:

# Gravando com UTF-8 sem BOM
Set-Content -Path "C:\temp\utf8.txt" -Value "Olá, mundo!" -Encoding utf8NoBOM

# Gravando com Unicode (UTF-16LE)
Set-Content -Path "C:\temp\unicode.txt" -Value "Olá, mundo!" -Encoding Unicode

# Verificando o tamanho dos arquivos
Get-Item C:\temp\utf8.txt, C:\temp\unicode.txt | Select-Object Name, Length

Note que o arquivo Unicode terá o dobro do tamanho porque cada caractere ocupa 2 bytes. Para a maioria dos casos, UTF-8 é recomendado por ser compatível com a web e sistemas Unix.

Cuidados

Ao escrever arquivos no PowerShell, alguns cuidados são essenciais para evitar erros e comportamentos inesperados:

  • Permissões: Certifique-se de que você tem permissão de escrita no diretório de destino. Caso contrário, você receberá um erro de acesso negado.
  • Sobrescrita: Set-Content sobrescreve o arquivo sem aviso. Se você quiser evitar isso, use o parâmetro -NoClobber (disponível em versões mais recentes) ou verifique se o arquivo existe antes.
  • Encoding: Sempre especifique o encoding se o conteúdo tiver caracteres não ASCII. Isso evita corrupção de dados.
  • Newline: O PowerShell usa `n (LF) ou `r`n (CRLF) dependendo do encoding e da plataforma. Em arquivos de texto, isso pode afetar a compatibilidade com outros sistemas.
  • Arquivos em uso: Se o arquivo estiver aberto em outro programa, a escrita pode falhar. Use try/catch para tratar esses erros.

Exemplo de tratamento de erro:

try {
    Set-Content -Path "C:\temp\importante.txt" -Value "Dados" -ErrorAction Stop
} catch {
    Write-Error "Falha ao escrever: $_"
}

Além disso, lembre-se de que Add-Content e Out-File -Append não criam o arquivo se ele não existir? Na verdade, eles criam. Mas é bom saber que Set-Content também cria. Todos eles criam o arquivo se não existir, desde que o diretório exista.

Referências

Exercícios

  1. Exercício 1: Crie um arquivo chamado `teste.txt` no diretório `C:\temp` usando `Set-Content` com a frase "Primeiro teste". Verifique o conteúdo com `Get-Content`.

    2. ✓ Resposta: 
    Set-Content -Path "C:\temp\teste.txt" -Value "Primeiro teste"
Get-Content "C:\temp\teste.txt"
  2. Exercício 2: Adicione as linhas "Linha 2" e "Linha 3" ao arquivo `teste.txt` usando `Add-Content`. Depois, exiba o conteúdo final.

    3. ✓ Resposta: 
    Add-Content -Path "C:\temp\teste.txt" -Value "Linha 2", "Linha 3"
Get-Content "C:\temp\teste.txt"
  3. Exercício 3: Salve a saída do comando `Get-Date` em um arquivo chamado `data.txt` usando `Out-File`. Depois, leia o arquivo para confirmar.

    4. ✓ Resposta: 
    Get-Date | Out-File -FilePath "C:\temp\data.txt"
Get-Content "C:\temp\data.txt"
  4. Exercício 4: Escreva a frase "Ação concluída" em um arquivo `log.txt` usando `Add-Content` com encoding UTF-8. Verifique o encoding do arquivo com `Get-Content -Encoding UTF8`.

    5. ✓ Resposta: 
    Add-Content -Path "C:\temp\log.txt" -Value "Ação concluída" -Encoding UTF8
Get-Content "C:\temp\log.txt" -Encoding UTF8
  5. Exercício 5: Crie um script que verifique se o arquivo `C:\temp\dados.txt` existe. Se existir, adicione a data atual com `Add-Content`; se não, crie com `Set-Content` contendo "Início do log". Use `Test-Path`.

    6. ✓ Resposta: 
    $caminho = "C:\temp\dados.txt"
if (Test-Path $caminho) {
    Add-Content -Path $caminho -Value (Get-Date)
} else {
    Set-Content -Path $caminho -Value "Início do log"
}

Observações Finais

Nesta aula, você aprendeu os principais cmdlets para escrita de arquivos no PowerShell. Lembre-se de sempre testar seus scripts em um ambiente seguro e verificar as permissões e encodings. Com essas ferramentas, você pode automatizar a criação de logs, relatórios e arquivos de configuração com facilidade.

Uma boa prática é usar -ErrorAction Stop em operações críticas para capturar erros e tratá-los adequadamente. Além disso, considere usar Set-Content com o parâmetro -NoClobber se você quiser evitar a sobrescrita acidental (disponível no PowerShell 7+). Continue praticando e explorando a documentação oficial para aprofundar seu conhecimento.