Добавление псевдонимов, развертывание подстановочных знаков и справка по параметрам командлета

В этом разделе описывается, как добавить псевдонимы, расширение подстановочных знаков и вспомогательные сообщения в параметры командлета Stop-Proc (описано в разделе Создание командлета, который изменяет системный).

Этот командлет Stop-Proc пытается остановить процессы, полученные с помощью командлета Get-Proc (описанного в разделе создание первого командлета).

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

Первым шагом в создании командлета является всегда именование командлета и объявление класса .NET, реализующего командлет. Так как вы пишете командлет для изменения системы, оно должно быть названо соответствующим образом. Так как этот командлет останавливает системные процессы, он использует команду Stop, определяемую классом System.Management.Automation.VerbsLifecy cle, с существительным Proc для указания процесса. Дополнительные сведения о утвержденных командах командлетов см. в имена командлетов.

Следующий код — это определение класса для этого командлета Stop-Proc.

[Cmdlet(VerbsLifecycle.Stop, "proc",
        SupportsShouldProcess = true)]
public class StopProcCommand : Cmdlet

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

Командлету необходимо определить параметры, поддерживающие изменения системы и отзывы пользователей. Командлет должен определить параметр Name или эквивалентный, чтобы командлет мог изменять систему по определенному идентификатору. Кроме того, командлет должен определить параметры force и PassTh ru. Дополнительные сведения об этих параметрах см. в создании командлета, который изменяет системный.

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

Псевдоним параметра может быть альтернативным именем или хорошо определенным 1-буквой или 2-буквным коротким именем для параметра командлета. В обоих случаях цель использования псевдонимов — упростить ввод пользователя из командной строки. Windows PowerShell поддерживает псевдонимы параметров с помощью атрибута System.Management.Automation.AliasAttribute, который использует синтаксис объявления [Alias()].

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

/// <summary>
/// Specify the mandatory Name parameter used to identify the
/// processes to be stopped.
/// </summary>
[Parameter(
           Position = 0,
           Mandatory = true,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true,
           HelpMessage = "The name of one or more processes to stop. Wildcards are permitted."
)]
[Alias("ProcessName")]
public string[] Name
{
  get { return processNames; }
  set { processNames = value; }
}
private string[] processNames;

Помимо использования атрибута System.Management.Automation.AliasAttribute, среда выполнения Windows PowerShell выполняет сопоставление частичных имен, даже если псевдонимы не указаны. Например, если командлет имеет параметр FileName и это единственный параметр, который начинается с F, пользователь может ввести Filename, Filenam, File, Fiили F и по-прежнему распознать запись как параметр FileName.

Создание справки по параметрам

Windows PowerShell позволяет создать справку для параметров командлета. Это можно сделать для любого параметра, используемого для изменения системы и отзывов пользователей. Для каждого параметра для поддержки справки можно задать ключевое слово атрибута HelpMessage в объявлении атрибута System.Management.Automation.ParameterAttribute. Это ключевое слово определяет текст, отображаемый пользователю для получения помощи в использовании параметра. Можно также задать ключевое слово helpMessageBaseName , чтобы определить базовое имя ресурса, используемого для сообщения. Если задать это ключевое слово, необходимо также задать ключевое слово HelpMessageResourceId, чтобы указать идентификатор ресурса.

Следующий код из этого командлета Stop-Proc определяет ключевое слово атрибута HelpMessage для параметра Name.

/// <summary>
/// Specify the mandatory Name parameter used to identify the
/// processes to be stopped.
/// </summary>
[Parameter(
           Position = 0,
           Mandatory = true,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true,
           HelpMessage = "The name of one or more processes to stop. Wildcards are permitted."
)]

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

Командлет должен переопределить метод обработки входных данных, чаще всего это будет System.Management.Automation.Командлет.ProcessRecord. При изменении системы командлет должен вызывать методы System.Management.Automation.Automation.ShouldProcess и System.Management.Automation.Командлет.ShouldContinue, чтобы разрешить пользователю предоставлять отзывы перед внесением изменений. Дополнительные сведения об этих методах см. в создании командлета, который изменяет системный.

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

Чтобы разрешить выбор нескольких объектов, командлет может использовать классы System.Management.Automation.WildcardPattern и System.Management.Automation.WildcardOptions, чтобы обеспечить поддержку расширения подстановочных знаков для ввода параметров. Примерами шаблонов подстановочных знаков являются lsa*, *.txtи [a-c]*. Используйте символ обратной кавычки (`) в качестве escape-символа, если шаблон содержит символ, который должен использоваться буквально.

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

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

• Вопросительный знак (?). Соответствует любому символу в указанном расположении.
• Звездочка (*). Соответствует нулю или нескольким символам, начиная с указанного расположения.
• Открытая скобка ([). Представляет выражение скобки шаблона, которое может содержать символы или диапазон символов. Если требуется диапазон, дефис (-) используется для указания диапазона.
• Закрыть скобку (]). Заканчивает выражение скобки шаблона.
• Символ escape-кавычки (`). Указывает, что следующий символ должен приниматься буквально. Помните, что при указании символа обратной кавычки из командной строки (в отличие от программного указания), экранный символ обратной кавычки должен быть указан дважды.

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

WildcardOptions options = WildcardOptions.IgnoreCase |
                          WildcardOptions.Compiled;
WildcardPattern wildcard = new WildcardPattern(name,options);

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

if (!wildcard.IsMatch(processName))
{
  continue;
}

Пример кода

Полный пример кода C# см. в разделе StopProcessSample03 sample.

Определение типов объектов и форматирования

Windows PowerShell передает сведения между командлетами с помощью объектов .NET. Следовательно, командлету может потребоваться определить собственный тип, или командлету может потребоваться расширить существующий тип, предоставленный другим командлетом. Дополнительные сведения об определении новых типов или расширении существующих типов см. в расширении типов объектов и форматировании.

Создание командлета

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

Тестирование командлета

После регистрации командлета в Windows PowerShell его можно протестировать, выполнив его в командной строке. Давайте протестируем пример командлета Stop-Proc. Дополнительные сведения об использовании командлетов из командной строки см. в Windows PowerShell.

• Запустите Windows PowerShell и используйте Stop-Proc, чтобы остановить процесс с помощью псевдонима ProcessName для параметра Name.

  PS> Stop-Proc -ProcessName notepad
  

  Отображаются следующие выходные данные.

  Confirm
  Are you sure you want to perform this action?
  Performing operation "Stop-Proc" on Target "notepad (3496)".
  [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y
  

• Выполните следующую запись в командной строке. Так как параметр Name является обязательным, вам будет предложено его. При вводе !? выводится текст справки, связанный с параметром.

  PS> Stop-Proc
  

  Отображаются следующие выходные данные.

  Cmdlet Stop-Proc at command pipeline position 1
  Supply values for the following parameters:
  (Type !? for Help.)
  Name[0]: !?
  The name of one or more processes to stop. Wildcards are permitted.
  Name[0]: notepad
  

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

  PS> Stop-Proc -Name *note*
  

  Отображаются следующие выходные данные.

  Confirm
  Are you sure you want to perform this action?
  Performing operation "Stop-Proc" on Target "notepad (1112)".
  [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y
  

  Отображаются следующие выходные данные.

  Confirm
  Are you sure you want to perform this action?
  Performing operation "Stop-Proc" on Target "ONENOTEM (3712)".
  [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N
  

  Отображаются следующие выходные данные.

  Confirm
  Are you sure you want to perform this action?
  Performing operation "Stop-Proc" on Target "ONENOTE (3592)".
  [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N
  

См. также

• создание командлета, который изменяет системный
• Создание командлета Windows PowerShell
• расширения типов объектов и форматирования
• Регистрация командлетов, поставщиков и ведущих приложений
• поддержки подстановочных знаков в параметрах командлетов
• пакета SDK для Windows PowerShell