Out-File

Módulo:

Microsoft.PowerShell.Utility Module

Envia a saída para um arquivo.

Sintaxe

ByPath (Predefinição)

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

ByLiteralPath

Out-File
    [[-Encoding] <Encoding>]
    -LiteralPath <string>
    [-Append]
    [-Force]
    [-NoClobber]
    [-Width <int>]
    [-NoNewline]
    [-InputObject <psobject>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Description

O cmdlet Out-File envia a saída para um arquivo. Ele usa implicitamente o sistema de formatação do PowerShell para gravar no arquivo. O arquivo recebe a mesma representação de exibição que o terminal. Isso significa que a saída pode não ser ideal para processamento programático, a menos que todos os objetos de entrada sejam strings. Quando precisar especificar parâmetros para a saída, use Out-File em vez do operador de redirecionamento (>). Para obter mais informações sobre redirecionamento, consulte about_Redirection.

Exemplos

Exemplo 1: Enviar saída e criar um arquivo

Este exemplo mostra como enviar uma lista dos processos do computador local para um arquivo. Se o arquivo não existir, Out-File criará o arquivo no caminho especificado.

Get-Process | Out-File -FilePath .\Process.txt
Get-Content -Path .\Process.txt

 NPM(K)    PM(M)      WS(M)     CPU(s)      Id  SI ProcessName
 ------    -----      -----     ------      --  -- -----------
     29    22.39      35.40      10.98   42764   9 Application
     53    99.04     113.96       0.00   32664   0 CcmExec
     27    96.62     112.43     113.00   17720   9 Code

O cmdlet Get-Process obtém a lista de processos em execução no computador local. Os objetos Processo são enviados pelo pipeline para o cmdlet Out-File. Out-File usa o parâmetro FilePath e cria um arquivo no diretório atual chamado Process.txt. O comando Get-Content obtém conteúdo do arquivo e o exibe no console do PowerShell.

Exemplo 2: Impedir que um arquivo existente seja substituído

Este exemplo impede que um arquivo existente seja substituído. Por padrão, Out-File substitui arquivos existentes.

Get-Process | Out-File -FilePath .\Process.txt -NoClobber

Out-File : The file 'C:\Test\Process.txt' already exists.
At line:1 char:15
+ Get-Process | Out-File -FilePath .\Process.txt -NoClobber
+               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

O cmdlet Get-Process obtém a lista de processos em execução no computador local. Os objetos Processo são enviados pelo pipeline para o cmdlet Out-File. Out-File usa o parâmetro FilePath e tenta gravar em um arquivo no diretório atual chamado Process.txt. O parâmetro NoClobber impede que o arquivo seja substituído e exibe uma mensagem informando que o arquivo já existe.

Exemplo 3: Enviar saída para um arquivo no formato ASCII

Este exemplo mostra como codificar a saída com um tipo de codificação específico.

$Procs = Get-Process
Out-File -FilePath .\Process.txt -InputObject $Procs -Encoding ASCII -Width 50

O cmdlet Get-Process obtém a lista de processos em execução no computador local. O processo objetos são armazenados na variável $Procs. Out-File usa o parâmetro FilePath e cria um arquivo no diretório atual chamado Process.txt. O parâmetro InputObject passa os objetos de processo em $Procs para o arquivo Process.txt. O parâmetro Encoding converte a saída para formato de ASCII. O parâmetro Width limita cada linha do arquivo a 50 caracteres, portanto, alguns dados podem ser truncados.

Exemplo 4: Usar um provedor e enviar a saída para um arquivo

Este exemplo mostra como usar o cmdlet Out-File quando você não está em uma unidade de provedor de FileSystem. Use o cmdlet Get-PSProvider para exibir os provedores em seu computador local. Para obter mais informações, consulte about_Providers.

PS> Set-Location -Path Alias:

PS> Get-Location

Path
----
Alias:\

PS> Get-ChildItem | Out-File -FilePath C:\TestDir\AliasNames.txt

PS> Get-Content -Path C:\TestDir\AliasNames.txt

CommandType     Name
-----------     ----
Alias           % -> ForEach-Object
Alias           ? -> Where-Object
Alias           ac -> Add-Content
Alias           cat -> Get-Content

O comando Set-Location usa o parâmetro Path para definir o local atual para o provedor do Registro Alias:. O cmdlet Get-Location exibe o caminho completo para Alias:. Get-ChildItem envia objetos pelo pipeline para o cmdlet Out-File. Out-File usa o parâmetro FilePath para especificar o caminho completo e o nome do arquivo para a saída, C:\TestDir\AliasNames.txt. O cmdlet Get-Content usa o parâmetro Path e exibe o conteúdo do arquivo no console do PowerShell.

Exemplo 5: Definir a largura de saída do arquivo para todo o escopo

Este exemplo usa $PSDefaultParameterValues para definir o Width parâmetro para todas as invocações de e os operadores de Out-File redirecionamento (> e >>) para 2000. Isso garante que, em todos os lugares dentro do escopo atual em que você envia dados formatados de tabela para arquivo, o PowerShell usa uma largura de linha de 2000 em vez de uma largura de linha determinada pela largura do console do host do PowerShell.

function DemoDefaultOutFileWidth() {
    try {
        $PSDefaultParameterValues['out-file:width'] = 2000

        $logFile = "$pwd\logfile.txt"

        Get-ChildItem Env:\ > $logFile

        Get-Service -ErrorAction Ignore |
            Format-Table -AutoSize |
            Out-File $logFile -Append

        Get-Process | Format-Table Id,SI,Name,Path,MainWindowTitle >> $logFile
    }
    finally {
        $PSDefaultParameterValues.Remove('out-file:width')
    }
}

DemoDefaultOutFileWidth

Para obter mais informações sobre $PSDefaultParameterValues, consulte about_Preference_Variables.

Parâmetros

-Append

Adiciona a saída ao final de um arquivo existente.

Propriedades dos parâmetros

Tipo:	SwitchParameter
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-Confirm

Solicita confirmação antes de executar o cmdlet.

Propriedades dos parâmetros

Tipo:	SwitchParameter
Default value:	False
Suporta carateres universais:	False
NãoMostrar:	False
Aliases:	Cf.

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-Encoding

Especifica o tipo de codificação para o arquivo de destino. O valor predefinido é utf8NoBOM.

Os valores aceitáveis para este parâmetro são os seguintes:

• ascii: Usa a codificação para o conjunto de caracteres ASCII (7 bits).
• bigendianunicode: Codifica no formato UTF-16 usando a ordem de bytes big-endian.
• bigendianutf32: Codifica no formato UTF-32 utilizando a ordem de bytes big-endian.
• oem: Utiliza a codificação predefinida para MS-DOS e programas de consola.
• unicode: Codifica em formato UTF-16 utilizando a ordem de bytes little-endian.
• utf7: Codifica em formato UTF-7.
• utf8: Codifica em formato UTF-8.
• utf8BOM: Codifica no formato UTF-8 com Byte Order Mark (BOM)
• utf8NoBOM: Codifica no formato UTF-8 sem Byte Order Mark (BOM)
• utf32: Codifica no formato UTF-32.

A partir do PowerShell 6.2, o parâmetro Encoding também permite IDs numéricos de páginas de código registradas (como -Encoding 1251) ou nomes de cadeia de caracteres de páginas de código registradas (como -Encoding "windows-1251"). Para obter mais informações, consulte a documentação do .NET para Encoding.CodePage.

Observação

UTF-7* não é mais recomendado para usar. A partir do PowerShell 7.1, um aviso será escrito se você especificar utf7 para o parâmetro Encoding.

Propriedades dos parâmetros

Tipo:	Encoding
Default value:	UTF8NoBOM
Valores aceites:	ASCII, BigEndianUnicode, BigEndianUTF32, OEM, Unicode, UTF7, UTF8, UTF8BOM, UTF8NoBOM, UTF32
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	1
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-FilePath

Especifica o caminho para o arquivo de saída.

Propriedades dos parâmetros

Tipo:	String
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False
Aliases:	Caminho

Conjuntos de parâmetros

ByPath

Position:	0
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-Force

Substitui o atributo somente leitura e substitui um arquivo somente leitura existente. O parâmetro Force não substitui as restrições de segurança.

Propriedades dos parâmetros

Tipo:	SwitchParameter
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-InputObject

Especifica os objetos a serem gravados no arquivo. Insira uma variável que contenha os objetos ou digite um comando ou expressão que obtenha os objetos.

Propriedades dos parâmetros

Tipo:	PSObject
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	True
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-LiteralPath

Especifica o caminho para o arquivo de saída. O parâmetro LiteralPath é usado exatamente como é digitado. Caracteres curinga não são aceitos. Se o caminho incluir caracteres de escape, coloque-o entre aspas simples. Aspas simples indicam ao PowerShell para não interpretar quaisquer caracteres como sequências de escape. Para obter mais informações, consulte about_Quoting_Rules.

Propriedades dos parâmetros

Tipo:	String
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False
Aliases:	PSPath, LP

Conjuntos de parâmetros

ByLiteralPath

Position:	Named
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	True
Valor dos restantes argumentos:	False

-NoClobber

NoClobber impede que um arquivo existente seja substituído e exibe uma mensagem informando que o arquivo já existe. Por padrão, se existir um arquivo no caminho especificado, Out-File substitui o arquivo sem aviso.

Propriedades dos parâmetros

Tipo:	SwitchParameter
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False
Aliases:	NoOverwrite

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-NoNewline

Especifica que o conteúdo gravado no arquivo não termina com um caractere de nova linha. As representações de cadeia de caracteres dos objetos de entrada são concatenadas para formar a saída. Nenhum espaço ou novas linhas são inseridos entre as cadeias de caracteres de saída. Nenhuma nova linha é adicionada após a última cadeia de caracteres de saída.

Propriedades dos parâmetros

Tipo:	SwitchParameter
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-WhatIf

Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.

Propriedades dos parâmetros

Tipo:	SwitchParameter
Default value:	False
Suporta carateres universais:	False
NãoMostrar:	False
Aliases:	Wi

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

-Width

Especifica o número máximo de caracteres em cada linha de saída. Todos os caracteres adicionais são truncados, não encapsulados. Se esse parâmetro não for usado, a largura será determinada pelas características do host. O padrão para o console do PowerShell é 80 caracteres. Se você quiser controlar a largura de todas as invocações de Out-File, bem como os operadores de redirecionamento (> e >>), defina $PSDefaultParameterValues['out-file:width'] = 2000 antes de usar Out-File.

Propriedades dos parâmetros

Tipo:	Int32
Default value:	None
Suporta carateres universais:	False
NãoMostrar:	False

Conjuntos de parâmetros

(All)

Position:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline por nome de propriedade:	False
Valor dos restantes argumentos:	False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Entradas

PSObject

Você pode canalizar qualquer objeto para este cmdlet.

Saídas

None

Este cmdlet não retorna nenhuma saída.

Notas

Os objetos de entrada são formatados automaticamente como estariam no terminal, mas você pode usar um cmdlet Format-* para controlar explicitamente a formatação da saída para o arquivo. Por exemplo, Get-Date | Format-List | Out-File out.txt

Para enviar a saída de um comando do PowerShell para o cmdlet Out-File, use o pipeline. Como alternativa, você pode armazenar dados em uma variável e usar o parâmetro InputObject para passar dados para o cmdlet Out-File.

Out-File salva dados em um arquivo, mas não produz nenhum objeto de saída para o pipeline.

O PowerShell 7.2 adicionou a capacidade de controlar como as sequências de escape ANSI são renderizadas. A saída decorada com ANSI que é passada para Out-File pode ser alterada com base na configuração da propriedade $PSStyle.OutputRendering. Para obter mais informações, consulte about_ANSI_Terminals.

Ligações Relacionadas

• sobre_Fornecedores
• sobre_Regras_de_Citação
• Out-Default
• Out-Host
• Out-Null
• Out-String
• Tee-Object