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 используют следующие числа для представления доступных выходных потоков:

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

Ниже перечислены операторы перенаправления PowerShell, где n представляет номер потока. Поток SUCCESS (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:Tempredirection.log

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

• 3>&1 перенаправляет поток WARNING в поток SUCCESS.
• 2>&1 перенаправляет поток ERROR в поток SUCCESS (который теперь также включает все данные потока WARNING)
• > перенаправляет поток SUCCESS (который теперь содержит потоки WARNING и ERROR) в файл с именем C:tempredirection.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:TestProcess.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:TestDirAliasNames.txt
    
Get-Content -Path C:TestDirAliasNames.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:TestDirAliasNames.txt. Командлет Get-Content использует параметр -Path и отображает содержимое файла в консоли PowerShell.

Всем привет.

Поехали.

1. Объект ErrorRecord и поток ошибок.

В PowerShell информация о возникающих ошибках записывается в поток ошибок, который по умолчанию отображается на экране, например:
PS C:> dir «C:Folder doesn’t exist»
Get-ChildItem : Не удается найти путь «C:Folder doesn’t exist»,
так как он не существует.
В строка:1 знак:4
+ dir <<<< «C:Folder doesn’t exist»

Поток ошибок можно перенаправить в текстовый файл с помощью специального оператора 2>, например:
PS C:> dir «C:Folder doesn’t exist» 2>err.txt

Проверим теперь содержимое файла err.txt:
PS C:> Get-Content err.txt
Get-ChildItem : Не удается найти путь «C:Folder doesn’t exist»,
так как он не существует.
В строка:1 знак:4
+ dir <<<< «Folder doesn’t exist» 2> err.txt
Как видите, в файл err.txt полностью записалось сообщение об ошибке, однако никакой дополнительной информации не появилось.

Где произошла ошибка смотрим так
PS C:> $err.InvocationInfo
MyCommand : Get-ChildItem
ScriptLineNumber : 1
OffsetInLine : -2147483648
ScriptName :
Line : $err = dir «C:Folder doesn’t exist» 2>&1
PositionMessage :
 В строка:1 знак:11
 + $err = dir <<<< «C:Folder doesn’t exist» 2>&1
InvocationName : dir
PipelineLength : 1
PipelinePosition : 1
Хотя этот вывод даст нам место скрипта(или непсредственного ввода)
где ошибку интепретирует сама PowerShell, истинное место проблемы надо будет
искать самим.

2. Специальная переменная $Error.

В PowerShell имеется специальная переменная $Error, которая содержит коллекцию (массив) объектов ErrorRecord, соответствующих ошибкам, возникавшим в текущем сеансе работы. Максимальное количество элементов в данной коллекции задается значением переменной $MaximumErrorCount (по умолчанию это 256):
PS C:> $MaximumErrorCount
256

После заполнения массива $Error объекты для вновь возникающих ошибок будут заменять объекты, соответствующие старым ошибкам. Возникновение каждой новой ошибки приводит к смещению элементов в массиве $Error: объект для последней ошибки хранится в первом элементе ($Error[0]), объект для предыдущей ошибки — во втором элементе ($Error[1]) и т. д.
Убедимся, что элемент $Error[0] имеет тип ErrorRecord, и выведем содержимое этого элемента:
PS C:> $Error[0].GetType().FullName
System.Management.Automation.ErrorRecord

PS C:> $Error[0]
Get-ChildItem : Не удается найти путь «C:Несуществующий каталог»,
так как он не существует.
В строка:1 знак:4
+ dir <<<< «Несуществующий каталог»
Естественно, мы можем обращаться ко всем свойствам объекта ErrorRecord:

PS C:> $Error[0].Exception
Не удается найти путь «C:Несуществующий каталог», так как он не существует.

Повторим вывод свойства InvocationInfo
PS C:> $Error[0].InvocationInfo
MyCommand : Get-ChildItem
ScriptLineNumber : 1
OffsetInLine : -2147483648
ScriptName :
Line : $err = dir «C:Folder doesn’t exist» 2>&1
PositionMessage :
 В строка:1 знак:11
 + $err = dir <<<< «C:Folder doesn’t exist» 2>&1
InvocationName : dir
PipelineLength : 1
PipelinePosition : 1

3. Мониторинг возникновения ошибки переменной $?.

В PowerShell имеется логическая переменная $?, которая равна $True, если последняя выполняемая операция завершена успешно, и $False, если во время выполнения последней
операции возникла ошибка. Такая же существует и в Linux.) Например, если выполнить командлет Get-Item для заведомо существующего каталога, то значение переменной $? будет равно $True:
PS C:> Get-Item С:
Каталог:
Mode LastWriteTime Length Name
—- ————- —— —-
d—hs 21.03.2016 12:00 C:

PS C:> $?
True

Если же выполнить этот же командлет для несуществующего каталога, то значение переменной $? будет равно $False:
PS C:> Get-Item С:321
Get-Item : Не удается найти путь «C:321», так как он не существует.
В строка:1 знак:9
Глава 9. Обработка ошибок и отладка 183
+ Get-Item <<<< С:321
PS C:> $?
False

4. Мониторинг возникновения ошибки по коду возврата.

Для внешних команд Windows и сценариев PowerShell определено понятие кода возврата (напомним, что для сценариев PowerShell этот код можно установить с помощью инструкции Exit). В операционной системе код возврата последней команды доступен через переменную среды %ERRORLEVEL%; в оболочке PowerShell данный код возврата хранится в специальной переменной $LASTEXITCODE. При этом, если код возврата равен нулю, то переменной $? присваивается значение $True. Если же код возврата не равен нулю, то считается, что при выполнении данной команды произошла ошибка, и переменной $? присваивается значение $False.

В качестве примера выполним команду интерпретатора cmd.exe, которая устанавливает нулевой код возврата. Для этого можно запустить cmd.exe с ключом /c (выполнить команду и завершить работу интерпретатора) и указать для исполнения команду exit 0:
PS C:> cmd /c exit 0

Проверим значения переменных $LASTEXITCODE и $?:
PS C:> $LASTEXITCODE
0
PS C:> $?
True
Теперь выполним команду интерпретатора cmd.exe с ненулевым кодом возврата (пусть, например, код возврата равен 10):
PS C:> cmd /c exit 10
Вновь проверим переменные $LASTEXITCODE и $?:
PS C:> $?
False
PS C:> $LASTEXITCODE
10

5. Командлет Set-PSDebug и точки прерывания.

Процесс поиска ошибок в сценариях неразрывно связан с отладкой. Поэтому нам стоит упомянуть что основным встроенным инструментом для отладки сценариев является командлет Set-PSDebug. Параметры этого командлета позволяют включить режимы трассировки и пошагового выполнения команд, а также режим обязательного объявления переменных:
-Trace 0 Отключение трассировки
-Trace 1 Включение основного режима трассировки
-Trace 2 Включение полного режима трассировки
-Step Включение режима пошагового выполнения
-Strict Включение режима обязательного объявления переменных
-Off Отключение всех механизмов отладки.

Примеры приводить не буду, назначение ключей очевидно из их названия. Самым интересным является режим пошагового выполнения -Step, который позволяет в любой момент вызвать вложенную командную строку для анализа или изменения состояния интерпретатора. Однако отлаживать более-менее большие сценарии с помощью данного метода часто оказывается неудобно, так как для запуска вложенного сеанса в определенной строке сценария придется каждый раз добираться до этой строки с самого начала сценария (каждую команду при этом
нужно выполнять, нажимая клавишу <A>).

Гораздо удобнее было бы использовать точки прерывания, позволяющие запускать сценарий в автоматическом режиме и приостанавливать выполнение на нужной команде. В PowerShell аналогом установки точки прерывания можно считать вызов метода $Host.EnterNestedPrompt(), например:
PS C:> for ($i=0; $i -lt 10; $i++) {
>> «i = $i»
>> if ($i -eq 5) {
>> «Моя точка прерывания»
>> $Host.EnterNestedPrompt()
>> }
>> }
>>
i = 0
i = 1
i = 2
i = 3
i = 4
i = 5
Моя точка прерывания
PS C:>>>

В данном примере на пятой итерации цикла выводится строка «Моя точка прерывания» и вызывается метод $Host.EnterNestedPrompt(). В результате выполнение цикла приостанавливается, и мы попадаем во вложенную командную строку (вид приглашения изменяется на >>>).

Выход из вложенного сеанса с помощью инструкции Exit:
PS C:>>> Exit
PS C:>

Вот так вот.

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:tempex2.docx: The process cannot access the file 'C:tempex2.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:tempex2.docx:FileInfo) [Remove-Item], IOException
+ FullyQualifiedErrorId : RemoveFileSystemItemIOError,Microsoft.PowerShell.Commands.RemoveItemCommand
Remove-Item : Cannot remove item C:temptest.xlsx: The process cannot access the file 'C:temptest.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:temptest.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.