Поиск по сайту:

Write-Error (Microsoft.PowerShell.Utility)

Write-Error

Модуль:
Microsoft.PowerShell.Utility

Записывает объект в поток ошибок.

Синтаксис

Write-Error
     [-Message] <string>
     [-Category <ErrorCategory>]
     [-ErrorId <string>]
     [-TargetObject <Object>]
     [-RecommendedAction <string>]
     [-CategoryActivity <string>]
     [-CategoryReason <string>]
     [-CategoryTargetName <string>]
     [-CategoryTargetType <string>]
     [<CommonParameters>]
Write-Error
     [-Exception] <Exception>
     [-Message <string>]
     [-Category <ErrorCategory>]
     [-ErrorId <string>]
     [-TargetObject <Object>]
     [-RecommendedAction <string>]
     [-CategoryActivity <string>]
     [-CategoryReason <string>]
     [-CategoryTargetName <string>]
     [-CategoryTargetType <string>]
     [<CommonParameters>]
Write-Error
     [-ErrorRecord] <ErrorRecord>
     [-RecommendedAction <string>]
     [-CategoryActivity <string>]
     [-CategoryReason <string>]
     [-CategoryTargetName <string>]
     [-CategoryTargetType <string>]
     [<CommonParameters>]

Описание

Командлет Write-Error объявляет о непрерывающейся ошибке. По умолчанию ошибки отправляются в потоке ошибок в хост-программу для отображения вместе с выводом.

Чтобы записать непрерывную ошибку, введите строку сообщения об ошибке, объект ErrorRecord или объект Exception. Используйте другие параметры Write-Error, чтобы заполнить запись об ошибке.

Непрерывные ошибки записывают ошибку в поток ошибок, но не останавливают обработку команды. Если для одного элемента коллекции входных элементов объявлена непрерывная ошибка, команда продолжает обрабатывать другие элементы коллекции.

Чтобы объявить завершающую ошибку, используйте ключевое слово Throw. Дополнительные сведения см. в разделе about_Throw.

Примеры

Пример 1. Запись ошибки для объекта RegistryKey.

Get-ChildItem | ForEach-Object {
    if ($_.GetType().ToString() -eq "Microsoft.Win32.RegistryKey")
    {
        Write-Error "Invalid object" -ErrorId B1 -TargetObject $_
    }
    else
    {
        $_
    }
}

Эта команда объявляет непрерывную ошибку, когда командлет Get-ChildItem возвращает объект Microsoft.Win32.RegistryKey, например объекты в HKLM: или HKCU: диски поставщика реестра PowerShell.

Пример 2. Вывод сообщения об ошибке в консоль

Write-Error "Access denied."

Эта команда объявляет непрерывную ошибку и пишет ошибку «Доступ запрещен». Команда использует параметр Message для указания сообщения, но опускает необязательное имя параметра Message.

Пример 3: Выводим ошибку в консоль и указываем категорию

Write-Error -Message "Error: Too many input values." -Category InvalidArgument

Эта команда объявляет непрерывную ошибку и указывает категорию ошибки.

Пример 4. Запись ошибки с использованием объекта Exception

$E = [System.Exception]@{Source="Get-ParameterNames.ps1";HelpLink="https://go.microsoft.com/fwlink/?LinkID=113425"}
Write-Error -Exception $E -Message "Files not found. The $Files location doesn't contain any XML files."

Эта команда использует объект Exception для объявления непрерывающейся ошибки.

Первая команда использует хеш-таблицу для создания объекта System.Exception. Он сохраняет объект исключения в переменной $E. Вы можете использовать хеш-таблицу для создания любого объекта типа, имеющего пустой конструктор.

Вторая команда использует командлет Write-Error для объявления непрерывающейся ошибки. Значением параметра Exception является объект Exception в переменной $E.

Параметры

-Category

Указывает категорию ошибки. Значение по умолчанию — NotSpecified. Допустимые значения этого параметра:

  • NotSpecified
  • OpenError
  • CloseError
  • DeviceError
  • DeadlockDetected
  • InvalidArgument
  • InvalidData
  • InvalidOperation
  • InvalidResult
  • InvalidType
  • MetadataError
  • NotImplemented
  • NotInstalled
  • Объектнотфаунд
  • OperationStopped
  • OperationTimeout
  • SyntaxError
  • ParserError
  • PermissionDenied
  • ResourceBusy
  • ResourceExists
  • ResourceUnavailable
  • ReadError
  • WriteError
  • Фромстдерр
  • SecurityError
  • ProtocolError
  • ConnectionError
  • AuthenticationError
  • LimitsExceeded
  • QuotaExceeded
  • NotEnabled

Сведения о категориях ошибок см. в разделе Перечисление ErrorCategory.

Тип :

ErrorCategory

Принятые значения:

NotSpecified, OpenError, CloseError, DeviceError, DeadlockDetected, InvalidArgument, InvalidData, InvalidOperation, InvalidResult, InvalidType, MetadataError, NotImplemented, NotInstalled, ObjectNotFound, OperationStopped, OperationTimeout, SyntaxError, ParserError, PermissionDenied, ResourceBusy, ResourceExists, ResourceUnavailable, ReadError, WriteError, FromStdErr , SecurityError, ProtocolError, ConnectionError, AuthenticationError, LimitsExceeded, QuotaExceeded, NotEnabled

Позиция:

Именованный

Значение по умолчанию:

NotSpecified

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-CategoryActivity

Указывает действие, вызвавшее ошибку.

Тип :

String

Псевдонимы:

Activity

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-CategoryReason

Указывает, как и почему действие вызвало ошибку.

Тип :

String

Псевдонимы:

Reason

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-CategoryTargetName

Указывает имя объекта, который обрабатывался в момент возникновения ошибки.

Тип :

String

Псевдонимы:

TargetName

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-CategoryTargetType

Указывает тип объекта, который обрабатывался в момент возникновения ошибки.

Тип :

String

Псевдонимы:

TargetType

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-ErrorId

Указывает строку идентификатора для идентификации ошибки. Строка должна быть уникальной для ошибки.

Тип :

String

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-ErrorRecord

Указывает объект записи ошибки, представляющий ошибку. Используйте свойства объекта для описания ошибки.

Чтобы создать объект записи ошибки, используйте командлет New-Object или получите объект записи ошибки из массива в автоматической переменной $Error.

Тип :

ErrorRecord

Позиция:

0

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-Exception

Указывает объект исключения, представляющий ошибку. Используйте свойства объекта для описания ошибки.

Чтобы создать объект исключения, используйте хеш-таблицу или командлет New-Object.

Тип :

Исключение

Позиция:

0

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-Message

Указывает текст сообщения об ошибке. Если текст содержит пробелы или специальные символы, заключите его в кавычки. Вы также можете передать строку сообщения в Write-Error.

Тип :

String

Псевдонимы:

Msg

Позиция:

0

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

True

Принимайте подстановочные знаки:

False

-RecommendedAction

Указывает действие, которое должен предпринять пользователь для устранения или предотвращения ошибки.

Тип :

String

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-TargetObject

Указывает объект, который обрабатывался в момент возникновения ошибки. Введите объект, переменную, содержащую объект, или команду, получающую объект.

Тип :

Объект

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

Входы

Строка

В этот командлет можно передать строку, содержащую сообщение об ошибке.

Выходы

Нет

Этот командлет не возвращает никаких результатов. Он записывает только в поток сообщений об ошибках.

Примечания

Write-Error не меняет значение автоматической переменной $?, поэтому не сигнализирует о завершающей ошибке. Чтобы сигнализировать о завершающей ошибке, используйте метод $PSCmdlet.WriteError().