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

Советы по разработке

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

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

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

Поддержка параметра InputObject (AD01)

Так как Windows PowerShell работает непосредственно с объектами Microsoft .NET Framework, объект .NET Framework часто доступен, который точно соответствует типу, который пользователю необходимо выполнить определенную операцию. InputObject — стандартное имя параметра, который принимает такой объект в качестве входных данных. Например, пример Stop-Proc командлета в руководстве StopProc определяет InputObject параметр типа Process, поддерживающий входные данные из конвейера. Пользователь может получить набор объектов процесса, управлять ими, чтобы выбрать точные объекты для остановки, а затем передать их Stop-Proc в командлет напрямую.

Поддержка параметра Force (AD02)

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

Например, командлет Remove-Item обычно не удаляет файл только для чтения. Однако этот командлет поддерживает параметр Force , чтобы пользователь смог принудительно удалить файл только для чтения. Если пользователь уже имеет разрешение на изменение атрибута только для чтения, а пользователь удаляет файл, использование параметра Force упрощает операцию. Однако если у пользователя нет разрешения на удаление файла, параметр Force не действует.

Обработка учетных данных с помощью Windows PowerShell (AD03)

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

Параметры кодирования поддержки (AD04)

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

Тестовые командлеты должны возвращать логическое значение (AD05)

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

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

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

Следуйте соглашениям об именовании классов командлетов (AC01)

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

Определение командлета в правильном пространстве имен

Обычно класс для командлета определяется в пространстве имен .NET Framework, которое добавляется .Commands в пространство имен, представляющее продукт, в котором выполняется командлет. Например, командлеты, включенные в Windows PowerShell, определяются в Microsoft.PowerShell.Commands пространстве имен.

Присвойте классу командлета имя командлета

Присвойте классу .NET Framework, реализующим командлет, присвойте классу <Verb><Noun>Commandимя, в котором замените <Verb><Noun> заполнители и заполнители глаголом и существительным, используемым для имени командлета. Например, командлет Get-Process реализуется классом с именем GetProcessCommand.

Если входные данные конвейера не переопределяют метод BeginProcessing (AC02)

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

Чтобы обрабатывать запросы остановки, переопределите метод StopProcessing (AC03)

Переопределите метод System.Management.Automation.Командлет.StopProcessing , чтобы командлет может обрабатывать сигнал остановки. Некоторые командлеты занимают много времени, чтобы завершить свою операцию, и они позволяют длительное время передаваться между вызовами среды выполнения Windows PowerShell, например, когда командлет блокирует поток в длительных вызовах RPC. К ним относятся командлеты, которые выполняют вызовы к методу System.Management.Automation.Cmdlet.WriteObject , методу System.Management.Automation.Cmdlet.WriteError и другим механизмам обратной связи, которые могут занять много времени. В таких случаях пользователю может потребоваться отправить сигнал остановки этим командлетам.

Реализация интерфейса IDisposable (AC04)

Если командлет имеет объекты, которые не удаляются (записываются в конвейер) методом System.Management.Automation.Cmdlet.ProcessRecord , командлет может потребовать дополнительного удаления объектов. Например, если командлет открывает дескриптор файла в методе System.Management.Automation.Командлет.BeginProcessing и сохраняет дескриптор открытым для использования методом System.Management.Automation.Cmdlet.ProcessRecord , этот дескриптор должен быть закрыт в конце обработки.

Среда выполнения Windows PowerShell не всегда вызывает метод System.Management.Automation.Командлет.EndProcessing . Например, метод System.Management.Automation.Командлет.EndProcessing может не вызываться, если командлет отменяется в середине операции или если в любой части командлета возникает завершающая ошибка. Таким образом, класс .NET Framework для командлета, требующего очистки объектов, должен реализовать полный шаблон интерфейса System.IDisposable , включая метод завершения, чтобы среда выполнения Windows PowerShell может вызывать методы System.Management.Automation.Командлет.EndProcessing и System.IDisposable.Dispose* в конце обработки.

Использование типов параметров, понятных для сериализации (AC05)

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

Примитивные типы:

  • Byte, SByte, Decimal, Single, Double, Int16, Int32, Int64, Uint16, UInt32 и UInt64.
  • Boolean, Guid, Byte[], TimeSpan, DateTime, Uri и Version.
  • Char, String, XmlDocument.

Встроенные типы rehydratable:

  • PSPrimitiveDictionary
  • ПараметрПереключателя
  • PSListModifier
  • PSCredential
  • IPAddress, MailAddress
  • CultureInfo
  • X509Certificate2, X500DistinguishedName
  • DirectorySecurity, FileSecurity, RegistrySecurity

Другие типы:

  • Безопасная строка (SecureString)
  • Контейнеры (списки и словари указанного выше типа)

Использование SecureString для конфиденциальных данных (AC06)

При обработке конфиденциальных данных всегда используйте тип данных System.Security.SecureString . Это может включать входные данные конвейера в параметры, а также возврат конфиденциальных данных в конвейер.

Хотя .NET рекомендует использовать SecureString для новой разработки, PowerShell продолжает поддерживать класс SecureString для обратной совместимости. Использование SecureString по-прежнему безопаснее, чем использование обычной текстовой строки. PowerShell по-прежнему использует тип SecureString , чтобы избежать случайного предоставления содержимого консоли или в журналах. Используйте SecureString тщательно, так как его можно легко преобразовать в строку обычного текста. Полное обсуждение использования SecureString см. в документации по классу System.Security.SecureString.

См. также

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

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

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