Поделиться через

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

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

Объект System. Management. Automation. ерроррекорд содержит следующие сведения:

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

Если командлет не перехватывает исключение, он должен создать новое исключение и выбрать класс исключения, который наилучшим образом описывает условие ошибки. Однако исключение не требуется, так как доступ к нему можно получить с помощью свойства 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}: ({TargetName}:{TargetType}):[{Activity}], {Reason}

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

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

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

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

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

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

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

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

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

сообщение о замене должно соответствовать платформа .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. инвокатионинфо , который содержит имя командлета, который был вызван командой, самой командой, а также сведения о конвейере или скрипте. Это свойство доступно только для чтения.

См. также:

System. Management. Automation. командлет. WriteError

System. Management. Automation. командлет. ThrowTerminatingError *

System. Management. Automation. ErrorCategory

System. Management. Automation. Ерроркатегоринфо

System. Management. Automation. Ерроррекорд

System. Management. Automation. ErrorDetails

System. Management. Automation. Инвокатионинфо

Отчеты об ошибках Windows PowerShell

Запись командлета Windows PowerShell

  • Last updated on