Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Командлеты должны сообщать об ошибках по-разному в зависимости от того, завершаются ли ошибки ошибками или неустранимыми ошибками. Завершающие ошибки — это ошибки, вызывающие немедленное завершение конвейера, или ошибки, возникающие, если нет причин продолжать обработку. Неустранимые ошибки — это ошибки, сообщающие о текущем состоянии ошибки, но командлет может продолжать обрабатывать входные объекты. В случае неустранимых ошибок пользователь обычно получает извещение о проблеме, но командлет продолжит обрабатывать следующий входной объект.
Завершение и неустранимые ошибки
Чтобы определить, является ли условие ошибки завершающим ошибкой или неустранимой ошибкой, можно использовать следующие рекомендации.
Не мешает ли командлету успешно обрабатывать любые дальнейшие входные объекты? Если это так, это Неустранимая ошибка.
Условие ошибки, связанное с определенным входным объектом или подмножеством входных объектов? Если да, это Неустранимая ошибка.
Принимает ли командлет несколько входных объектов, что может привести к успешности обработки другого входного объекта? Если да, это Неустранимая ошибка.
Командлеты, которые могут принимать несколько входных объектов, должны определить, какие из них завершаются, а какие — нет, даже если конкретная ситуация относится только к одному входному объекту.
Командлеты могут получать любое количество входных объектов и отправлять любое количество объектов Success или Error перед вызовом завершающего исключения. Между числом полученных входных объектов и количеством отправленных объектов Success и Error не связано никаких отношений.
Командлеты, которые могут принимать только 0-1 входных объектов и создавать только объекты вывода 0-1, должны обрабатывать ошибки как прерывающие работу и создавать завершающие исключения.
Сообщает о неустранимых ошибках
Отчеты о незавершающей ошибке всегда должны быть выполнены в реализации командлета метода System. Management. Automation. командлет. BeginProcessing , метода System. Management. Automation. командлет. ProcessRecord или метода System. Management. Automation. командлет. EndProcessing . Эти типы ошибок выводятся путем вызова метода System. Management. Automation. командлета. WriteError , который, в свою очередь, отправляет запись об ошибке в поток ошибок.
Создание отчетов о прекращении ошибок
Для завершения ошибок выдаются исключения или вызывается метод System. Management. Automation. командлет. ThrowTerminatingError . Имейте в виду, что командлеты также могут перехватывать и воссоздавать исключения, такие как OutOfMemory, однако они не требуют повторных порождения исключений, так как среда выполнения PowerShell также будет перехватывать их.
Можно также определить собственные исключения для проблем, характерных для конкретной ситуации, или добавить дополнительные сведения к существующему исключению с помощью записи об ошибке.
Записи об ошибках
PowerShell описывает неустранимую ошибку в объектах System. Management. Automation. ерроррекорд . Каждый объект предоставляет сведения о категории ошибок, дополнительный целевой объект и сведения о состоянии ошибки.
Идентификаторы ошибок
Идентификатор ошибки представляет собой простую строку, определяющую условие ошибки в командлете. PowerShell объединяет этот идентификатор с идентификатором командлета, чтобы создать полный идентификатор ошибки, который можно использовать позже при фильтрации потоков ошибок или ошибок ведения журнала, при ответе на определенные ошибки или с другими действиями, специфичными для пользователя.
При указании идентификаторов ошибок следует следовать приведенным ниже рекомендациям.
Присвойте разные идентификаторы ошибок различным путям кода. Каждый путь кода, вызывающий System. Management. Automation. командлет. WriteError или System. Management. Automation. командлет. ThrowTerminatingError , должен иметь собственный идентификатор ошибки.
Идентификаторы ошибок должны быть уникальными для типов исключений среды CLR как для завершающих, так и для неустранимых ошибок.
Не меняйте семантику идентификатора ошибки между версиями командлета или поставщика PowerShell. После установки семантики идентификатора ошибки она должна оставаться постоянной в течение жизненного цикла командлета.
Для завершения ошибок используйте уникальный идентификатор ошибки для конкретного типа исключения CLR. Если тип исключения изменяется, используйте новый идентификатор ошибки.
Для неустранимых ошибок используйте конкретный идентификатор ошибки для конкретного входного объекта.
Выберите текст для идентификатора, который кратко соответствует сообщению об ошибке. Не используйте пробелы или знаки препинания.
Не создавайте идентификаторы ошибок, которые не воспроизводимы. Например, не создавайте идентификаторы, включающие идентификатор процесса. Идентификаторы ошибок полезны только в том случае, если они соответствуют идентификаторам, которые видят другие пользователи, испытывающие одну и ту же проблему.
Категории ошибок
Категории ошибок используются для группирования ошибок пользователя. PowerShell определяет эти категории и командлеты, и поставщики PowerShell должны выбирать между ними при создании записи об ошибке.
Описание доступных категорий ошибок см. в описании перечисления System. Management. Automation. ErrorCategory . В общем случае следует избегать использования ошибок, ундефинедеррор и Общая ошибка везде, где это возможно.
Пользователи могут просматривать ошибки на основе категории, если для них задано значение $ErrorView категоривиев.