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

Обязательные требования к разработке

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

В этом разделе

Рекомендации по проектированию

Рекомендации по коду

Рекомендации по проектированию

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

Использование только утвержденных команд (RD01)

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

Дополнительные сведения о утвержденных именах команд см. в командлетов.

Пользователям требуется набор обнаруженных и ожидаемых имен командлетов. Используйте соответствующую команду, чтобы пользователь смог быстро оценить, что делает командлет, и легко обнаружить возможности системы. Например, следующая команда командной строки получает список всех команд в системе, имена которых начинаются с "Пуск": Get-Command Start-*. Используйте существительные в командлетах, чтобы отличить командлеты от других командлетов. Существительное указывает ресурс, на котором будет выполнена операция. Сама операция представлена командой.

Имена командлетов: символы, которые нельзя использовать (RD02)

При имени командлетов не используйте следующие специальные символы.

Персонаж Имя
# знак числа
, запятая
() круглые скобки
{} фигурные скобки
[] скобками
& амперсанд
- дефис Примечание. Дефис можно использовать для разделения глагола от существительного, но его нельзя использовать в существительном или в пределах глагола.
/ Знак косой черты
\ обратная косая черта
$ знак доллара
^ каретка
; точка с запятой
: двоеточие
" двойная кавычка
' одинарный кавычки
<> угловые скобки
| вертикальная полоса
? вопросительный знак
@ при входе
` назад галочку (серьезный акцент)
* звездочка
% Знак процента
+ знак плюс
= знак равенства
~ тильда

Имена параметров, которые нельзя использовать (RD03)

Windows PowerShell предоставляет общий набор параметров для всех командлетов и дополнительных параметров, добавленных в определенных ситуациях. При разработке собственных командлетов нельзя использовать следующие имена: Подтверждение, Отладка, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, WarningVariable, WhatIf, UseTransaction и Подробные сведения. Дополнительные сведения об этих параметрах см. в общих имен параметров.

Запросы на подтверждение поддержки (RD04)

Для командлетов, которые изменяют систему, они должны вызывать метод System.Management.Automation.Cmdlet.ShouldProcess* для запроса подтверждения, а в особых случаях вызывает метод System.Management.Automation.Командлет.ShouldContinue*. (Метод System.Management.Automation.Cmdlet.ShouldContinue* должен вызываться только после вызова метода System.Management.Automation.Cmdlet.ShouldProcess*.).

Для выполнения этих вызовов командлету необходимо указать, что он поддерживает запросы на подтверждение, задав ключевое слово SupportsShouldProcess атрибута Командлета. Дополнительные сведения о настройке этого атрибута см. в объявлении атрибутов командлетов.

Примечание.

Если атрибут Командлета класса командлета указывает, что командлет поддерживает вызовы метода System.Management.Automation.Командлет.ShouldProcess*, и командлет не сможет выполнить вызов метода System.Management.Automation.Cmdlet.ShouldProcess*, пользователь может неожиданно изменить систему.

Используйте метод System.Management.Automation.Командлет.ShouldProcess* для любого изменения системы. Предпочтения пользователя и параметр WhatIf управляют методом System.Management.Automation.Cmdlet.ShouldProcess*. В отличие от этого, вызов System.Management.Automation.Командлет.ShouldContinue* выполняет дополнительную проверку потенциально опасных изменений. Этот метод не контролируется любым пользовательским предпочтениям или параметром WhatIf. Если командлет вызывает метод System.Management.Automation.Командлет.ShouldContinue*, он должен иметь параметр Force, который проходит вызовы этих двух методов и выполняет операцию. Это важно, так как он позволяет командлету использоваться в неинтерактивных скриптах и узлах.

Если командлеты поддерживают эти вызовы, пользователь может определить, следует ли выполнять действие. Например, командлет stop-Process вызывает метод System.Management.Automation.Cmdlet.ShouldContinue*, прежде чем остановить набор критически важных процессов, включая процессы System, Winlogon и Spoolsv.

Дополнительные сведения о поддержке этих методов см. в запроса подтверждения.

Параметр Force Force для интерактивных сеансов (RD05)

Если командлет используется в интерактивном режиме, всегда предоставьте параметр Force для переопределения интерактивных действий, таких как запросы или чтение строк входных данных). Это важно, так как он позволяет командлету использоваться в неинтерактивных скриптах и узлах. Следующие методы можно реализовать интерактивным узлом.

Объекты выходных данных документа (RD06)

Windows PowerShell использует объекты, записанные в конвейер. Чтобы пользователи использовали преимущества объектов, возвращаемых каждым командлетом, необходимо документировать возвращаемые объекты и документировать элементы возвращаемых объектов.

Рекомендации по коду

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

Производный от классов командлета или PSCmdlet (RC01)

Командлет должен быть производным от базового класса System.Management.Automation.Командлет или System.Management.Automation.PSCmdlet. Командлеты, производные от класса System.Management.Automation.Командлет, не зависят от среды выполнения Windows PowerShell. Их можно вызывать непосредственно из любого языка Microsoft .NET Framework. Командлеты, производные от класса System.Management.Automation.PSCmdlet, зависят от среды выполнения Windows PowerShell. Поэтому они выполняются в пространстве выполнения.

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

Укажите атрибут командлета (RC02)

Чтобы командлет распознался Windows PowerShell, его класс .NET Framework должен быть украшен атрибутом Командлета. Этот атрибут указывает следующие функции командлета.

  • Пара глаголов и существительных, идентифицирующая командлет.

  • Набор параметров по умолчанию, используемый при указании нескольких наборов параметров. Набор параметров по умолчанию используется, если в Windows PowerShell недостаточно сведений, чтобы определить, какой набор параметров используется.

  • Указывает, поддерживает ли командлет вызовы метода System.Management.Automation.Командлет.ShouldProcess*. Этот метод отображает сообщение подтверждения пользователю перед тем, как командлет вносит изменения в систему. Дополнительные сведения о том, как выполняются запросы на подтверждение, см. в запроса на подтверждение.

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

Дополнительные сведения о том, как объявить атрибут командлета, см. в объявлении КомандлетаAttribute.

Переопределите метод обработки входных данных (RC03)

Чтобы командлет участвовал в среде Windows PowerShell, он должен переопределить по крайней мере один из следующих методов обработки входных данных.

System.Management.Automation.Командлет.BeginProcessing Этот метод вызывается один раз и используется для предоставления функций предварительной обработки.

System.Management.Automation.Командлет.ProcessRecord Этот метод вызывается несколько раз и используется для предоставления функций записей по записи.

System.Management.Automation.Командлет.EndProcessing Этот метод вызывается один раз и используется для предоставления функций после обработки.

Укажите атрибут OutputType (RC04)

Атрибут OutputType (представленный в Windows PowerShell 2.0) указывает тип .NET Framework, который командлет возвращает в конвейер. Указав тип выходных данных командлетов, возвращаемых командлетом, более обнаруживаемыми другими командлетами. Дополнительные сведения о декорировании класса командлета с помощью этого атрибута см. в объявлении атрибута OutputType.

Не сохраняйте дескрипторы для выходных объектов (RC05)

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

Надежная обработка ошибок (RC06)

Среда администрирования по сути обнаруживает и вносит важные изменения в систему, которую вы администрируете. Поэтому очень важно, чтобы командлеты правильно обрабатывали ошибки. Дополнительные сведения об ошибках см. в отчета об ошибках Windows PowerShell.

  • Если ошибка предотвращает продолжение обработки дополнительных записей командлетом, это завершающая ошибка. Командлет должен вызвать метод System.Management.Automation.Командлет.ThrowTerminatingError*, который ссылается на объект System.Management.Automation.ErrorRecord. Если исключение не перехватывается командлетом, среда выполнения Windows PowerShell создает завершающую ошибку, содержащую меньше информации.

  • Для неустранимой ошибки, которая не останавливает операцию в следующей записи, которая поступает из конвейера (например, запись, созданная другим процессом), командлет должен вызвать метод System.Management.Automation.Cmdlet.WriteError*, который ссылается на объект System.Management.Automation.ErrorRecord. Примером неустранимой ошибки является ошибка, которая возникает, если определенный процесс не удается остановить. Вызов метода System.Management.Automation.Cmdlet.WriteError* позволяет пользователю последовательно выполнять запрошенные действия и сохранять сведения для определенных действий, которые завершаются сбоем. Командлет должен обрабатывать каждую запись как можно независимо.

  • Объект System.Management.Automation.ErrorRecord, на который ссылается метод System.Management.Automation.Automation.ThrowTerminatingError* и System.Management.Automation.Командлет.WriteError* требует исключения. Следуйте рекомендациям по проектированию .NET Framework при определении исключения для использования. Если ошибка семантически совпадает с существующим исключением, используйте это исключение или наследуйте это исключение. В противном случае наследуйте новую иерархию исключений или исключений непосредственно из типа System.Exception.

Объект System.Management.Automation.ErrorRecord также требует категорию ошибок, которая группирует ошибки для пользователя. Пользователь может просматривать ошибки на основе категории, задав значение переменной оболочки $ErrorView значение CategoryView. Возможные категории определяются перечислением System.Management.Automation.ErrorCategory.

  • Если командлет создает новый поток и если код, выполняющийся в этом потоке, вызывает необработанное исключение, Windows PowerShell не перехватывает ошибку и завершит процесс.

  • Если объект содержит код в деструкторе, который вызывает необработанное исключение, Windows PowerShell не перехватит ошибку и завершит процесс. Это также происходит, если объект вызывает методы Dispose, вызывающие необработанное исключение.

Использование модуля Windows PowerShell для развертывания командлетов (RC07)

Создайте модуль Windows PowerShell для упаковки и развертывания командлетов. Поддержка модулей представлена в Windows PowerShell 2.0. Сборки, содержащие классы командлетов, можно использовать непосредственно в виде двоичных файлов модуля (это очень полезно при тестировании командлетов) или создать манифест модуля, ссылающийся на сборки командлетов. (При использовании модулей можно также добавлять существующие сборки оснастки.) Дополнительные сведения о модулях см. в записи модуля Windows PowerShell.

См. также

настоятельно рекомендуемых рекомендаций по разработке

рекомендации по разработке рекомендаций по разработке

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