Paraméterkészletek hozzáadása parancsmagokhoz

Cikk
09/27/2021

A paraméterkészletekkel kapcsolatos fontos tudnimek

Windows PowerShell egy paraméterkészletet határoz meg együtt működő paraméterek csoportjaként. Egy parancsmag paramétereinek csoportosítása lehetővé teszi, hogy egyetlen parancsmagot hozzon létre, amely a felhasználó által megadott paramétercsoport alapján módosíthatja annak működését.

Egy olyan parancsmag például, amely két paraméterkészletet használ a különböző funkciók meghatározásához, a parancsmag, amelyet a Get-EventLog Windows PowerShell. Ez a parancsmag különböző információkat ad vissza, amikor a felhasználó megadja a List vagy a LogName paramétert. Ha a paraméter meg van adva, a parancsmag információt ad vissza egy adott LogName eseménynapló eseményeiről. Ha a paraméter meg van adva, a parancsmag magukról a naplófájlokkal kapcsolatos adatokat ad vissza (nem pedig az List eseményadatokat, amelyek tartalmazzák őket). Ebben az esetben a List és a paraméter két különálló LogName paraméterkészletet azonosít.

A paraméterkészletekkel kapcsolatos két fontos dolog, hogy a Windows PowerShell-runtime csak egy paraméterkészletet használ egy adott bemenethez, és hogy minden paraméterkészletnek legalább egy, az adott paraméterkészlethez egyedi paraméterrel kell lennie.

Az utolsó pont szemléltetésére ez Stop-Proc parancsmag három paraméterkészletet használ: ProcessName , ProcessId és InputObject . Ezen paraméterkészletek mindegyikének van egy paraméterkészlete, amely nem a többi paraméterkészletben van. A paraméterkészletek más paramétereket is használhatnak, de a parancsmag az egyedi , és paramétereket használja annak azonosítására, hogy a Windows PowerShell futtatás melyik ProcessName ProcessId InputObject paraméterkészletet használja.

A parancsmagosztály deklarálása

A parancsmag létrehozásának első lépése mindig a parancsmag elnevezése és a parancsmagot megvalósító .NET-osztály deklarációja. Ehhez a parancsmaghoz a "Stop" életciklus-parancs használatos, mert a parancsmag leállítja a rendszerfolyamatokat. A "Proc" főnév azért használatos, mert a parancsmag folyamatokon működik. Az alábbi deklarációban figyelje meg, hogy a parancsmag ige és főnév is megjelenik a parancsmag osztályának nevében.

Megjegyzés

A jóváhagyott parancsmagnevekkel kapcsolatos további információkért lásd: Parancsmag-parancsmagok nevei.

A következő kód a parancsmag osztálydefiníciójaStop-Proc parancsmaghoz.

[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

A parancsmag paramétereinek deklarálta

Ez a parancsmag három paramétert határoz meg, amelyek a parancsmag bemeneteként szükségesek (ezek a paraméterek a paraméterkészleteket is meghatározzák), valamint egy paramétert, amely a parancsmag parancsmagját kezeli, valamint egy paramétert, amely meghatározza, hogy a parancsmag kimeneti objektumot küld-e a Force PassThru folyamaton keresztül. Alapértelmezés szerint ez a parancsmag nem ad át objektumot a folyamaton keresztül. További információ az utolsó két paraméterről: Creating a Cmdlet that Modififies the System.

A Name paraméter deklarása

Ez a bemeneti paraméter lehetővé teszi, hogy a felhasználó megadja a leállítani kívánt folyamatok nevét. Vegye figyelembe, hogy a ParameterSetName System.Management.Automation.Parameterattribute attribútumszava határozza meg a ProcessName paraméterkészletet ehhez a paraméterhez.

[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

Azt is figyelje meg, hogy a "ProcessName" alias van megadva ehhez a paraméterhez.

Az Azonosító paraméter deklarása

Ez a bemeneti paraméter lehetővé teszi, hogy a felhasználó megadja a leállítani kívánt folyamatok azonosítóit. Vegye figyelembe, ParameterSetName hogy a System.Management.Automation.Parameterattribute attribútum kulcsszó határozza meg a ProcessId paraméterkészletet.

[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

Vegye figyelembe azt is, hogy a "ProcessId" alias van megadva ehhez a paraméterhez.

Az InputObject paraméter deklarása

Ez a bemeneti paraméter lehetővé teszi, hogy a felhasználó megad egy bemeneti objektumot, amely információkat tartalmaz a leállítani kívánt folyamatokról. Vegye figyelembe, hogy a ParameterSetName System.Management.Automation.Parameterattribute attribútumszava határozza meg a InputObject paraméterkészletet ehhez a paraméterhez.

[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

Vegye figyelembe azt is, hogy ennek a paraméternek nincs aliasa.

Paraméterek deklarása több paraméterkészletben

Bár minden paraméterkészlethez egyedi paraméternek kell tartozni, a paraméterek több paraméterkészlethez is tartoznak. Ezekben az esetekben adjon egy System.Management.Automation.Parameterattribute attribútumdeklarációt a megosztott paraméternek minden olyan készlethez, amelyhez a paraméter tartozik. Ha egy paraméter az összes paraméterkészletben van, csak egyszer kell deklarálni a paraméterattribútumot, és nem kell megadnia a paraméterkészlet nevét.

Bemeneti feldolgozási metódus felülbírálása

Minden parancsmagnak felül kell bírálni egy bemeneti feldolgozási módszert. Ez leggyakrabban a System.Management.Automation.Cmdlet.ProcessRecord metódus. Ebben a parancsmagban a System.Management.Automation.Cmdlet.ProcessRecord metódus felül van bírálva, hogy a parancsmag bármilyen számú folyamatot feldolgozhat. Tartalmaz egy Select utasítást, amely egy másik metódust hív meg a felhasználó által megadott paraméterkészlet alapján.

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

A Select utasítás által hívott segítő metódusokat itt nem ismertetjük, de azok implementációja a következő szakaszban a teljes kódmintában látható.

Kódminta

A teljes C#-mintakódért tekintse meg a StopProcessSample04 mintát.

Objektumtípusok definiálása és formázása

Windows PowerShell .NET-objektumok használatával továbbítja az információkat a parancsmagok között. Emiatt előfordulhat, hogy egy parancsmagnak meg kell határoznia a saját típusát, vagy a parancsmagnak ki kell terjesztenie egy másik parancsmag által biztosított meglévő típust. További információ az új típusok meghatározásáról vagy a meglévő típusok kiterjesztéséről: Extending Object Types and Formatting (Az objektumtípusok kiterjesztése és formázása).

A parancsmag kiépítése

A parancsmagok megvalósítása után regisztrálnia kell azt a Windows PowerShell egy Windows PowerShell beépülő modulon keresztül. További információ a parancsmagok regisztrálásról: Parancsmagok, szolgáltatók és gazdaalkalmazások regisztrálása.

A parancsmag tesztelése

Miután regisztrálta a parancsmagot a Windows PowerShell, tesztelje a parancssorban való futtatásával. Íme néhány teszt, amelyek azt mutatják be, hogyan használhatók a és a paraméterekkel a paraméterkészletek egy folyamat ProcessId InputObject leállításához.

A Windows PowerShell futtassa a Stop-Proc parancsmagot a paraméterkészlet használatával, hogy leállítsa a folyamatot ProcessId az azonosítója alapján. Ebben az esetben a parancsmag a paraméterkészletet használja a ProcessId folyamat leállításához.
```
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
```

A Windows PowerShell után futtassa a Stop-Proc parancsmagot a paraméterkészlet használatával, hogy leállítsa a Jegyzettömb által lekért objektum InputObject Get-Process folyamatait.

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