Настоятельно рекомендуемые руководства по разработке

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

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

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

Используйте конкретное существительное для имени командлета (SD01)

Существительные, используемые в именовании командлетов, должны быть очень конкретными, чтобы пользователь смог найти ваши командлеты. Добавьте префикс к универсальным существительным, таким как "сервер", используя сокращенную версию имени продукта. Например, если существительное ссылается на сервер, на котором выполняется экземпляр Microsoft SQL Server, используйте существительное, например "SQLServer". Сочетание определенных существительных и короткого списка утвержденных глаголов позволяет пользователю быстро обнаруживать и предвидеть функциональность, избегая дублирования между названиями командлетов.

Чтобы улучшить взаимодействие с пользователем, существительное, выбранное для имени командлета, должно быть уникальным. Например, используйте имя Get-Process вместо Get-Processes. Рекомендуется всегда следовать этому правилу для всех имен командлетов, даже если командлет, скорее всего, будет работать над несколькими элементами.

Используйте ПаскальКейс для имен командлетов (SD02)

Используйте PascalCase для имен параметров. Другими словами, начинайте с прописной буквы глагол и все термины, входящие в состав существительного. Например, Clear-ItemProperty.

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

Командлету требуются параметры, получающие данные, с которыми он должен работать, и параметры, указывающие сведения, используемые для определения характеристик операции. Например, командлет может иметь Name параметр, который получает данные из конвейера, а командлет может иметь Force параметр, указывающий, что командлет может быть вынужден выполнять свою операцию. Число параметров, которые может определить командлет, не ограничено.

Использование стандартных имен параметров

Командлет должен использовать стандартные имена параметров, чтобы пользователь смог быстро определить, что означает конкретный параметр. Если требуется более конкретное имя, используйте стандартное имя параметра, а затем укажите более конкретное имя в качестве псевдонима. Например, Get-Service командлет имеет параметр с универсальным именем (Name) и более конкретным псевдонимом (ServiceName). Оба термина можно использовать для указания параметра.

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

Использование имен сингулярных параметров

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

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

Используйте Pascal Case для имен параметров

Используйте вариант Pascal для имен параметров. Другими словами, начинать каждое слово с прописной буквы в имени параметра, включая первую букву имени. Например, имя ErrorAction параметра использует правильную прописную букву. В следующих именах параметров используются неправильные заглавные буквы.

• errorAction
• erroraction

Параметры, которые принимают список опций

Существует два способа создания параметра, значение которого можно выбрать из набора параметров.

• Определите тип перечисления (или используйте существующий тип перечисления), указывающий допустимые значения. Затем используйте тип перечисления для создания параметра этого типа.

• Добавьте атрибут ValidateSet в объявление параметра. Дополнительные сведения об этом атрибуте см. в разделе "Объявление атрибутов ValidateSet".

Использование стандартных типов для параметров

Чтобы обеспечить согласованность с другими командлетами, используйте стандартные типы параметров по возможности. Дополнительные сведения о типах, которые следует использовать для разных параметров, см. в разделе "Стандартные имена параметров командлетов" и "Типы". В этом разделе содержатся ссылки на несколько разделов, описывающих имена и типы .NET Framework для групп стандартных параметров, таких как "параметры действия".

Использование типов .NET Framework Strongly-Typed

Параметры должны быть определены как типы .NET Framework, чтобы обеспечить лучшую проверку параметров. Например, параметры, ограниченные одним значением из набора значений, должны быть определены как тип перечисления. Чтобы поддерживать значение универсального идентификатора ресурса (URI), определите параметр как тип System.Uri . Избегайте использования строковых параметров для всех свойств текста свободного формата.

Использование согласованных типов параметров

Если один и тот же параметр используется несколькими командлетами, всегда используйте один и тот же тип параметра. Например, если Process параметр является типом System.Int16 для одного командлета, не используйте Process параметр для другого командлета System.Uint16 типа.

Параметры, которые принимают значение true и false

Если параметр принимает только true и falseопределите параметр как тип System.Management.Automation.SwitchParameter. Параметр switch обрабатывается как true при указании в команде. Если параметр не включен в команду, Windows PowerShell считает значение параметра false. Не определяйте логические параметры.

Если параметру необходимо различать 3 значения: $true, $false и "не указано", определите параметр типа nullable<bool>. Потребность в третьем значении "не указано" обычно возникает, когда командлет может изменить логическое свойство объекта. В этом случае "не указано" означает, что текущее значение свойства не изменится.

Поддержка массивов для параметров

Часто пользователи должны выполнять одну и ту же операцию с несколькими аргументами. Для этих пользователей командлет должен принимать массив в качестве входных данных параметров, чтобы пользователь смог передать аргументы в параметр в качестве переменной Windows PowerShell. Например, командлет Get-Process использует массив строк, определяющих имена процессов для извлечения.

Поддержка параметра PassThru

По умолчанию многие командлеты, изменяющие систему, такие как командлет Stop-Process , действуют как приемники для объектов и не возвращают результат. Этот командлет должен использовать параметр PassThru, чтобы заставить командлет вернуть объект. PassThru При указании параметра командлет возвращает объект с помощью вызова метода System.Management.Automation.Cmdlet.WriteObject. Например, следующая команда останавливает Calc (CalculatorApp.exe) и передает результирующий процесс конвейеру.

Stop-Process -Name CalculatorApp -PassThru

В большинстве случаев командлеты Add, Set и New должны поддерживать параметр PassThru.

Наборы параметров поддержки

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

При указании наборов параметров задайте только один параметр в наборе ValueFromPipeline. Дополнительные сведения об объявлении атрибута Parameter см. в разделе ParameterAttribute Declaration.

Если используются наборы параметров, набор параметров по умолчанию определяется атрибутом Командлета . Набор параметров по умолчанию должен включать параметры, которые, скорее всего, будут использоваться в интерактивном сеансе Windows PowerShell. Дополнительные сведения об объявлении атрибута Командлета см. в объявлении КомандлетаAttribute.

Предоставление отзывов пользователю (SD04)

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

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

Поддержка методов WriteWarning, WriteVerbose и WriteDebug

Командлет должен вызывать метод System.Management.Automation.Командлет.WriteWarning , когда командлет будет выполнять операцию, которая может иметь непредвиденный результат. Например, командлет должен вызвать этот метод, если командлет должен перезаписать файл только для чтения.

Командлет должен вызывать метод System.Management.Automation.Cmdlet.WriteVerbose, когда пользователю требуются подробные сведения о том, что делает командлет. Например, командлет должен вызывать эти сведения, если автор командлета считает, что существуют сценарии, которые могут потребовать дополнительных сведений о том, что делает командлет.

Командлет должен вызвать метод System.Management.Automation.Cmdlet.WriteDebug , когда инженер по поддержке разработчика или продукта должен понять, что повреждает операцию командлета. Командлету не требуется вызывать метод System.Management.Automation.Командлет.WriteDebug в том же коде, который вызывает метод System.Management.Automation.Cmdlet.WriteVerbose , так как параметр Debug представляет оба набора сведений.

Поддержка WriteProgress для операций, которые занимают много времени

Операции командлетов, которые занимают много времени и которые не могут выполняться в фоновом режиме, должны поддерживать отчеты о ходе выполнения с помощью периодических вызовов метода System.Management.Automation.Командлет.WriteProgress.

Используйте интерфейсы хоста

Иногда командлет должен взаимодействовать непосредственно с пользователем, а не использовать различные методы Write или Should, поддерживаемые классом System.Management.Automation.Cmdlet. В этом случае командлет должен быть производным от класса System.Management.Automation.PSCmdlet и использовать свойство System.Management.Automation.PSCmdlet.Host* . Это свойство поддерживает различные уровни взаимодействия, включая типы PromptForChoice, Prompt и WriteLine/ReadLine. На самом конкретном уровне он также предоставляет способы чтения и записи отдельных ключей и работы с буферами.

Если командлет специально не предназначен для создания графического пользовательского интерфейса (GUI), он не должен обходить хост с использованием свойства System.Management.Automation.PSCmdlet.Host*. Пример командлета, предназначенного для создания графического интерфейса, — командлет Out-GridView.

Создание файла справки командлета (SD05)

Для каждой сборки cmdlet создайте файл Help.xml, содержащий информацию о cmdlet. Эти сведения включают описание командлета, описание параметров командлета, примеры использования командлета и многое другое.

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

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

Параметры программирования (SC01)

Определите параметр, объявив общедоступное свойство класса командлета, помеченное атрибутом Parameter. Параметры не должны быть статическими элементами производного класса .NET Framework для командлета. Дополнительные сведения о объявлении атрибута параметра см. в разделе "Объявление атрибута параметра".

Поддержка путей Windows PowerShell

Путь Windows PowerShell — это механизм нормализации доступа к пространствам имен. При назначении пути Windows PowerShell к параметру в командлете пользователь может определить пользовательский диск, который выступает в качестве ярлыка для определенного пути. Если пользователь назначает такой диск, хранимые данные, такие как данные в реестре, можно использовать согласованно.

Если командлет позволяет пользователю указывать файл или источник данных, он должен определить параметр типа System.String. Если поддерживается несколько дисков, тип должен быть массивом. Имя параметра должно быть Path, с псевдонимом PSPath. Кроме того, Path параметр должен поддерживать подстановочные знаки. Если поддержка подстановочных знаков не требуется, определите LiteralPath параметр.

Если данные, которые командлет считывает или записывает, должны быть файлом, командлет должен принимать входные данные в формате пути Windows PowerShell, а командлет должен использовать свойство System.Management.Automation.SessionState.Path для преобразования путей Windows PowerShell в пути, которые распознаются файловой системой. К конкретным механизмам относятся следующие методы:

• System.Management.Automation.PSCmdlet.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PSCmdlet.GetUnresolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetUnresolvedProviderPathFromPSPath

Если данные, которые командлет считывает или записывает только набор строк, а не файл, командлет должен использовать сведения о содержимом поставщика (Content член) для чтения и записи. Эти сведения получены из свойства System.Management.Automation.Provider.CmdletProvider.InvokeProvider. Эти механизмы позволяют другим хранилищам данных участвовать в чтении и записи данных.

Поддержка подстановочных знаков

Если это возможно, командлет должен поддерживать подстановочные знаки. Поддержка подстановочных знаков происходит во многих местах в командлете (особенно если параметр принимает строку для идентификации одного объекта из набора объектов). Например, пример Stop-Proc командлета из учебника StopProc определяет Name параметр для обработки строк, представляющих имена процессов. Этот параметр поддерживает подстановочные знаки, чтобы пользователь легко указать процессы для остановки.

Если доступна поддержка подстановочных знаков, операция командлета обычно создает массив. Иногда не имеет смысла поддерживать массив, так как пользователь может использовать только один элемент за раз. Например, командлет Set-Location не должен поддерживать массив, так как пользователь задает только одно расположение. В этом случае командлет по-прежнему поддерживает подстановочные знаки, но он заставляет разрешение до одного расположения.

Для получения дополнительной информации о шаблонах подстановочных символов см. раздел «Использование подстановочных символов в параметрах командлетов».

Определение объектов

В этом разделе содержатся рекомендации по определению объектов для командлетов и расширению существующих объектов.

Определение стандартных элементов

Определите стандартные члены для расширения типа объекта в пользовательском файле Types.ps1xml (используйте файл Windows PowerShell Types.ps1xml в качестве шаблона). Стандартные члены определяются узлом с именем PSStandardMembers. Эти определения позволяют другим командлетам и среде выполнения Windows PowerShell работать с объектом согласованно.

Определение объектаMembers для использования в качестве параметров

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

Существующим объектам .NET Framework, возвращаемым командлетами, часто не хватает некоторых важных или удобных элементов, необходимых разработчику скрипта или пользователю. Эти отсутствующие элементы могут быть особенно важными для отображения и создания правильных имен элементов, чтобы объект можно было правильно передать в конвейер. Создайте пользовательский файл Types.ps1xml, чтобы документировать эти необходимые элементы. При создании этого файла рекомендуется использовать следующее соглашение об именовании: <Your_Product_Name>. Types.ps1xml.

Например, можно добавить Mode свойство скрипта в тип System.IO.FileInfo , чтобы отобразить атрибуты файла более четко. Кроме того, можно добавить Count свойство псевдонима в тип System.Array , чтобы разрешить согласованное использование этого имени свойства (а не Length).

Реализация интерфейса IComparable

Реализуйте интерфейс System.IComparable во всех выходных объектах. Это позволяет легко передавать выходные объекты в различные командлеты сортировки и анализа.

Обновление сведений о отображении

Если отображение объекта не предоставляет ожидаемых результатов, создайте пользовательский файл <YourProductName>.Format.ps1xml для этого объекта.

Поддержка хорошо определенных входных данных для конвейера (SC02)

Реализация для средней части трубопровода

Реализуйте командлет, предполагая, что он будет вызван из середины конвейера (т. е. другие командлеты будут создавать входные данные или использовать выходные данные). Например, можно предположить, что командлет Get-Process, поскольку он генерирует данные, используется только в качестве первого командлета в конвейере. Однако, так как этот командлет предназначен для середины конвейера, этот командлет позволяет предыдущим командлетам или данным в конвейере указывать процессы для извлечения.

Поддержка входных данных из конвейера

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

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

Поддержка метода ProcessRecord

Чтобы принять все записи из предыдущего cmdlet в конвейере, ваш cmdlet должен реализовать метод System.Management.Automation.Cmdlet.ProcessRecord. Windows PowerShell вызывает этот метод многократно, по одному разу для каждой записи, отправляемой вашему командлету.

Запись отдельных данных в конвейер (SC03)

Когда командлет возвращает объекты, командлет должен немедленно записывать объекты по мере их создания. Командлет не должен хранить их для их буферизации в объединенный массив. Командлеты, которые получают объекты в качестве входных данных, смогут затем без задержки обрабатывать, отображать или и то и другое делать с выходными объектами. Командлет, создающий выходные объекты по одному, должен вызывать метод System.Management.Automation.Cmdlet.WriteObject. Командлет, который создает выходные объекты в пакетах (например, так как базовый API возвращает массив выходных объектов), должен вызывать метод System.Management.Automation.Cmdlet.WriteObject со своим вторым параметром true.

Создать командлеты Case-Insensitive и Case-Preserving (SC04)

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

См. также

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

Руководящие указания по разработке

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