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

2025-03-25

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

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

Пример командлета, использующего два набора параметров для определения различных функций, — это командлет Get-EventLog, предоставляемый Windows PowerShell. Этот командлет возвращает различные сведения, когда пользователь задает параметр List или LogName. Если указан параметр LogName, командлет возвращает сведения о событиях в заданном журнале событий. Если указан параметр List, командлет возвращает сведения о файлах журнала (а не сведения о событии, которые они содержат). В этом случае параметры List и LogName определяют два отдельных набора параметров.

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

Для иллюстрации последней точки этот командлет Stop-Proc использует три набора параметров: ProcessName, ProcessIdи InputObject. Каждый из этих наборов параметров имеет один параметр, который не входит в другие наборы параметров. Наборы параметров могут совместно использовать другие параметры, но командлет использует уникальные параметры ProcessName, ProcessIdи InputObject для определения набора параметров, которые должна использовать среда выполнения Windows PowerShell.

Объявление класса командлета

Первым шагом в создании командлета является всегда именование командлета и объявление класса .NET, реализующего командлет. Для этого командлета используется команда жизненного цикла Stop, так как командлет останавливает системные процессы. Имя существительного "Proc" используется, так как командлет работает над процессами. В приведенном ниже объявлении обратите внимание, что имя командлета и существительного отражаются в имени класса командлета.

Примечание.

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

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

[Cmdlet(VerbsLifecycle.Stop, "Proc",
        DefaultParameterSetName = "ProcessId",
        SupportsShouldProcess = true)]
public class StopProcCommand : PSCmdlet

<Cmdlet(VerbsLifecycle.Stop, "Proc", DefaultParameterSetName:="ProcessId", _
SupportsShouldProcess:=True)> _
Public Class StopProcCommand
    Inherits PSCmdlet

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

Этот командлет определяет три параметра, необходимые в качестве входных данных командлета (эти параметры также определяют наборы параметров), а также параметр Force, который управляет выполнением командлета и параметром PassThru, который определяет, отправляет ли командлет выходной объект через конвейер. По умолчанию этот командлет не передает объект через конвейер. Дополнительные сведения об этих последних двух параметрах см. в создании командлета, который изменяет системный.

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

Этот входной параметр позволяет пользователю указать имена процессов, которые необходимо остановить. Обратите внимание, что ключевое слово атрибута ParameterSetName атрибута System.Management.Automation.ParameterAttribute задает набор параметров ProcessName для этого параметра.

[Parameter(
   Position = 0,
   ParameterSetName = "ProcessName",
   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;

<Parameter(Position:=0, ParameterSetName:="ProcessName", _
Mandatory:=True, _
ValueFromPipeline:=True, ValueFromPipelineByPropertyName:=True, _
HelpMessage:="The name of one or more processes to stop. " & _
    "Wildcards are permitted."), [Alias]("ProcessName")> _
Public Property Name() As String()
    Get
        Return processNames
    End Get
    Set(ByVal value As String())
        processNames = value
    End Set
End Property

Private processNames() As String

Обратите внимание также, что псевдоним ProcessName присваивается этому параметру.

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

Этот входной параметр позволяет пользователю указать идентификаторы процессов, которые должны быть остановлены. Обратите внимание, что ключевое слово атрибута ParameterSetName атрибута System.Management.Automation.ParameterAttribute задает набор параметров ProcessId.

[Parameter(
           ParameterSetName = "ProcessId",
           Mandatory = true,
           ValueFromPipelineByPropertyName = true,
           ValueFromPipeline = true
)]
[Alias("ProcessId")]
public int[] Id
{
  get { return processIds; }
  set { processIds = value; }
}
private int[] processIds;

<Parameter(ParameterSetName:="ProcessId", _
Mandatory:=True, _
ValueFromPipelineByPropertyName:=True, _
ValueFromPipeline:=True), [Alias]("ProcessId")> _
Public Property Id() As Integer()
    Get
        Return processIds
    End Get
    Set(ByVal value As Integer())
        processIds = value
    End Set
End Property
Private processIds() As Integer

Обратите внимание, что псевдоним ProcessId присваивается этому параметру.

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

Этот входной параметр позволяет пользователю указать входной объект, содержащий сведения об остановленных процессах. Обратите внимание, что ключевое слово атрибута ParameterSetName атрибута System.Management.Automation.ParameterAttribute задает набор параметров InputObject для этого параметра.

[Parameter(
           ParameterSetName = "InputObject",
           Mandatory = true,
           ValueFromPipeline = true)]
public Process[] InputObject
{
  get { return inputObject; }
  set { inputObject = value; }
}
private Process[] inputObject;

<Parameter(ParameterSetName:="InputObject", _
Mandatory:=True, ValueFromPipeline:=True)> _
Public Property InputObject() As Process()
    Get
        Return myInputObject
    End Get
    Set(ByVal value As Process())
        myInputObject = value
    End Set
End Property
Private myInputObject() As Process

Обратите внимание, что этот параметр не имеет псевдонима.

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

Хотя для каждого набора параметров должен быть уникальный параметр, параметры могут принадлежать нескольким наборам параметров. В этих случаях присвойте общему параметру объявление атрибута System.Management.Automation.ParameterAttribut e для каждого набора, которому принадлежит этот параметр. Если параметр находится во всех наборах параметров, необходимо объявить атрибут параметра только один раз и не нужно указывать имя набора параметров.

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

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

protected override void ProcessRecord()
{
  switch (ParameterSetName)
  {
    case "ProcessName":
         ProcessByName();
         break;

    case "ProcessId":
         ProcessById();
         break;

    case "InputObject":
         foreach (Process process in inputObject)
         {
           SafeStopProcess(process);
         }
         break;

    default:
         throw new ArgumentException("Bad ParameterSet Name");
  } // switch (ParameterSetName...
} // ProcessRecord

Protected Overrides Sub ProcessRecord()
    Select Case ParameterSetName
        Case "ProcessName"
            ProcessByName()

        Case "ProcessId"
            ProcessById()

        Case "InputObject"
            Dim process As Process
            For Each process In myInputObject
                SafeStopProcess(process)
            Next process

        Case Else
            Throw New ArgumentException("Bad ParameterSet Name")
    End Select

End Sub 'ProcessRecord ' ProcessRecord

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

Пример кода

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

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

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

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

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

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

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

При запуске Windows PowerShell запустите командлет Stop-Proc с параметром ProcessId, чтобы остановить процесс на основе его идентификатора. В этом случае командлет использует параметр ProcessId для остановки процесса.
```
PS> Stop-Proc -Id 444
Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "notepad (444)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y
```
При запуске Windows PowerShell запустите командлет Stop-Proc с параметром InputObject, чтобы остановить процессы в объекте Блокнота, полученном командой Get-Process.
```
PS> Get-Process notepad | Stop-Proc
Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "notepad (444)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N
```