Přidání sad parametrů do rutiny

Článek
09/27/2021

Věci o sadách parametrů

Windows PowerShell definuje sadu parametrů jako skupinu parametrů, které spolupracují. Seskupením parametrů rutiny můžete vytvořit jedinou rutinu, která může změnit její funkčnost na základě toho, jakou skupinu parametrů uživatel zadá.

Příklad rutiny, která používá dvě sady parametrů k definování různých funkcí Get-EventLog , je rutinou, která je poskytována Windows PowerShell. Tato rutina vrátí jiné informace, když uživatel určí List LogName parametr nebo. Pokud LogName je parametr zadán, rutina vrátí informace o událostech v daném protokolu událostí. Pokud List je parametr zadán, rutina vrátí informace o samotných souborech protokolu (nikoli informace o událostech, které obsahují). V tomto případě List LogName parametry a identifikují dvě samostatné sady parametrů.

mezi dvě důležité věci týkající se sad parametrů je, že modul runtime Windows PowerShell používá pouze jednu sadu parametrů pro konkrétní vstup a že každá sada parametrů musí mít alespoň jeden parametr, který je pro danou sadu parametrů jedinečný.

K ilustraci tohoto posledního bodu používá tato rutina Stop-Proc tři sady parametrů: ProcessName , ProcessId a InputObject . Každá z těchto sad parametrů má jeden parametr, který není v ostatních sadách parametrů. sady parametrů mohou sdílet jiné parametry, ale rutina používá jedinečné parametry ProcessName , ProcessId a InputObject k určení sady parametrů, které má Windows PowerShell runtime použít.

Deklarace třídy rutiny

První krok při vytváření rutiny vždy pojmenovává rutinu a deklaruje třídu .NET, která implementuje rutinu. Pro tuto rutinu se používá operace "Stop" (životní cyklus), protože rutina zastaví systémové procesy. Název podstatného jména "proc" se používá, protože rutina funguje na procesech. V deklaraci níže si všimněte, že operace rutiny a název podstatné jméno se projeví v názvu třídy rutiny.

Poznámka

Další informace o názvůch operací rutiny najdete v tématu názvy operací rutiny.

Následující kód je definicí třídy pro tuto Stop-Proc rutinu.

[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

Deklarace parametrů rutiny

Tato rutina definuje tři parametry nutné jako vstup do rutiny (tyto parametry také definují sady parametrů), jakož i Force parametr, který spravuje, co rutina dělá, a PassThru parametr, který určuje, zda rutina odesílá výstupní objekt prostřednictvím kanálu. Ve výchozím nastavení tato rutina neprojde objekt přes kanál. Další informace o těchto posledních dvou parametrech najdete v tématu Vytvoření rutiny, která mění systém.

Deklarace parametru name

Tento vstupní parametr umožňuje uživateli zadat názvy procesů, které mají být zastaveny. Všimněte si, že ParameterSetName klíčové slovo Attribute atributu System. Management. Automation. ParameterAttribute Určuje ProcessName sadu parametrů pro tento parametr.

[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

Všimněte si také, že tento parametr má přiřazen alias "Process".

Deklarace parametru ID

Tento vstupní parametr umožňuje uživateli zadat identifikátory procesů, které mají být zastaveny. Všimněte si, že ParameterSetName klíčové slovo Attribute atributu System. Management. Automation. ParameterAttribute Určuje ProcessId sadu parametrů.

[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

Všimněte si také, že tento parametr má přiřazen alias "ProcessId".

Deklarace parametru položky InputObject

Tento vstupní parametr umožňuje uživateli zadat vstupní objekt, který obsahuje informace o procesech, které mají být zastaveny. Všimněte si, že ParameterSetName klíčové slovo Attribute atributu System. Management. Automation. ParameterAttribute Určuje InputObject sadu parametrů pro tento parametr.

[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

Všimněte si také, že tento parametr nemá žádný alias.

Deklarace parametrů ve více sadách parametrů

I když musí existovat jedinečný parametr pro každou sadu parametrů, parametry mohou patřit do více než jedné sady parametrů. V těchto případech poskytněte sdílenému parametru deklaraci atributu System. Management. Automation. ParameterAttribute pro každou sadu, ke které parametr patří. Pokud je parametr ve všech sadách parametrů, stačí deklarovat atribut parametru pouze jednou a není nutné zadávat název sady parametrů.

Přepsání vstupní metody zpracování

Každá rutina musí přepsat vstupní metodu zpracování, většinou se jedná o metodu System. Management. Automation. rutine. ProcessRecord . V této rutině je metoda System. Management. Automation. rutina. ProcessRecord přepsaná, aby mohla rutina zpracovat libovolný počet procesů. Obsahuje příkaz SELECT, který volá jinou metodu na základě toho, kterou sadu parametrů zadal uživatel.

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

Pomocné metody, které jsou volány příkazem SELECT, zde nejsou popsány, ale jejich implementaci můžete zobrazit v ukázce kompletního kódu v následující části.

Vzorek kódu

Úplný ukázkový kód jazyka C# naleznete v tématu StopProcessSample04 Sample.

Definování typů objektů a formátování

Windows PowerShell předává informace mezi rutinami pomocí objektů .net. V důsledku toho může rutina potřebovat definovat vlastní typ, nebo může být nutné, aby rutina rozšířila existující typ poskytnutý jinou rutinou. Další informace o definování nových typů nebo rozšíření existujících typů naleznete v tématu rozšíření typů objektů a formátování.

Sestavení rutiny

po implementaci rutiny je nutné ji zaregistrovat pomocí Windows PowerShell prostřednictvím modulu snap-in Windows PowerShell. Další informace o registraci rutin najdete v tématu jak registrovat rutiny, zprostředkovatele a hostitelské aplikace.

Testování rutiny

když je vaše rutina zaregistrovaná ve službě Windows PowerShell, otestujte ji spuštěním na příkazovém řádku. Zde jsou některé testy, které ukazují, ProcessId Jak InputObject lze pomocí parametrů a otestovat jejich sady parametrů pro zastavení procesu.

po spuštění Windows PowerShell spustit rutinu Stop-Proc se ProcessId sadou parametrů, aby se zastavil proces založený na jeho identifikátoru. V tomto případě rutina používá ProcessId sadu parametrů k zastavení procesu.
```
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
```

po spuštění Windows PowerShell spusťte rutinu Stop-Proc se InputObject sadou parametrů, aby se zastavily procesy na objektu Poznámkový blok načteném Get-Process příkazem.

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