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

Статья
2025-03-25

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

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

Первым шагом в создании командлета является именование командлетов и объявление класса .NET Framework, реализующего командлет. Этот командлет извлекает сведения о процессе, поэтому выбранное здесь имя команды — Get. (Практически любой вид командлета, который может получить информацию, может обрабатывать входные данные командной строки.) Дополнительные сведения о утвержденных командах командлетов см. в имена командлетов.

Ниже приведено объявление класса для командлета Get-Proc. Сведения об этом определении приведены в создании первого командлета.

[Cmdlet(VerbsCommon.Get, "proc")]
public class GetProcCommand: Cmdlet

<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
    Inherits Cmdlet

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

Параметр командлета позволяет пользователю предоставлять входные данные командлету. В следующем примере Get-Proc и Get-Member — это имена конвейерных командлетов, а MemberType — параметр для командлета Get-Member. Параметр имеет аргумент "свойство".

PS> Get-Proc ; свойство Get-Member -MemberType

Чтобы объявить параметры для командлета, сначала необходимо определить свойства, представляющие параметры. В командлете Get-Proc единственным параметром является Name, который в данном случае представляет имя объекта процесса .NET Framework для извлечения. Поэтому класс командлета определяет свойство строки типа для принятия массива имен.

Ниже приведено объявление параметров для параметра Name командлета Get-Proc.

/// <summary>
/// Specify the cmdlet Name parameter.
/// </summary>
  [Parameter(Position = 0)]
  [ValidateNotNullOrEmpty]
  public string[] Name
  {
    get { return processNames; }
    set { processNames = value; }
  }
  private string[] processNames;

  #endregion Parameters

<Parameter(Position:=0), ValidateNotNullOrEmpty()> _
Public Property Name() As String()
    Get
        Return processNames
    End Get

    Set(ByVal value As String())
        processNames = value
    End Set

End Property

Чтобы сообщить среде выполнения Windows PowerShell, что это свойство является параметром Name, в определение свойства добавляется атрибут System.Management.Automation.ParameterAttribute. Базовый синтаксис для объявления этого атрибута — [Parameter()].

Примечание.

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

Этот командлет использует массив строк для параметра Name. Если это возможно, командлет также должен определить параметр в виде массива, так как это позволяет командлету принимать несколько элементов.

Сведения о определениях параметров

Предопределенные имена параметров Windows PowerShell и типы данных должны использоваться повторно, чтобы обеспечить совместимость командлета с командлетами Windows PowerShell. Например, если все командлеты используют предопределенное имя параметра Id для идентификации ресурса, пользователь сможет легко понять значение параметра независимо от того, какой командлет они используют. В основном имена параметров соответствуют тем же правилам, что и имена переменных в среде CLR. Дополнительные сведения об именовании параметров см. в именах параметров командлетов.
Windows PowerShell резервирует несколько имен параметров для обеспечения согласованного взаимодействия с пользователем. Не используйте эти имена параметров: WhatIf, Confirm, Verbose, Debug, Warn, ErrorAction, ErrorVariable, OutVariableи OutBuffer. Кроме того, для этих имен параметров зарезервированы следующие псевдонимы: vb, db, ea, ev, ovи ob.
Name — это простое и общее имя параметра, рекомендуемое для использования в командлетах. Лучше выбрать такое имя параметра, чем сложное имя, уникальное для определенного командлета и трудно помнить.
Параметры не учитывает регистр в Windows PowerShell, хотя по умолчанию оболочка сохраняет регистр. Конфиденциальность регистра аргументов зависит от операции командлета. Аргументы передаются в параметр, указанный в командной строке.
Примеры других объявлений параметров см. в параметрах командлетов.

Объявление параметров как позиционных или именованных

Командлет должен задать каждый параметр как позиционный или именованный параметр. Оба типа параметров принимают одиночные аргументы, несколько аргументов, разделенных запятыми и логическими параметрами. Логический параметр, также называемый параметром , обрабатывает только логические параметры. Параметр используется для определения наличия параметра. Рекомендуемое значение по умолчанию — false.

Пример командлета Get-Proc определяет параметр Name в качестве позиционного параметра с позицией 0. Это означает, что первый аргумент, который пользователь вводит в командной строке, автоматически вставляется для этого параметра. Если вы хотите определить именованный параметр, для которого пользователь должен указать имя параметра из командной строки, оставьте ключевое слово Position из объявления атрибута.

Примечание.

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

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

Командлет должен задать каждый параметр как необязательный или обязательный. В примере командлета Get-Proc параметр Name определяется как необязательный, так как ключевое слово Mandatory не задано в объявлении атрибута.

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

В примере командлета Get-Proc добавляется атрибут проверки ввода System.Management.Automation.ValidateNotNullOrEmptyAttributeName , чтобы включить проверку того, что входные данные не null или пусты. Этот атрибут является одним из нескольких атрибутов проверки, предоставляемых Windows PowerShell. Примеры других атрибутов проверки см. в проверке входныхпараметров.

[Parameter(Position = 0)]
[ValidateNotNullOrEmpty]
public string[] Name

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

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

Командлет Get-Proc переопределяет метод System.Management.Automation.Cmdlet.ProcessRecord для обработки входных данных параметра Name, предоставленных пользователем или скриптом. Этот метод получает процессы для каждого запрошенного имени процесса или все для процессов, если имя не указано. Обратите внимание, что в System.Management.Automation.Командлет.ProcessRecordвызов System.Management.Automation.Cmdlet.WriteObject — это выходной механизм отправки выходных объектов в конвейер. Второй параметр этого вызова, enumerateCollection, имеет значение true, чтобы сообщить среде выполнения Windows PowerShell перечислить выходной массив объектов процесса и записать один процесс в командную строку.

protected override void ProcessRecord()
{
  // If no process names are passed to the cmdlet, get all processes.
  if (processNames == null)
  {
    // Write the processes to the pipeline making them available
    // to the next cmdlet. The second argument of this call tells
    // PowerShell to enumerate the array, and send one process at a
    // time to the pipeline.
    WriteObject(Process.GetProcesses(), true);
  }
  else
  {
    // If process names are passed to the cmdlet, get and write
    // the associated processes.
    foreach (string name in processNames)
    {
      WriteObject(Process.GetProcessesByName(name), true);
    }
  }
}

Protected Overrides Sub ProcessRecord()

    '/ If no process names are passed to the cmdlet, get all processes.
    If processNames Is Nothing Then
        Dim processes As Process()
        processes = Process.GetProcesses()
    End If

    '/ If process names are specified, write the processes to the
    '/ pipeline to display them or make them available to the next cmdlet.

    For Each name As String In processNames
        '/ The second parameter of this call tells PowerShell to enumerate the
        '/ array, and send one process at a time to the pipeline.
        WriteObject(Process.GetProcessesByName(name), True)
    Next

End Sub 'ProcessRecord

Пример кода

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

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

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

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

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

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

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

В командной строке Windows PowerShell используйте следующую команду для перечисления процесса Internet Explorer, который называется IEXPLORE.
```
Get-Proc -Name iexplore
```
Отображаются следующие выходные данные.
```
Handles  NPM(K)  PM(K)   WS(K)  VS(M)  CPU(s)   Id   ProcessName
-------  ------  -----   -----  -----   ------ --   -----------
    354      11  10036   18992    85   0.67   3284   iexplore
```

Чтобы получить список процессов Internet Explorer, Outlook и Блокнота с именем IEXPLORE, OUTLOOK и NOTEPAD, используйте следующую команду. При наличии нескольких процессов отображаются все процессы.

Get-Proc -Name iexplore, outlook, notepad

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

Handles  NPM(K)  PM(K)   WS(K)  VS(M)  CPU(s)   Id   ProcessName
-------  ------  -----   -----  -----  ------   --   -----------
    732      21  24696    5000    138   2.25  2288   iexplore
    715      19  20556   14116    136   1.78  3860   iexplore
   3917      62  74096   58112    468 191.56  1848   OUTLOOK
     39       2   1024    3280     30   0.09  1444   notepad
     39       2   1024     356     30   0.08  3396   notepad