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 Out-File cmdlet quando você não está em uma unidade de provedor 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. Essa é uma maneira fácil de garantir que, em todos os lugares de um escopo em que você envia dados formatados da tabela para o arquivo, o PowerShell usará 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 de caracteres em cada linha de saída. Todos os caracteres adicionais são truncados, não encapsulados. Se este parâmetro não for usado, a largura é 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 Out-File.

Saídas

None

Out-File não gera 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.

Ligações Relacionadas

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