Powershell перенаправление вывода ошибок

Аналоги > и >> в PowerShell

Если вы знакомы с операторами командной строки Linux, то вы можете знать, что оператор «>» перенаправляет вывод в файл, если файл существует, то он перезаписывается, если файл не существует, то он создаётся и в него записывается содержимое.

В PowerShell этот оператор также работает, например, в следующей команде результат работы командлета будет сохранён в файл man.txt:

Get-Help about_Comparison_Operators -Full > man.txt

В Linux существует ещё один оператор для перенаправления стандартного вывода, это «>>», который работает аналогично предыдущему, но если файл уже существует, то вместо перезаписи, новые данные дописываются в файл, например, следующая команда допишет выводом командлета содержимое файла man.txt, а если его нет, то создаст этот файл:

Get-Help about_Comparison_Operators -Full >> man.txt

В PowerShell вы можете использовать «>» и «>>» если вам достаточно простого перенаправления вывода в файл. Также имеется командлет Out-File который кроме выполнения перенаправления вывода имеет дополнительную функциональность.

Перенаправление вывода в PowerShell

По умолчанию PowerShell отправляет выходные данные своей команды в консоль PowerShell. Однако вы можете направить вывод в текстовый файл, и вы можете перенаправить вывод ошибок в обычный поток вывода.

Для перенаправления вывода можно использовать следующие методы:

• Использовать командлет Out-File, который отправляет выходные данные команды в текстовый файл. Как правило, вы используете командлет Out-File когда вам нужно использовать его параметры, такие как параметры -Encoding, -Force, -Width или -NoClobber.
• Использовать командлет Tee-Object, который отправляет вывод команды в текстовый файл, а затем отправляет его в конвейер.
• Использовать операторы перенаправления PowerShell.

Операторы перенаправления PowerShell

Операторы перенаправления позволяют отправлять потоки данных в файл или выходной поток SUCCESS.

Операторы перенаправления PowerShell используют следующие числа для представления доступных выходных потоков:

№ потока	Описание	Представлен в
1	SUCCESS Stream	PowerShell 2.0
2	ERROR Stream	PowerShell 2.0
3	WARNING Stream	PowerShell 3.0
4	VERBOSE Stream	PowerShell 3.0
5	DEBUG Stream	PowerShell 3.0
6	INFORMATION Stream	PowerShell 5.0
*	All Streams	PowerShell 3.0

[!ПРИМЕЧАНИЕ] В PowerShell также есть поток PROGRESS, но он не используется для перенаправления.

Ниже перечислены операторы перенаправления PowerShell, где n представляет номер потока. Поток SUCCESS (1) используется по умолчанию, если поток не указан.

Оператор	Описание	Синтаксис
>	Отправить указанный поток в файл.	n>
>>	ДОБАВИТЬ указанный поток к файлу.	n>>
>&1	_Перенаправляет_ указанный поток в поток SUCCESS.	n>&1

[!ПРИМЕЧАНИЕ] В отличие от некоторых оболочек Unix, вы можете перенаправлять другие потоки только в поток SUCCESS.

Примеры:

Пример 1: Перенаправление ошибок и вывод в файл

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

В этом примере dir запускается для двух элементов, один из который завершится успешно, а для другого — с ошибкой.

Он использует «2>&1» для перенаправления потока ERROR в поток SUCCESS и «>» для отправки результирующего потока SUCCESS в файл с именем dir.log.

Пример 2: Отправить все данные потока SUCCESS в файл

.\script.ps1 > script.log

Эта команда отправляет все данные потока SUCCESS в файл с именем script.log.

Пример 3. Отправка потоков Success, Warning и Error в файл

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

В этом примере показано, как можно комбинировать операторы перенаправления для достижения желаемого результата.

• 3>&1 перенаправляет поток WARNING в поток SUCCESS.
• 2>&1 перенаправляет поток ERROR в поток SUCCESS (который теперь также включает все данные потока WARNING)
• > перенаправляет поток SUCCESS (который теперь содержит потоки WARNING и ERROR) в файл с именем C:\temp\redirection.log)

Пример 4: Перенаправить все потоки в файл

.\script.ps1 *> script.log

В этом примере все потоки выводятся из сценария с именем script.ps1 в файл с именем script.log.

Пример 5: Подавить все данные Write-Host и Information Stream

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

В этом примере подавляются все данные Information Stream (информационного потока). Дополнительные сведения о командлетах потока INFORMATION смотрите разделах Write-Host и Write-Information.

Смотрите также: Аналог echo в PowerShell

Примечания:

1. Операторы перенаправления, которые не добавляют данные (> и n>), перезаписывают текущее содержимое указанного файла без предупреждения.

2. Однако, если файл доступен только для чтения, является скрытым или системным файлом, перенаправление ТЕРПИТ НЕУДАЧУ. Операторы перенаправления добавления (>> и n>>) не записывают в файл, доступный только для чтения, но они добавляют содержимое в системный или скрытый файл.

3. Чтобы принудительно перенаправить содержимое в доступный только для чтения, скрытый или системный файл, используйте командлет Out-File с его параметром -Force.

4. Когда вы пишете в файлы, операторы перенаправления используют кодировку Unicode. Если файл имеет другую кодировку, выходные данные могут быть отформатированы неправильно. Чтобы перенаправить содержимое в файлы, отличные от Unicode, используйте командлет Out-File с его параметром -Encoding.

5. Возможная путаница с операторами сравнения

Оператор «>» не следует путать с оператором сравнения Больше (часто обозначается как «>» в других языках программирования).

В зависимости от сравниваемых объектов вывод с использованием «>» может показаться правильным (поскольку 36 не больше 42).

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

Однако проверка локальной файловой системы позволяет увидеть, что был создан файл с именем 42, а в него записано содержимое 36.

dir

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

    cat 42
    36

Попытка использовать обратное сравнение «<» (меньше чем) приводит к системной ошибке:

if (36 < 42) { "true" } else { "false" }
    At line:1 char:8
    + if (36 < 42) { "true" } else { "false" }
    +        ~
    The '<' operator is reserved for future use.
    + CategoryInfo          : ParserError: (:) [], ParentContainsErrorRecordException
    + FullyQualifiedErrorId : RedirectionNotSupported

Если требуется числовое сравнение, следует использовать -lt и -gt.

Смотрите также: Операторы сравнения в PowerShell

Как в PowerShell дописать вывод в файл

Итак, оператор «>» перенаправляет вывод, который в противном случае попал бы на экран, в файл. Этот оператор полностью переписывает файл, если он уже существует.

Для того, чтобы вместо замены содержимого файла дописать в него, можно использовать оператор «>>»:

Get-Help about_Comparison_Operators -Full >> man.txt

Командлет Out-File для сохранение в файл в PowerShell

Командлет Out-File отправляет вывод в файл. Когда вам нужно указать параметры для вывода, используйте Out-File вместо оператора перенаправления («>»).

Как дописать файл. Аналог «>>» в Out-File

Для того, чтобы добавить вывод в конец существующего файла (вместо его перезаписи), используйте в вашей команде опцию -Append.

Как указать кодировку

Для изменения кодировки по умолчанию, используйте опцию «-Encoding КОДИРОВКА». Кодировкой по умолчанию является UTF8NoBOM.

Опция -Encoding задаёт тип кодировки для целевого файла. Значение по умолчанию — UTF8NoBOM. Кодировка — это динамический параметр, который поставщик FileSystem добавляет в Set-Content. Этот параметр работает только на дисках с файловой системой. Допустимые значения этого параметра следующие:

• ASCII: использует кодировку для набора символов ASCII (7-бит).
• BigEndianUnicode: кодирует в формате UTF-16, используя порядок байтов с прямым порядком байтов.
• OEM: использует кодировку по умолчанию для MS-DOS и консольных программ.
• Unicode: кодируется в формате UTF-16 с использованием порядка байтов с прямым порядком байтов.
• UTF7: кодирует в формате UTF-7.
• UTF8: кодирует в формате UTF-8.
• UTF8BOM: кодирует в формате UTF-8 с меткой порядка байтов (BOM)
• UTF8NoBOM: кодирует в формате UTF-8 без метки порядка байтов (BOM)
• UTF32: кодирует в формате UTF-32.

Начиная с PowerShell 6.2, параметр -Encoding также позволяет использовать числовые идентификаторы зарегистрированных кодовых страниц (например, «-Encoding 1251») или строковые имена зарегистрированных кодовых страниц (например, «-Encoding «windows-1251»».

Как указать путь до файла

Обязательным аргументом командлета Out-File является путь до файла в который будет сделано сохранение выводимых данных. Вы можете указать его с опцией -FilePath, либо опустить эту опцию и указать путь до файла без неё.

Обратите внимание, что вы не можете использовать подстановочные знаки в пути до файла.

Смотрите также: Подстановочные символы в PowerShell

Как переписать файл только для чтения

С помощью опции -Force вы можете переопределить атрибут только для чтения и перезаписать существующий файл, доступный только для чтения. Параметр -Force не отменяет ограничения безопасности, то есть если у вас нет прав на записи в указываемый файл, то вы всё равно не сможете записать в него..

Как не добавлять символ новой строки (newline) в конец файла

При записи в файл, в конец будет добавлен символ перехода на новую строку. То есть если в файл будут добавлены другие данные, то они будут записаны с новой строки. Если вы не хотите, чтобы добавлялся символ новой строки, то используйте опцию -NoNewline. Если для формирования вывода используется несколько строк, то по умолчанию они разделяются пробелом, эта опция также отменяет вставку пробелов между строк.

Как запретить перезаписывать существующий файл

Опция -NoClobber предотвращает перезапись существующего файла и отображает сообщение о том, что файл уже существует. По умолчанию, если файл существует по указанному пути, Out-File перезаписывает файл без предупреждения.

Что может быть вводом командлета Out-File

В Out-File вы можете отправить по конвейеру любые объекты, а не только строки (как например в Set-Content и Add-Content). Например, следующая команда сохраняет практически пустой файл:

Get-ComputerInfo | Set-Content test3.txt

Но с помощью Out-File весь вывод будет сохранён в файл:

Get-ComputerInfo | Out-File test4.txt

Командлеты типа Out- не форматируют объекты; они просто визуализируют их и отправляют в указанное место отображения. Если вы отправляете неформатированный объект командлету Out-, этот командлет отправляет его командлету форматирования перед его визуализацией.

Чтобы отправить вывод команды PowerShell командлету Out-File, используйте конвейер. Вы можете хранить данные в переменной и использовать параметр -InputObject для передачи данных в командлет Out-File.

Out-File отправляет данные, но не создаёт никаких объектов вывода. Если вы направите вывод Out-File в Get-Member, командлет Get-Member сообщает, что объекты не были указаны.

Пример 1: Отправить вывод и создать файл

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

Командлет Get-Process получает список процессов, запущенных на локальном компьютере. Объекты Process отправляются по конвейеру в командлет Out-File. Затем Out-File использует параметр -FilePath и создаёт файл с именем Process.txt в текущем каталоге. Команда Get-Content получает содержимое из файла и отображает его в консоли PowerShell.

Пример 2: Предотвратить перезапись существующего файла

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
    +               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Командлет Get-Process получает список процессов, запущенных на локальном компьютере. Объекты Process отправляются по конвейеру в командлет Out-File. Затем Out-File использует параметр -FilePath и пытается выполнить запись в файл в текущем каталоге с именем Process.txt. Параметр -NoClobber предотвращает перезапись файла и отображает сообщение о том, что файл уже существует.

Пример 3: Сохранение вывода в файл в кодировке ASCII

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

Командлет Get-Process получает список процессов, запущенных на локальном компьютере. Объекты процесса хранятся в переменной $Procs. Затем Out-File использует параметр -FilePath и создаёт файл с именем Process.txt в текущем каталоге. Параметр -InputObject передаёт объекты с процессами из $Procs в файл Process.txt. Параметр -Encoding преобразует вывод в формат ASCII. Параметр -Width ограничивает каждую строку в файле 50 символами, поэтому некоторые данные могут быть усечены.

Пример 4: Использование провайдера и отправка вывода в файл

Set-Location -Path Alias:
    
Get-Location
    
    Path
    ----
    Alias:\
    
Get-ChildItem | Out-File -FilePath C:\TestDir\AliasNames.txt
    
Get-Content -Path C:\TestDir\AliasNames.txt
    
    CommandType     Name
    -----------     ----
    Alias           % -> ForEach-Object
    Alias           ? -> Where-Object
    Alias           ac -> Add-Content
    Alias           cat -> Get-Content

Команда Set-Location использует параметр -Path для установки текущего местоположения провайдера реестра «Alias:». Командлет Get-Location отображает полный путь к «Alias:». Get-ChildItem отправляет объекты по конвейеру командлету Out-File. Out-File использует параметр -FilePath, чтобы указать полный путь и имя файла для вывода, C:\TestDir\AliasNames.txt. Командлет Get-Content использует параметр -Path и отображает содержимое файла в консоли PowerShell.

PowerShell has several redirection operators that can be used to redirect specific type of output to a file. For example, if you want to redirect all errors produced by different cmdlet in your script to a text file, you can use Error redirection to do so.

It is particularly helpful when you want to hide errors from appearing on the screen but need them to identify any possible issues and improving the script. Sometimes, when you have a script deployed in production, you can ask users (who are using your script) for the error redirection file to troubleshoot the script.

To send errors to specified file, use 2> file.name

To append errors to a specified file, use 2>> file.name

Following examples attempts to delete files from c:\temp folder and redirects any errors to c:\errors.txt file.

PS C:\> Get-ChildItem -Path c:\temp

Directory: C:\temp

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
-a---         4/24/2016   2:45 PM        972 errors.txt
-a---         4/24/2016   2:48 PM      21085 ex2.docx
-a---         4/24/2016   2:49 PM        274 test.txt
-a---         4/24/2016   2:47 PM       8008 test.xlsx
-a---         4/24/2016   2:49 PM        289 test2.ps1

PS C:\> Get-ChildItem -Path C:\temp | Remove-Item 2> C:\errors.txt
PS C:\>

If above command has not resulted in any error, you will not see c:\errors.txt or anything in the file. if the command produced any errors, it will be there in the error file. In example above, two documents were open and they were not deleted. notice how errors were not shown on the console but they were redirected to given error file:

PS C:\> get-content C:\errors.txt
Remove-Item : Cannot remove item C:\temp\ex2.docx: The process cannot access the file 'C:\temp\ex2.docx' because it is being used by another
process.
At line:1 char:31
+ Get-ChildItem -Path C:\temp | Remove-Item 2> c:\errors.txt
+                               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo          : WriteError: (C:\temp\ex2.docx:FileInfo) [Remove-Item], IOException
+ FullyQualifiedErrorId : RemoveFileSystemItemIOError,Microsoft.PowerShell.Commands.RemoveItemCommand
Remove-Item : Cannot remove item C:\temp\test.xlsx: The process cannot access the file 'C:\temp\test.xlsx' because it is being used by
another process.
At line:1 char:31
+ Get-ChildItem -Path C:\temp | Remove-Item 2> c:\errors.txt
+                               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo          : WriteError: (C:\temp\test.xlsx:FileInfo) [Remove-Item], IOException
+ FullyQualifiedErrorId : RemoveFileSystemItemIOError,Microsoft.PowerShell.Commands.RemoveItemCommand
PS C:\> Get-ChildItem C:\temp

Notice that the error message redirected to the file is same as you would see on the console when not handling (by means of  -ErrorAction, Try/Catch etc.). It shows line number that has thrown the error and helps in troubleshooting the script/code.

2> c:\errors.txt in Remove-Item cmdlet in the pipeline is used to direct the errors to given text file (here c:\errors.txt). If you need to append to a file instead of overwriting/creating a new one (2> c:\errors.txt creates the file if does not exist or overwrites it if it exist), use append operator (2>> c:\errors.txt):

PS C:\> Get-ChildItem -Path C:\temp | Remove-Item 2>> c:\errors.txt

One important point to note is, you shouldn’t always be just redirecting errors. There are times when you need to handle errors in a script and take appropriate action. In those cases, its better to use error handling (using try/catch, -ErrorAction parameter of supported cmdlets etc.) to handle the error appropriately.

Note:

• This answer is about writing to stderr from the perspective of the outside world when a PowerShell script is called from there; while the answer is written from the perspective of the Windows shell, cmd.exe, it equally applies to Unix shells such as bash when combined with PowerShell Core.

• By contrast, from within Powershell, you should use Write-Error, as explained in Keith Hill’s answer.

• Sadly, there is no unified approach that will work from both within PowerShell and from the outside — see this answer of mine for a discussion.

---

To add to @Chris Sear’s great answer:

While $host.ui.WriteErrorLine should work in all hosts, it doesn’t (by default) write to stderr when invoked via cmd.exe, such as from a batch file.
[Console]::Error.WriteLine, by contrast, always does.

So if you want to write a PowerShell script that plays nicely in terms of output streams when invoked from cmd.exe, use the following function, Write-StdErr, which uses [Console]::Error.WriteLine
in the regular PS / cmd.exe host (console window), and $host.ui.WriteErrorLine otherwise:

<#
.SYNOPSIS
Writes text to stderr when running in a regular console window,
to the host''s error stream otherwise.

.DESCRIPTION
Writing to true stderr allows you to write a well-behaved CLI
as a PS script that can be invoked from a batch file, for instance.

Note that PS by default sends ALL its streams to *stdout* when invoked from
cmd.exe.

This function acts similarly to Write-Host in that it simply calls
.ToString() on its input; to get the default output format, invoke
it via a pipeline and precede with Out-String.

#>
function Write-StdErr {
  param ([PSObject] $InputObject)
  $outFunc = if ($Host.Name -eq 'ConsoleHost') {
    [Console]::Error.WriteLine
  } else {
    $host.ui.WriteErrorLine
  }
  if ($InputObject) {
    [void] $outFunc.Invoke($InputObject.ToString())
  } else {
    [string[]] $lines = @()
    $Input | % { $lines += $_.ToString() }
    [void] $outFunc.Invoke($lines -join "`r`n")
  }
}

---

Optional background information: How the PowerShell CLI’s output streams are seen by outside callers:

Internally, PowerShell has more than the traditional output streams (stdout and stderr), and their count has increased over time (try Write-Warning "I'll go unheard." 3> $null as an example, and read more at Get-Help about_Redirection.

When interfacing with the outside world, PowerShell must map the non-traditional output streams to stdout and stderr.

Strangely, however, PowerShell by default sends all its streams (including Write-Host and $host.ui.WriteErrorLine() output) to stdout when invoked from cmd.exe, even though mapping PowerShell’s error stream to stderr would be the logical choice. This behavior has been in effect since (at least) v2 and still applies as of v5.1 (and probably won’t change for reasons of backward compatibility — see GitHub issue #7989).

You can verify this with the following command, if you invoke it from cmd.exe:

powershell -noprofile -command "'out'; Write-Error 'err'; Write-Warning 'warn'; Write-Verbose -Verbose 'verbose'; $DebugPreference='Continue'; write-debug 'debug'; $InformationPreference='Continue'; Write-Information 'info'; Write-Host 'host'; $host.ui.WriteErrorLine('uierr'); [Console]::Error.WriteLine('cerr')" >NUL

The command writes to all PowerShell output streams (when you run on a pre-PowerShell-v5 version, you’ll see an additional error message relating to Write-Information, which was introduced in PowerShell v5) and has cmd.exe redirect stdout only to NUL (i.e., suppress stdout output; >NUL).

You will see no output except cerr (from [Console]::Error.WriteLine(), which writes directly to stderr) — all of PowerShell’s streams were sent to stdout.

Perhaps even more strangely, it is possible to capture PowerShell’s error stream, but only with a redirection:

If you change >NUL to 2>NUL above, it is exclusively PowerShell’s error stream and $host.ui.WriteErrorLine() output that will be suppressed; of course, as with any redirection, you can alternatively send it to a file.
(As stated, [Console]::Error.WriteLine()] always outputs to stderr, whether the latter is redirected or not.)

To give a more focused example (again, run from cmd.exe):

powershell -noprofile -command "'out'; Write-Error 'err'" 2>NUL

The above only outputs out — Write-Error‘s output is suppressed.

To summarize:

• Without any (cmd.exe) redirection or with only a stdout redirection (>... or 1>...), PowerShell sends all its output streams to stdout.

• With a stderr redirection (2>...), PowerShell selectively sends its error stream to stderr (irrespective of whether stdout is also redirected or not).

• As a corollary, the following common idiom does not work as expected:
  
  powershell ... >data-output.txt
  This will not, as one might expect, send only stdout to file data-output.txt while printing stderr output to the terminal; instead, you’d have to use
  
  powershell ... >data-output.txt 2>err-output.tmp; type err-output.tmp >&2; del err-output.tmp

It follows that PowerShell is aware of cmd.exe‘s redirections and adjusts its behavior intentionally.
(This is also evident from PowerShell producing colored output in the cmd.exe console while stripping the color codes when output is redirected to a file.)