about_Redirection

Artigo
12/06/2023

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 você 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 Out-File saída do comando para um arquivo de texto. Normalmente, você usa o Out-File cmdlet quando precisa usar seus parâmetros, como o Encoding, Force, Widthou NoClobber parâmetros.
Use o cmdlet, que envia a Tee-Object saída do comando para um arquivo de texto e, em seguida, o 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 à tubulação 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 oferece suporte ao redirecionamento dos seguintes fluxos de saída.

Riacho #	Descrição	Introduzido no	Cmdlet de gravação
1	Fluxo de sucesso	PowerShell 2.0	`Write-Output`
2	Fluxo de erros	PowerShell 2.0	`Write-Error`
3	Fluxo de Aviso	PowerShell 3.0	`Write-Warning`
4	Fluxo 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 Streams	PowerShell 3.0

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

Importante

Os fluxos Success e Error são semelhantes aos fluxos stdout e stderr de outros shells. No entanto, o 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 êxito ( 1 ) será o padrão se nenhum fluxo for especificado.

Operador	Descrição	Sintaxe
`>`	Enviar fluxo especificado para um arquivo.	`n>`
`>>`	Acrescentar fluxo especificado a um arquivo.	`n>>`
`>&1`	Redireciona o fluxo especificado para o fluxo Êxito .	`n>&1`

Observação

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

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 bem-sucedido e outro que falha.

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

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

Exemplo 2: Enviar todos os dados de fluxo de êxito para um arquivo

Este exemplo envia todos os dados de fluxo de êxito para um arquivo chamado script.log.

.\script.ps1 > script.log

Exemplo 3: Enviar fluxos de êxito, 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 Erros para o fluxo de Êxito (que agora também inclui todos os dados de fluxo de Aviso )
> redireciona o fluxo de êxito (que agora contém fluxos de aviso e de 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 de fluxo de informações e host de gravação

Este exemplo suprime todos os dados de 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

As 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 afeta o que é gravado no fluxo de $ErrorActionPreference erros.

$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 solicitados quando $ErrorActionPreference é 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: Redirecionar 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 Out-File ou 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 Get-ChildItem Env:\Path > path.log em um sistema em 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, você pode preferir a saída da tabela de formato do PowerShell 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 todos os lugares que você invocar 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 para os operadores de redirecionamento. Coloque o seguinte comando perto da parte superior do script para definir Out-File:Width para o script inteiro:

$PSDefaultParameterValues['out-file:width'] = 2000

Aumentar a largura de saída aumentará o consumo de memória ao registrar a saída formatada da 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 a saída, para usar a largura extra, você precisará canalizar a saída antes Format-Table -AutoSize 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.

Confusão potencial com operadores de comparação

O > operador não deve ser confundido com o operador de comparação Greater-than (muitas vezes denotado como > em outras linguagens de programação).

Dependendo dos objetos que estão sendo comparados, a saída usada > 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 < inversa (menor que), produz um erro de 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 é a operação necessária, -lt e -gt deve ser usada. Para obter mais informações, consulte o operador em about_Comparison_Operators-gt.