Windows powershell error codes



Отчеты об ошибках командлетов

Командлеты должны сообщать об ошибках по-разному в зависимости от того, завершаются ли ошибки ошибками или неустранимыми ошибками. Завершающие ошибки — это ошибки, вызывающие немедленное завершение конвейера, или ошибки, возникающие, если нет причин продолжать обработку. Неустранимые ошибки — это ошибки, сообщающие о текущем состоянии ошибки, но командлет может продолжать обрабатывать входные объекты. В случае неустранимых ошибок пользователь обычно получает извещение о проблеме, но командлет продолжит обрабатывать следующий входной объект.

Завершение и неустранимые ошибки

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

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

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

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

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

Командлеты могут получать любое количество входных объектов и отправлять любое количество объектов 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 категоривиев.

Источник

Записи об ошибках Windows PowerShell

Командлеты должны передавать объект System. Management. Automation. ерроррекорд , который определяет условие ошибки для завершающих и устранимых ошибок.

  • Исключение, описывающее ошибку. Часто это исключение, которое командлет перехватывает и преобразует в запись об ошибке. Каждая запись об ошибке должна содержать исключение.
Читайте также:  Eclipse fatal error no input files

Если командлет не перехватывает исключение, он должен создать новое исключение и выбрать класс исключения, который наилучшим образом описывает условие ошибки. Однако исключение не требуется, так как доступ к нему можно получить с помощью свойства System. Management. Automation. ерроррекорд. Exception объекта System. Management. Automation. ерроррекорд .

идентификатор ошибки, предоставляющий целевой указатель, который может использоваться в целях диагностики, а также скрипты Windows PowerShell для обработки определенных условий ошибок с определенными обработчиками ошибок. Каждая запись об ошибке должна содержать идентификатор ошибки (см. Идентификатор ошибки).

Категория ошибок, которая предоставляет общее обозначение, которое можно использовать в целях диагностики. Каждая запись об ошибке должна указывать категорию ошибок (см. раздел Категория ошибок).

Необязательное сообщение об ошибке замены и рекомендуемое действие (см. сообщение об ошибке замены).

Дополнительные сведения о вызове командлета, вызвавшего ошибку. эти сведения задаются Windows PowerShell (см. сообщение о вызове).

Целевой объект, который был обработан при возникновении ошибки. Это может быть входной объект или другой объект, обрабатываемый командлетом. Например, для команды remove-item -recurse c:\somedirectory ошибка может быть экземпляром объекта FileInfo для «к:\сомедиректори\локкедфиле». Сведения о целевом объекте являются необязательными.

Идентификатор ошибки

При создании записи об ошибке укажите идентификатор, обозначающий условие ошибки в командлете. Windows PowerShell объединяет целевой идентификатор с именем командлета, чтобы создать полный идентификатор ошибки. Полный идентификатор ошибки можно получить с помощью свойства System. Management. Automation. ерроррекорд. фулликуалифиедеррорид объекта System. Management. Automation. ерроррекорд . Идентификатор ошибки недоступен для самого себя. Он доступен только в составе полного идентификатора ошибки.

При создании записей об ошибках следуйте приведенным ниже рекомендациям по созданию идентификаторов ошибок.

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

В общем случае назначьте разные идентификаторы ошибок разным путям кода. Преимущества конечных пользователей от конкретных идентификаторов. Часто каждый путь кода, вызывающий System. Management. Automation. командлет. WriteError или System. Management. Automation. командлет. ThrowTerminatingError * , имеет свой собственный идентификатор. В качестве правила определите новый идентификатор при определении новой строки шаблона для сообщения об ошибке и наоборот. Не используйте сообщение об ошибке в качестве идентификатора.

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

Обычно конкретный идентификатор ошибки следует использовать только для исключений определенного типа CLR. Если тип исключения или тип целевого объекта изменяется, создайте и используйте новый идентификатор.

Выберите текст для идентификатора ошибки, который кратко соответствует ошибке, о которой вы сообщаете. используйте стандартные платформа .NET Framework соглашения об именовании и капитализации. Не используйте пробелы или знаки препинания. Не следует локализовать идентификаторы ошибок.

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

Категория ошибки

При создании записи об ошибке укажите категорию ошибки с помощью одной из констант, определенных перечислением System. Management. Automation. ErrorCategory . Windows PowerShell использует категорию ошибок для вывода сведений об ошибках, когда пользователь присваивает $ErrorView переменной значение «CategoryView» .

Старайтесь не использовать константу System. Management. Automation. ErrorCategory NotSpecified . Если у вас есть какие-либо сведения об ошибке или об операции, вызвавшей ошибку, выберите категорию, которая лучше описывает ошибку или операцию, даже если категория не является идеальным соответствием.

сведения, отображаемые Windows PowerShell, называются строкой представления «категория» и формируются из свойств класса System. Management. Automation. ерроркатегоринфо . (Доступ к этому классу осуществляется через свойство Error System. Management. Automation. ерроррекорд. CategoryInfo .)

В следующем списке описаны отображаемые сведения.

Category: определенная Windows PowerShell константа System. Management. Automation. ErrorCategory .

TargetName: по умолчанию имя объекта, обрабатываемого командлетом при возникновении ошибки. Или другая строка, определяемая командлетом.

TargetType: по умолчанию это тип целевого объекта. Или другая строка, определяемая командлетом.

Действие: по умолчанию имя командлета, создавшего запись об ошибке. Или другая строка, определяемая командлетом.

Читайте также:  Error there is no attribute name

Причина: по умолчанию это тип исключения. Или другая строка, определяемая командлетом.

Сообщение об ошибке замены

При разработке записи об ошибке для командлета сообщение об ошибке по умолчанию поступает из текста сообщения по умолчанию в свойстве System. Exception. Message . это свойство только для чтения, текст сообщения которого предназначен только для целей отладки (в соответствии с рекомендациями платформа .NET Framework). Рекомендуется создать сообщение об ошибке, которое заменит или дополнит текст сообщения по умолчанию. Сделайте сообщение более понятным для пользователя и более конкретным для командлета.

Заменяющее сообщение предоставляется объектом System. Management. Automation. ErrorDetails . Используйте один из следующих конструкторов этого объекта, так как они предоставляют дополнительные сведения о локализации, которые могут использоваться Windows PowerShell.

ErrorDetails (командлет, строка, строка, объект []). Используйте этот конструктор, если строка шаблона является строкой ресурса в той же сборке, в которой реализуется командлет, или если требуется загрузить строку шаблона с помощью переопределения метода System. Management. Automation. командлета. жетресаурцестринг .

ErrorDetails (сборка, строка, строка, объект []): Используйте этот конструктор, если строка шаблона находится в другой сборке и вы не загрузили ее с помощью переопределения System. Management. Automation. командлета. жетресаурцестринг.

сообщение о замене должно соответствовать платформа .NET Framework правилам проектирования для написания сообщений об исключениях с небольшими различиями. Рекомендации о том, что сообщения об исключениях должны быть написаны для разработчиков. Эти замещающие сообщения должны быть написаны для пользователя командлета.

Сообщение об ошибке замены должно быть добавлено перед вызовом методов System. Management. Automation. командлет. WriteError или System. Management. Automation. командлета. ThrowTerminatingError * . Чтобы добавить заменяющее сообщение, задайте свойство System. Management. Automation. ерроррекорд. ErrorDetails записи об ошибке. если это свойство задано, Windows PowerShell отображает свойство System. Management. Automation. ErrorDetails. Message * вместо текста сообщения по умолчанию.

Рекомендуемые сведения о действии

Объект System. Management. Automation. ErrorDetails также может предоставлять сведения о том, какие действия рекомендуются при возникновении ошибки.

Сведения о вызове

если командлет использует system. management. automation. командлет. WriteError или system. management. automation. командлет. Throwterminatingerror * для сообщения о записи об ошибке, Windows PowerShell автоматически добавляет сведения, описывающие команду, которая была вызвана при возникновении ошибки. Эта информация предоставляется объектом System. Management. Automation. инвокатионинфо , который содержит имя командлета, который был вызван командой, самой командой, а также сведения о конвейере или скрипте. Это свойство доступно только для чтения.

Источник

Windows PowerShell Error Records

Cmdlets must pass an System.Management.Automation.ErrorRecord object that identifies the error condition for terminating and non-terminating errors.

The System.Management.Automation.ErrorRecord object contains the following information:

  • The exception that describes the error. Often, this is an exception that the cmdlet caught and converted into an error record. Every error record must contain an exception.

If the cmdlet did not catch an exception, it must create a new exception and choose the exception class that best describes the error condition. However, you do not need to throw the exception because it can be accessed through the System.Management.Automation.ErrorRecord.Exception property of the System.Management.Automation.ErrorRecord object.

An error identifier that provides a targeted designator that can be used for diagnostic purposes and by Windows PowerShell scripts to handle specific error conditions with specific error handlers. Every error record must contain an error identifier (see Error Identifier).

An error category that provides a general designator that can be used for diagnostic purposes. Every error record must specify an error category (see Error Category).

An optional replacement error message and a recommended action (see Replacement Error Message).

Optional invocation information about the cmdlet that threw the error. This information is specified by Windows PowerShell (see Invocation Message).

The target object that was being processed when the error occurred. This might be the input object, or it might be another object that your cmdlet was processing. For example, for the command remove-item -recurse c:\somedirectory , the error might be an instance of a FileInfo object for «c:\somedirectory\lockedfile». The target object information is optional.

Error Identifier

When you create an error record, specify an identifier that designates the error condition within your cmdlet. Windows PowerShell combines the targeted identifier with the name of your cmdlet to create a fully qualified error identifier. The fully qualified error identifier can be accessed through the System.Management.Automation.ErrorRecord.FullyQualifiedErrorId property of the System.Management.Automation.ErrorRecord object. The error identifier is not available by itself. It is available only as part of the fully qualified error identifier.

Читайте также:  Http error 503 the service is unavailable wsus

Use the following guidelines to generate error identifiers when you create error records:

Make error identifiers specific to an error condition. Target the error identifiers for diagnostic purposes and for scripts that handle specific error conditions with specific error handlers. A user should be able to use the error identifier to identify the error and its source. Error identifiers also enable reporting for specific error conditions from existing exceptions so that new exception subclasses are not required.

In general, assign different error identifiers to different code paths. The end-user benefits from specific identifiers. Often, each code path that calls System.Management.Automation.Cmdlet.WriteError or System.Management.Automation.Cmdlet.Throwterminatingerror* has its own identifier. As a rule, define a new identifier when you define a new template string for the error message, and vice-versa. Do not use the error message as an identifier.

When you publish code using a particular error identifier, you establish the semantics of errors with that identifier for your complete product support lifecycle. Do not reuse it in a context that is semantically different from the original context. If the semantics of this error change, create and then use a new identifier.

You should generally use a particular error identifier only for exceptions of a particular CLR type. If the type of the exception or the type of the target object changes, create and then use a new identifier.

Choose text for your error identifier that concisely corresponds to the error that you are reporting. Use standard .NET Framework naming and capitalization conventions. Do not use white space or punctuation. Do not localize error identifiers.

Do not dynamically generate error identifiers in a non-reproducible way. For example, do not incorporate error information such as a process ID. Error identifiers are useful only if they correspond to the error identifiers seen by other users who are experiencing the same error condition.

Error Category

When you create an error record, specify the category of the error using one of the constants defined by the System.Management.Automation.ErrorCategory enumeration. Windows PowerShell uses the error category to display error information when users set the $ErrorView variable to «CategoryView» .

Avoid using the System.Management.Automation.ErrorCategory NotSpecified constant. If you have any information about the error or about the operation that caused the error, choose the category that best describes the error or the operation, even if the category is not a perfect match.

The information displayed by Windows PowerShell is referred to as the category-view string and is built from the properties of the System.Management.Automation.Errorcategoryinfo class. (This class is accessed through the error System.Management.Automation.ErrorRecord.CategoryInfo property.)

The following list describes the information displayed:

TargetName: By default, the name of the object the cmdlet was processing when the error occurred. Or, another cmdlet-defined string.

TargetType: By default, the type of the target object. Or, another cmdlet-defined string.

Activity: By default, the name of the cmdlet that created the error record. Or, some other cmdlet-defined string.

Reason: By default, the exception type. Or, another cmdlet-defined string.

Replacement Error Message

When you develop an error record for a cmdlet, the default error message for the error comes from the default message text in the System.Exception.Message property. This is a read-only property whose message text is intended only for debugging purposes (according to the .NET Framework guidelines). We recommend that you create an error message that replaces or augments the default message text. Make the message more user-friendly and more specific to the cmdlet.

The replacement message is provided by an System.Management.Automation.ErrorDetails object. Use one of the following constructors of this object because they provide additional localization information that can be used by Windows PowerShell.

ErrorDetails(Cmdlet, String, String, Object[]): Use this constructor if your template string is a resource string in the same assembly in which the cmdlet is implemented or if you want to load the template string through an override of the System.Management.Automation.Cmdlet.GetResourceString method.

ErrorDetails(Assembly, String, String, Object[]): Use this constructor if the template string is in another assembly and you do not load it through an override of System.Management.Automation.Cmdlet.GetResourceString.

The replacement message should conform to the .NET Framework design guidelines for writing exception messages with a small difference. The guidelines state that exception messages should be written for developers. These replacement messages should be written for the cmdlet user.

Источник

Оцените статью
toolgir.ru
Adblock
detector