Dodawanie parametrów, które przetwarzają dane wejściowe wiersza polecenia

Artykuł
09/24/2021

Jednym ze źródeł danych wejściowych dla polecenia cmdlet jest wiersz polecenia. W tym temacie opisano sposób dodawania parametru do polecenia cmdlet (opisanego w temacie Tworzenie pierwszego polecenia cmdlet ), aby polecenie cmdlet może przetwarzać dane wejściowe z komputera lokalnego na podstawie jawnych obiektów przekazanych do polecenia Get-Proc cmdlet. Opisane tutaj polecenie cmdlet pobiera procesy na podstawie ich nazw, a następnie wyświetla informacje o procesach Get-Proc w wierszu polecenia.

Definiowanie klasy polecenia cmdlet

Pierwszym krokiem tworzenia polecenia cmdlet jest nazewnictwo i deklaracja klasy .NET Framework, która implementuje polecenie cmdlet. To polecenie cmdlet pobiera informacje o procesie, więc nazwa czasownika wybrana w tym miejscu to "Pobierz". (Niemal każdy rodzaj polecenia cmdlet, które umożliwia pobieranie informacji, może przetwarzać dane wejściowe wiersza polecenia). Aby uzyskać więcej informacji na temat zatwierdzonych czasowników cmdlet, zobacz Nazwy czasowników polecenia cmdlet.

Oto deklaracja klasy dla Get-Proc polecenia cmdlet . Szczegółowe informacje o tej definicji znajdują się w te tematu Creating Your First Cmdlet (Tworzenie pierwszego polecenia cmdlet).

[Cmdlet(VerbsCommon.Get, "proc")]
public class GetProcCommand: Cmdlet

<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
    Inherits Cmdlet

Deklarowanie parametrów

Parametr polecenia cmdlet umożliwia użytkownikowi podanie danych wejściowych polecenia cmdlet. W poniższym przykładzie parametry i są nazwami Get-Proc Get-Member potokowych polecenia cmdlet oraz są parametrami polecenia MemberType Get-Member cmdlet . Parametr ma argument "property".

PS> get-proc; get-member -membertype, właściwość

Aby zadeklarować parametry dla polecenia cmdlet, należy najpierw zdefiniować właściwości, które reprezentują parametry. W poleceniach cmdlet jedynym parametrem jest , który w tym przypadku reprezentuje nazwę obiektu Get-Proc Name .NET Framework do pobrania. W związku z tym klasa polecenia cmdlet definiuje właściwość ciągu typu do akceptowania tablicy nazw.

Oto deklaracja parametru Name dla parametru Get-Proc polecenia cmdlet .

/// <summary>
/// Specify the cmdlet Name parameter.
/// </summary>
  [Parameter(Position = 0)]
  [ValidateNotNullOrEmpty]
  public string[] Name
  {
    get { return processNames; }
    set { processNames = value; }
  }
  private string[] processNames;

  #endregion Parameters

<Parameter(Position:=0), ValidateNotNullOrEmpty()> _
Public Property Name() As String()
    Get
        Return processNames
    End Get

    Set(ByVal value As String())
        processNames = value
    End Set

End Property

Aby poinformować środowisko Windows PowerShell, że ta właściwość jest parametrem, do definicji właściwości jest dodawany atrybut Name System.Management.Automation.Parameterattribute. Podstawowa składnia do deklarowania tego atrybutu to [Parameter()] .

Uwaga

Parametr musi być jawnie oznaczony jako publiczny. Parametry, które nie są oznaczone jako publiczne domyślne dla wewnętrznego i nie znajdują się w Windows PowerShell uruchomieniowym.

To polecenie cmdlet używa tablicy ciągów dla Name parametru . Jeśli to możliwe, polecenie cmdlet powinno również definiować parametr jako tablicę, ponieważ dzięki temu polecenie cmdlet może akceptować więcej niż jeden element.

Co należy zapamiętać o definicjach parametrów

Wstępnie zdefiniowane Windows PowerShell parametrów i typów danych powinny być używane ponownie w miarę możliwości, aby upewnić się, że polecenie cmdlet jest zgodne z Windows PowerShell cmdlet. Na przykład jeśli wszystkie polecenia cmdlet używają nazwy wstępnie zdefiniowanego parametru do identyfikowania zasobu, użytkownik będzie łatwo zrozumieć znaczenie parametru, niezależnie od tego, jakiego Id polecenia cmdlet używa. Zasadniczo nazwy parametrów są zgodne z tymi samymi regułami, które są używane dla nazw zmiennych w środowisku uruchomieniowym języka wspólnego (CLR). Aby uzyskać więcej informacji na temat nazewnictwa parametrów, zobacz Nazwy parametrów polecenia cmdlet.
Windows PowerShell rezerwuje kilka nazw parametrów, aby zapewnić spójne środowisko użytkownika. Nie używaj tych nazw parametrów: WhatIf , , , , , , , , Confirm i Verbose Debug Warn ErrorAction ErrorVariable OutVariable OutBuffer . Ponadto następujące aliasy dla tych nazw parametrów są zarezerwowane: vb , , , , i db ea ev ov ob .
Name jest prostą i typową nazwą parametru zalecaną do użycia w poleceniach cmdlet. Lepiej jest wybrać taką nazwę parametru niż nazwę złożoną, która jest unikatowa dla określonego polecenia cmdlet i trudna do zapamiętania.
W parametrach nie jest uwzględniania Windows PowerShell, chociaż domyślnie powłoka zachowuje literę. Wrażliwość argumentów na wielkości liter zależy od działania polecenia cmdlet . Argumenty są przekazywane do parametru określonego w wierszu polecenia.
Aby uzyskać przykłady innych deklaracji parametrów, zobacz Parametry polecenia cmdlet.

Deklarowanie parametrów jako pozytywnych lub nazwanych

Polecenie cmdlet musi ustawić każdy parametr jako parametr pozytowy lub nazwany. Oba rodzaje parametrów akceptują pojedyncze argumenty, wiele argumentów rozdzielonych przecinkami i ustawienia logiczne. Parametr logiczny, nazywany również przełącznikiem, obsługuje tylko ustawienia logiczne. Przełącznik służy do określania obecności parametru. Zalecana wartość domyślna to false .

Przykładowe Get-Proc polecenie cmdlet definiuje Name parametr jako parametr pozytowy z pozycją 0. Oznacza to, że pierwszy argument wprowadzony przez użytkownika w wierszu polecenia jest automatycznie wstawiany dla tego parametru. Jeśli chcesz zdefiniować nazwany parametr, dla którego użytkownik musi określić nazwę parametru z wiersza polecenia, pozostaw słowo kluczowe Position poza deklaracją atrybutu.

Uwaga

Jeśli parametry nie muszą być nazwane, zaleca się ustawić najczęściej używane parametry jako pozyacyjne, aby użytkownicy nie trzeba było wpisywać nazwy parametru.

Deklarowanie parametrów jako obowiązkowych lub opcjonalnych

Polecenie cmdlet musi ustawić każdy parametr jako opcjonalny lub obowiązkowy. W przykładowym cmdlet parametr jest zdefiniowany jako opcjonalny, ponieważ słowo kluczowe Get-Proc nie jest ustawione w deklaracji Name Mandatory atrybutu.

Obsługa walidacji parametrów

Przykładowe polecenie cmdlet dodaje atrybut weryfikacji danych wejściowych Get-Proc System.Management.Automation.Validatenotnulloremptyattributedo parametru , aby umożliwić sprawdzenie, czy dane wejściowe nie są ani puste, ani Name null puste. Ten atrybut jest jednym z kilku atrybutów weryfikacji dostarczonych przez Windows PowerShell. Aby uzyskać przykłady innych atrybutów walidacji, zobacz Sprawdzanie poprawności danych wejściowych parametru.

[Parameter(Position = 0)]
[ValidateNotNullOrEmpty]
public string[] Name

Zastępowanie metody przetwarzania danych wejściowych

Jeśli polecenie cmdlet ma obsługiwać dane wejściowe wiersza polecenia, musi zastąpić odpowiednie metody przetwarzania danych wejściowych. Podstawowe metody przetwarzania danych wejściowych zostały wprowadzone w tece Tworzenie pierwszego polecenia cmdlet.

Polecenie Get-Proc cmdlet zastępuje metodę System.Management.Automation.Cmdlet.ProcessRecord w celu obsługi danych wejściowych parametru dostarczonych przez użytkownika lub Name skrypt. Ta metoda pobiera procesy dla każdej nazwy żądanego procesu lub wszystkich procesów, jeśli nie podano nazwy. Zwróć uwagę, że w rekordach System.Management.Automation.Cmdlet.ProcessRecordwywołanie do system.Management.Automation.Cmdlet.WriteObject%28System.Object%2CSystem.Boolean%29 jest mechanizmem wyjściowym wysyłania obiektów wyjściowych do potoku. Drugi parametr tego wywołania, , jest ustawiony na , aby poinformować środowisko uruchomieniowe programu Windows PowerShell o wyliczaniu tablicy wyjściowej obiektów procesu i zapisywaniu po jednym procesie w enumerateCollection true wierszu polecenia.

protected override void ProcessRecord()
{
  // If no process names are passed to the cmdlet, get all processes.
  if (processNames == null)
  {
    // Write the processes to the pipeline making them available
    // to the next cmdlet. The second argument of this call tells
    // PowerShell to enumerate the array, and send one process at a
    // time to the pipeline.
    WriteObject(Process.GetProcesses(), true);
  }
  else
  {
    // If process names are passed to the cmdlet, get and write
    // the associated processes.
    foreach (string name in processNames)
    {
      WriteObject(Process.GetProcessesByName(name), true);
    }
  }
}

Protected Overrides Sub ProcessRecord()

    '/ If no process names are passed to the cmdlet, get all processes.
    If processNames Is Nothing Then
        Dim processes As Process()
        processes = Process.GetProcesses()
    End If

    '/ If process names are specified, write the processes to the
    '/ pipeline to display them or make them available to the next cmdlet.

    For Each name As String In processNames
        '/ The second parameter of this call tells PowerShell to enumerate the
        '/ array, and send one process at a time to the pipeline.
        WriteObject(Process.GetProcessesByName(name), True)
    Next

End Sub 'ProcessRecord

Przykład kodu

Aby uzyskać kompletny przykładowy kod w języku C#, zobacz GetProcessSample02 Sample (Przykład GetProcessSample02).

Definiowanie typów obiektów i formatowania

Windows PowerShell przekazuje informacje między poleceniami cmdlet przy użyciu .NET Framework obiektów. W związku z tym polecenie cmdlet może wymagać zdefiniowania własnego typu lub może być konieczne rozszerzenie istniejącego typu udostępnianego przez inne polecenie cmdlet. Aby uzyskać więcej informacji na temat definiowania nowych typów lub rozszerzania istniejących typów, zobacz Rozszerzanie typów obiektów i formatowanie.

Tworzenie polecenia cmdlet

Po zaimplementowaniu polecenia cmdlet należy zarejestrować je w Windows PowerShell przy użyciu Windows PowerShell przystawki. Aby uzyskać więcej informacji na temat rejestrowania cmdlet, zobacz Jak rejestrować polecenia cmdlet,dostawców i aplikacje hosta .

Testowanie polecenia cmdlet

Gdy polecenie cmdlet jest zarejestrowane w Windows PowerShell, możesz je przetestować, uruchamiając je w wierszu polecenia. Oto dwa sposoby testowania kodu dla przykładowego polecenia cmdlet. Aby uzyskać więcej informacji na temat używania poleceń cmdlet z wiersza polecenia, zobacz Wprowadzenie z Windows PowerShell.

W wierszu Windows PowerShell użyj następującego polecenia, aby wyświetlić listę procesu Internet Explorer o nazwie "IEXPLORE".

get-proc -name iexplore

Wyświetlone są następujące dane wyjściowe.

Handles  NPM(K)  PM(K)   WS(K)  VS(M)  CPU(s)   Id   ProcessName
-------  ------  -----   -----  -----   ------ --   -----------
    354      11  10036   18992    85   0.67   3284   iexplore

Aby wyświetlić listę Internet Explorer, Outlook i Notatnik o nazwach "IEXPLORE", "OUTLOOK" i "NOTEPAD", użyj następującego polecenia. Jeśli istnieje wiele procesów, zostaną wyświetlone wszystkie z nich.

get-proc -name iexplore, outlook, notepad

Wyświetlone są następujące dane wyjściowe.

Handles  NPM(K)  PM(K)   WS(K)  VS(M)  CPU(s)   Id   ProcessName
-------  ------  -----   -----  -----  ------   --   -----------
    732      21  24696    5000    138   2.25  2288   iexplore
    715      19  20556   14116    136   1.78  3860   iexplore
   3917      62  74096   58112    468 191.56  1848   OUTLOOK
     39       2   1024    3280     30   0.09  1444   notepad
     39       2   1024     356     30   0.08  3396   notepad