Lägga till parameteruppsättningar i en cmdlet

Saker att veta 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 den Get-EventLog cmdlet som tillhandahålls av Windows PowerShell. Den här cmdleten returnerar annan information när användaren anger parametern List eller LogName. Om parametern LogName anges returnerar cmdleten information om händelserna i en viss händelselogg. Om parametern List anges returnerar cmdleten information om själva loggfilerna (inte den händelseinformation som de innehåller). I det här fallet identifierar parametrarna List och LogName två separata parameteruppsättningar.

Två viktiga saker att komma ihåg om parameteruppsättningar är att Windows PowerShell-körningen endast 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 parameteruppsättningen.

För att illustrera den sista punkten använder den här Stop-Proc-cmdleten tre parameteruppsättningar: ProcessName, ProcessIdoch 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 ProcessName, ProcessIdoch InputObject för att identifiera vilken uppsättning parametrar som Windows PowerShell-körningen ska använda.

Deklarera cmdlet-klassen

Det första steget när cmdleten skapas är att alltid namnge cmdleten och deklarera .NET-klassen som implementerar cmdleten. För den här cmdleten används livscykelverb "Stop" 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.

Anmärkning

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

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

Deklarera namnparametern

Med den här indataparametern kan användaren ange namnen på de processer som ska stoppas. Observera att nyckelordet ParameterSetName attribut i 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 vilka identifierare för processerna som ska stoppas. Observera att nyckelordet ParameterSetName attribut i attributet System.Management.Automation.ParameterAttribute anger parameteruppsättningen 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

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 nyckelordet ParameterSetName attribut i 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 System.Management.Automation.ParameterAttribute attributdeklaration 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 indatabearbetningsmetod

Varje cmdlet måste åsidosätta en indatabearbetningsmetod, 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 valfritt antal processer. Den innehåller en Select-instruktion som anropar en annan metod baserat på vilken parameteruppsättning 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 kodexemplet i nästa avsnitt.

Kodexempel

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

Definiera objekttyper och formatering

Windows PowerShell skickar information mellan cmdletar 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 med Windows PowerShell via en Windows PowerShell-snapin-modul. Mer information om hur du registrerar cmdletar finns i Så här registrerar du cmdletar, leverantörer och värdprogram.

Testa cmdleten

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

• När Windows PowerShell har startats kör du cmdleten Stop-Proc med parametern ProcessId inställd för att stoppa en process baserat på dess identifierare. I det här fallet använder cmdleten parametern ProcessId 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 har startats kör du cmdleten Stop-Proc med parametern InputObject inställd på att stoppa processer på notepad-objektet som hämtats av kommandot 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
  

Se även

Skapa en cmdlet som ändrar systemets

Skapa en Windows PowerShell-cmdlet

utöka objekttyper och formatering

Registrera cmdletar, leverantörer och värdprogram

Windows PowerShell SDK