Lägga till parameteruppsättningar i en cmdlet

Artikel
09/27/2021
6 minuter för att läsa

Saker att känna till om parameteruppsättningar

Windows PowerShell definierar en parameteruppsättning som en grupp parametrar som fungerar tillsammans. Genom att gruppera parametrarna för en cmdlet kan du skapa en enda cmdlet som kan ändra dess funktioner baserat på vilken grupp av parametrar som användaren anger.

Ett exempel på en cmdlet som använder två parameteruppsättningar för att definiera olika funktioner är Get-EventLog cmdleten som tillhandahålls av Windows PowerShell. Denna cmdlet returnerar annan information när användaren anger List LogName parametern eller . Om LogName parametern anges returnerar cmdleten information om händelserna i en viss händelselogg. Om List parametern anges returnerar cmdleten information om själva loggfilerna (inte händelseinformationen de innehåller). I det här fallet identifierar List LogName parametrarna och två separata parameteruppsättningar.

Två viktiga saker att komma ihåg om parameteruppsättningar är att Windows PowerShell-körningen bara använder en parameteruppsättning för en viss indata och att varje parameteruppsättning måste ha minst en parameter som är unik för den parameteruppsättningen.

För att illustrera den sista punkten använder Stop-Proc här cmdleten tre parameteruppsättningar: ProcessName ProcessId , och InputObject . Var och en av dessa parameteruppsättningar har en parameter som inte finns i de andra parameteruppsättningarna. Parameteruppsättningarna kan dela andra parametrar, men cmdleten använder de unika parametrarna , och för att identifiera vilken uppsättning parametrar ProcessName ProcessId som Windows PowerShell ska InputObject använda.

Deklarera cmdlet-klassen

Det första steget i att skapa cmdleten är att alltid namnge cmdleten och deklarera den .NET-klass som implementerar cmdleten . För den här cmdleten används livscykelverbet "Stoppa" eftersom cmdleten stoppar systemprocesserna. Substantivnamnet "Proc" används eftersom cmdleten fungerar på processer. Observera att cmdlet-verbet och substantivnamnet återspeglas i namnet på cmdlet-klassen i deklarationen nedan.

Anteckning

Mer information om godkända cmdlet-verbnamn finns i Cmdlet verbnamn.

Följande kod är klassdefinitionen för den här Stop-Proc-cmdleten.

[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

Deklarera parametrarna för cmdleten

Denna cmdlet definierar tre parametrar som behövs som indata till cmdleten (dessa parametrar definierar även parameteruppsättningarna), samt en parameter som hanterar vad cmdleten gör och en parameter som avgör om cmdleten skickar ett utdataobjekt via Force PassThru pipelinen. Som standard skickar denna cmdlet inte ett objekt via pipelinen. Mer information om dessa två sista parametrar finns i Skapa en cmdlet som ändrar systemet.

Deklarera namnparametern

Med den här indataparametern kan användaren ange namnen på de processer som ska stoppas. Observera att ParameterSetName attributnyckelordet för attributet System.Management.Automation.Parameterattribute anger ProcessName parameteruppsättningen för den här parametern.

[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

Observera också att aliaset "ProcessName" ges till den här parametern.

Deklarera ID-parametern

Med den här indataparametern kan användaren ange identifierare för de processer som ska stoppas. Observera att ParameterSetName attributnyckelordet för attributet System.Management.Automation.Parameterattribute anger ProcessId parameteruppsättningen.

[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

Observera också att aliaset "ProcessId" ges till den här parametern.

Deklarera InputObject-parametern

Med den här indataparametern kan användaren ange ett indataobjekt som innehåller information om de processer som ska stoppas. Observera att ParameterSetName attributnyckelordet för attributet System.Management.Automation.Parameterattribute anger InputObject parameteruppsättningen för den här parametern.

[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

Observera också att den här parametern inte har något alias.

Deklarera parametrar i flera parameteruppsättningar

Även om det måste finnas en unik parameter för varje parameteruppsättning, kan parametrar tillhöra mer än en parameteruppsättning. I dessa fall ger du den delade parametern en deklaration av attributet System.Management.Automation.Parameterattribute för varje uppsättning som parametern tillhör. Om en parameter finns i alla parameteruppsättningar behöver du bara deklarera parameterattributet en gång och behöver inte ange parameteruppsättningens namn.

Åsidosätta en metod för indatabearbetning

Varje cmdlet måste åsidosätta en metod för indatabearbetning, oftast är detta metoden System.Management.Automation.Cmdlet.ProcessRecord. I den här cmdleten åsidosätts metoden System.Management.Automation.Cmdlet.ProcessRecord så att cmdleten kan bearbeta val av antal processer. Den innehåller en Select-instruktion som anropar en annan metod baserat på vilken parameteruppsättning som användaren har angett.

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

Hjälpmetoderna som anropas av Select-instruktionen beskrivs inte här, men du kan se deras implementering i det fullständiga kodexe exemplet i nästa avsnitt.

Kodexempel

Den fullständiga C#-exempelkoden finns i StopProcessSample04 Sample.

Definiera objekttyper och formatering

Windows PowerShell skickar information mellan cmdlets med hjälp av .NET-objekt. Därför kan en cmdlet behöva definiera sin egen typ, eller så kan cmdleten behöva utöka en befintlig typ som tillhandahålls av en annan cmdlet. Mer information om hur du definierar nya typer eller utökar befintliga typer finns i Utöka objekttyper och formatering.

Skapa cmdleten

När du har implementerat en cmdlet måste du registrera den Windows PowerShell en Windows PowerShell snapin-modulen. Mer information om hur du registrerar cmdlets finns i How to Register Cmdlets, Providers, and Host Applications.

Testa cmdleten

När din cmdlet har registrerats med Windows PowerShell kan du testa den genom att köra den på kommandoraden. Här är några tester som visar hur ProcessId parametrarna InputObject och kan användas för att testa sina parameteruppsättningar för att stoppa en process.

När Windows PowerShell igång kör du cmdleten Stop-Proc med parametern inställd för ProcessId att stoppa en process baserat på dess identifierare. I det här fallet använder cmdleten ProcessId parameteruppsättningen för att stoppa processen.
```
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
```

När Windows PowerShell startar kör du cmdleten Stop-Proc med parametern inställd för att stoppa processer InputObject på Anteckningar-objektet som hämtats av Get-Process kommandot .

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