about_Redirection

2024-11-06

Descrição breve

Explica como redirecionar a saída do PowerShell para arquivos de texto.

Descrição longa

Por padrão, o PowerShell envia a saída para o host do PowerShell. Normalmente, este é o aplicativo de console. No entanto, você pode redirecionar a saída para um arquivo de texto e pode redirecionar a saída de erro para o fluxo de saída regular.

Você pode usar os seguintes métodos para redirecionar a saída:

Use o cmdlet, que envia a saída do Out-File comando para um arquivo de texto. Normalmente, você usa o Out-File cmdlet quando precisa usar seus parâmetros, como os Encodingparâmetros , Force, Width, ou NoClobber .
Use o cmdlet, que envia a saída do Tee-Object comando para um arquivo de texto e, em seguida, a envia para o pipeline.
Use os operadores de redirecionamento do PowerShell. Redirecionar a saída de um comando do PowerShell (cmdlet, função, script) usando o operador de redirecionamento (>) é funcionalmente equivalente a canalizar para Out-File sem parâmetros extras. O PowerShell 7.4 alterou o comportamento do operador de redirecionamento quando usado para redirecionar o fluxo stdout de um comando nativo.

Para obter mais informações sobre fluxos, consulte about_Output_Streams.

Fluxos de saída redirecionáveis

O PowerShell dá suporte ao redirecionamento dos fluxos de saída a seguir.

Riacho #	Descrição	Introduzido no	Cmdlet de gravação
1	Fluxo de sucesso	PowerShell 2.0	`Write-Output`
2	Fluxo de erro	PowerShell 2.0	`Write-Error`
3	Fluxo de aviso	PowerShell 3.0	`Write-Warning`
4	Córrego Detalhado	PowerShell 3.0	`Write-Verbose`
5	Fluxo de depuração	PowerShell 3.0	`Write-Debug`
6	Fluxo de informações	PowerShell 5.0	`Write-Information`, `Write-Host`
*	Todos os fluxos	PowerShell 3.0

Há também um fluxo de progresso no PowerShell, mas ele não dá suporte ao redirecionamento.

Importante

Os fluxos de Sucesso e Erro são semelhantes aos fluxos stdout e stderr de outros shells. No entanto, stdin não está conectado ao pipeline do PowerShell para entrada.

Operadores de redirecionamento do PowerShell

Os operadores de redirecionamento do PowerShell são os seguintes, onde n representa o número do fluxo. O fluxo de sucesso ( 1 ) será o padrão se nenhum fluxo for especificado.

Operador	Descrição	Sintaxe
`>`	Envie o fluxo especificado para um arquivo.	`n>`
`>>`	Anexe o fluxo especificado a um arquivo.	`n>>`
`>&1`	Redireciona o fluxo especificado para o fluxo de sucesso .	`n>&1`

Observação

Ao contrário de alguns shells Unix, você só pode redirecionar outros fluxos para o fluxo de sucesso .

Redirecionando a saída de comandos nativos

O PowerShell 7.4 alterou o comportamento dos operadores de redirecionamento quando usados para redirecionar o fluxo stdout de um comando nativo. Os operadores de redirecionamento agora preservam os dados de fluxo de bytes ao redirecionar a saída de um comando nativo. O PowerShell não interpreta os dados redirecionados nem adiciona formatação adicional. Para obter mais informações, consulte o Exemplo #7.

Exemplos

Exemplo 1: redirecionar erros e saída para um arquivo

Este exemplo é executado dir em um item que é bem-sucedido e outro que falha.

dir C:\, fakepath 2>&1 > .\dir.log

Ele usa 2>&1 para redirecionar o fluxo de Erro para o fluxo de Sucesso e > para enviar o fluxo de Sucesso resultante para um arquivo chamadodir.log

Exemplo 2: Enviar todos os dados do fluxo de sucesso para um arquivo

Este exemplo envia todos os dados do fluxo de sucesso para um arquivo chamado script.log.

.\script.ps1 > script.log

Exemplo 3: Enviar fluxos de sucesso, aviso e erro para um arquivo

Este exemplo mostra como você pode combinar operadores de redirecionamento para obter um resultado desejado.

&{
   Write-Warning "hello"
   Write-Error "hello"
   Write-Output "hi"
} 3>&1 2>&1 > C:\Temp\redirection.log

3>&1 redireciona o fluxo de Aviso para o fluxo de Êxito .
2>&1 redireciona o fluxo de Erro para o fluxo de Sucesso (que agora também inclui todos os dados do fluxo de Aviso )
> redireciona o fluxo de sucesso (que agora contém os fluxos de aviso e erro ) para um arquivo chamado C:\temp\redirection.log.

Exemplo 4: Redirecionar todos os fluxos para um arquivo

Este exemplo envia todos os fluxos de saída de um script chamado script.ps1 para um arquivo chamado script.log.

.\script.ps1 *> script.log

Exemplo 5: Suprimir todos os dados do Write-Host e do fluxo de informações

Este exemplo suprime todos os dados do fluxo de informações. Para ler mais sobre cmdlets de fluxo de informações , consulte Write-Host e Write-Information

&{
   Write-Host "Hello"
   Write-Information "Hello" -InformationAction Continue
} 6> $null

Exemplo 6: Mostrar o efeito das Preferências de Ação

Variáveis e parâmetros de Preferência de Ação podem alterar o que é gravado em um fluxo específico. O script neste exemplo mostra como o valor de $ErrorActionPreference afeta o que é gravado no fluxo de Erro .

$ErrorActionPreference = 'Continue'
$ErrorActionPreference > log.txt
Get-Item /not-here 2>&1 >> log.txt

$ErrorActionPreference = 'SilentlyContinue'
$ErrorActionPreference >> log.txt
Get-Item /not-here 2>&1 >> log.txt

$ErrorActionPreference = 'Stop'
$ErrorActionPreference >> log.txt
try {
    Get-Item /not-here 2>&1 >> log.txt
}
catch {
    "`tError caught!" >> log.txt
}
$ErrorActionPreference = 'Ignore'
$ErrorActionPreference >> log.txt
Get-Item /not-here 2>&1 >> log.txt

$ErrorActionPreference = 'Inquire'
$ErrorActionPreference >> log.txt
Get-Item /not-here 2>&1 >> log.txt

$ErrorActionPreference = 'Continue'

Quando executamos esse script, somos avisados quando $ErrorActionPreference está definido como Inquire.

PS C:\temp> .\test.ps1

Confirm
Can't find path 'C:\not-here' because it doesn't exist.
[Y] Yes  [A] Yes to All  [H] Halt Command  [S] Suspend  [?] Help (default is "Y"): H
Get-Item: C:\temp\test.ps1:23
Line |
  23 |  Get-Item /not-here 2>&1 >> log.txt
     |  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | The running command stopped because the user selected the Stop option.

Quando examinamos o arquivo de log, vemos o seguinte:

PS C:\temp> Get-Content .\log.txt
Continue

Get-Item: C:\temp\test.ps1:3
Line |
   3 |  Get-Item /not-here 2>&1 >> log.txt
     |  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | Cannot find path 'C:\not-here' because it does not exist.

SilentlyContinue
Stop
    Error caught!
Ignore
Inquire

Exemplo 7: redirecionando dados binários de um comando nativo

A partir do PowerShell 7.4, o PowerShell preserva os dados de fluxo de bytes ao redirecionar o fluxo stdout de um comando nativo para um arquivo ou ao canalizar dados de fluxo de bytes para o fluxo stdin de um comando nativo.

Por exemplo, usando o comando curl nativo, você pode baixar um arquivo binário e salvá-lo em disco usando o redirecionamento.

$uri = 'https://github.com/PowerShell/PowerShell/releases/download/v7.3.7/powershell-7.3.7-linux-arm64.tar.gz'

# native command redirected to a file
curl -s -L $uri > powershell.tar.gz

Você também pode redirecionar os dados de fluxo de bytes para o fluxo stdin de outro comando nativo. O exemplo a seguir baixa um arquivo TAR compactado usando curl. Os dados do arquivo baixado são transmitidos ao comando tar para extrair o conteúdo do arquivo morto.

# native command output piped to a native command
curl -s -L $uri | tar -xzvf - -C .

Você também pode redirecionar a saída de fluxo de bytes de um comando do PowerShell para a entrada do comando nativo. Os exemplos a seguir usam Invoke-WebRequest para baixar o mesmo arquivo TAR do exemplo anterior.

# byte stream piped to a native command
(Invoke-WebRequest $uri).Content | tar -xzvf - -C .

# bytes piped to a native command (all at once as byte[])
,(Invoke-WebRequest $uri).Content | tar -xzvf - -C .

Esse recurso não dá suporte a dados de fluxo de bytes ao redirecionar a saída stderr para stdout. Quando você combina os fluxos stderr e stdout, os fluxos combinados são tratados como dados de cadeia de caracteres.

Observações

Os operadores de redirecionamento que não acrescentam dados (> e n>) substituem o conteúdo atual do arquivo especificado sem aviso.

No entanto, se o arquivo for somente leitura, oculto ou do sistema, o redirecionamento falhará. Os operadores de redirecionamento de acréscimo (>> e n>>) não gravam em um arquivo somente leitura, mas acrescentam conteúdo a um sistema ou arquivo oculto.

Para forçar o redirecionamento de conteúdo para um arquivo somente leitura, oculto ou do sistema, use o Out-File cmdlet com seu Force parâmetro.

Quando você está gravando em arquivos, os operadores de redirecionamento usam UTF8NoBOM codificação. Se o arquivo tiver uma codificação diferente, a saída pode não estar formatada corretamente. Para gravar em arquivos com uma codificação diferente, use o Out-File cmdlet com seu Encoding parâmetro.

Largura da saída ao gravar em um arquivo

Quando você está gravando em um arquivo usando um ou Out-File os operadores de redirecionamento, o PowerShell formata a saída da tabela para o arquivo com base na largura do console em que ele está sendo executado. Por exemplo, ao registrar a saída da tabela no arquivo usando um comando, como em um sistema em Get-ChildItem Env:\Path > path.log que a largura do console é definida como 80 colunas, a saída no arquivo é truncada para 80 caracteres:

Name                         Value
----                         -----
Path                         C:\Program Files\PowerShell\7;C:\WINDOWS…

Considerando que a largura do console pode ser definida arbitrariamente em sistemas em que o script é executado, talvez você prefira que a saída da tabela no formato do PowerShell seja exibida para arquivos com base em uma largura especificada.

O Out-File cmdlet fornece um parâmetro Width que permite definir a largura desejada para a saída da tabela. Em vez de ter que adicionar -Width 2000 em todos os lugares que você invoca Out-File, você pode usar a $PSDefaultParameterValues variável para definir esse valor para todos os usos do Out-File cmdlet em um script. E como os operadores de redirecionamento (> e >>) são efetivamente aliases para Out-File, definir o Out-File:Width parâmetro para todo o script também afeta a largura de formatação dos operadores de redirecionamento. Coloque o seguinte comando próximo à parte superior do script para definir Out-File:Width todo o script:

$PSDefaultParameterValues['Out-File:Width'] = 2000

Aumentar a largura de saída aumentará o consumo de memória ao registrar a saída formatada em tabela. Se você estiver registrando muitos dados tabulares no arquivo e souber que pode sobreviver com uma largura menor, use a largura menor.

Em alguns casos, como Get-Service saída, para usar a largura extra, você precisará canalizar a saída Format-Table -AutoSize antes de enviar para o arquivo.

$PSDefaultParameterValues['Out-File:Width'] = 2000
Get-Service | Format-Table -AutoSize > services.log

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

Possível confusão com operadores de comparação

O > operador não deve ser confundido com o operador de comparação Maior que (geralmente denotado como > em outras linguagens de programação).

Dependendo dos objetos que estão sendo comparados, a saída usando > pode parecer correta (porque 36 não é maior que 42).

PS> if (36 > 42) { "true" } else { "false" }
false

No entanto, uma verificação do sistema de arquivos local pode ver que um arquivo chamado 42 foi gravado, com o conteúdo 36.

PS> dir

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
------          1/02/20  10:10 am              3 42

PS> cat 42
36

A tentativa de usar a comparação < reversa (menor que) produz um erro do sistema:

PS> if (36 < 42) { "true" } else { "false" }
ParserError:
Line |
   1 |  if (36 < 42) { "true" } else { "false" }
     |         ~
     | The '<' operator is reserved for future use.

Se a comparação numérica for a operação -lt necessária e -gt deve ser usada. Para obter mais informações, consulte o -gt operador em about_Comparison_Operators.