about_Redirection

Artigo
06/21/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, esse é o aplicativo de console. No entanto, você pode redirecionar a saída para um arquivo de texto e 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 Out-File cmdlet, que envia a saída de comando para um arquivo de texto. Normalmente, você usa o Out-File cmdlet quando precisa usar seus parâmetros, como os Encodingparâmetros , ForceWidthou NoClobber .
Use o Tee-Object cmdlet, que envia a saída de comando para um arquivo de texto e, em seguida, envia-a para o pipeline.
Use os operadores de redirecionamento do PowerShell. Usar o operador de redirecionamento com um destino de arquivo é funcionalmente equivalente à canalização sem Out-File parâmetros extras.

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.

Fluxo #	Descrição	Introduzido no	Cmdlet de gravação
1	Sucesso Fluxo	PowerShell 2.0	`Write-Output`
2	Erro Fluxo	PowerShell 2.0	`Write-Error`
3	Aviso Fluxo	PowerShell 3.0	`Write-Warning`
4	Verbose Fluxo	PowerShell 3.0	`Write-Verbose`
5	Depurar Fluxo	PowerShell 3.0	`Write-Debug`
6	Informações Fluxo	PowerShell 5.0	`Write-Information`
*	Todos os Fluxos	PowerShell 3.0

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

Importante

Os fluxos de êxito e erro 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 success ( 1 ) é o padrão se nenhum fluxo for especificado.

Operador	Descrição	Syntax
`>`	Enviar fluxo especificado para um arquivo.	`n>`
`>>`	Acrescente o fluxo especificado a um arquivo.	`n>>`
`>&1`	Redireciona o fluxo especificado para o fluxo success .	`n>&1`

Observação

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

Exemplos

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

Este exemplo é executado dir em um item que terá êxito e um que errou.

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

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

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

Este exemplo envia todos os dados de fluxo de sucesso 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 Sucesso .
2>&1 redireciona o fluxo de erros para o fluxo de Sucesso (que também agora inclui todos os dados de fluxo de aviso)
> redireciona o fluxo success (que agora contém 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 todas as saídas de fluxos 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 Write-Host

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 afeta $ErrorActionPreference o que é gravado no fluxo de 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 está definido como Inquire.

PS C:\temp> .\test.ps1

Confirm
Cannot find path 'C:\not-here' because it does not 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

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 arquivo 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 de sistema, oculto ou somente leitura, 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 poderá não ser 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 os Out-File operadores de redirecionamento 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 em log 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-preview;C:\WINDOWS…

Considerando que a largura do console pode ser definida arbitrariamente em sistemas em que seu script é executado, você pode preferir que a saída da tabela de formato do PowerShell para arquivos com base em uma largura especificada em vez disso.

O Out-File cmdlet fornece um parâmetro Width que permite definir a largura desejada para a saída da tabela. Em vez de precisar adicionar -Width 2000 em todos os lugares invocados 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 afeta a largura de formatação para os operadores de redirecionamento também. Coloque o seguinte comando perto da parte superior do script para definir Out-File:Width 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 na tabela. Se você estiver registrando muitos dados tabulares no arquivo e souber que pode se dar bem 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 fazer a saída para o arquivo.

$PSDefaultParameterValues['out-file:width'] = 2000
Get-Service | Format-Table -AutoSize > services.log

Para obter mais informações sobre $PSDefaultParameterValues, 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 maior do que (geralmente indicado como > em outras linguagens de programação).

Dependendo dos objetos que estão sendo comparados, o uso > da saída pode parecer correto (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

Tentar usar a comparação < inversa (menor que), gera 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 no about_Comparison_Operators.