Tworzenie polecenia cmdlet bez parametrów

W tej sekcji opisano sposób tworzenia polecenia cmdlet, które pobiera informacje z komputera lokalnego bez użycia parametrów, a następnie zapisuje informacje w potoku. Opisane tutaj polecenie cmdlet to Get-Proc cmdlet, które pobiera informacje o procesach komputera lokalnego, a następnie wyświetla te informacje w wierszu polecenia.

Uwaga

Należy pamiętać, że podczas pisania poleceń cmdlet zestawy referencyjne programu Windows PowerShell® są pobierane na dysk (domyślnie w folderze C:\Program Files\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0). Nie są one instalowane w globalnej pamięci podręcznej zestawów (GAC).

Nazywanie polecenia cmdlet

Nazwa polecenia cmdlet składa się z czasownika wskazującego akcję, która przyjmuje polecenie cmdlet, oraz rzeczownika wskazującego elementy, na których działa polecenie cmdlet. Ponieważ to przykładowe polecenie cmdlet Get-Proc pobiera obiekty procesu, używa czasownika "Get", zdefiniowanego przez wyliczenie System.Management.Automation.Verbscommon, oraz rzeczownika "Proc", aby wskazać, że polecenie cmdlet działa na elementach procesu.

Podczas nazywania cmdlet nie należy używać żadnego z następujących znaków: # , () {} [] & - /\ $ ; : " '<> | ? @ ` .

Wybieranie rzeczownika

Należy wybrać rzeczownik, który jest specyficzny. Najlepiej jest użyć rzeczownika pojedynczej poprzedzonego skróconą wersją nazwy produktu. Przykładowa nazwa polecenia cmdlet tego typu to " Get-SQLServer ".

Wybieranie zlecenia

Należy użyć czasownika z zestawu zatwierdzonych nazw czasowników polecenia cmdlet. Aby uzyskać więcej informacji na temat zatwierdzonych czasowników cmdlet, zobacz Nazwy czasowników polecenia cmdlet.

Definiowanie klasy polecenia cmdlet

Po wybraniu nazwy polecenia cmdlet zdefiniuj klasę .NET, aby zaimplementować polecenie cmdlet. Oto definicja klasy dla tego przykładowego Get-Proc cmdlet:

[Cmdlet(VerbsCommon.Get, "Proc")]
  public class GetProcCommand : Cmdlet
<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
    Inherits Cmdlet

Zwróć uwagę, że przed definicją klasy atrybut System.Management.Automation.CmdletAttribute o składni jest używany do identyfikowania tej klasy jako [Cmdlet(verb, noun, ...)] polecenia cmdlet. Jest to jedyny wymagany atrybut dla wszystkich polecenia cmdlet i umożliwia środowisku uruchomieniowemu Windows PowerShell prawidłowe ich wywołanie. Możesz ustawić słowa kluczowe atrybutu, aby dodatkowo zadeklarować klasę w razie potrzeby. Należy pamiętać, że deklaracja atrybutu dla naszej przykładowej klasy GetProcCommand deklaruje tylko nazwy rzeczowników i czasowników dla Get-Proc cmdlet.

Uwaga

Dla wszystkich Windows PowerShell atrybutów słowa kluczowe, które można ustawić, odpowiadają właściwościom klasy atrybutów.

Podczas nazywania klasy polecenia cmdlet dobrym rozwiązaniem jest odzwierciedlenie nazwy polecenia cmdlet w nazwie klasy. Aby to zrobić, należy użyć formularza "VerbNounCommand" i zastąpić "Czasownik" i "Rzeczownik" czasownikiem i rzeczownikiem używanym w nazwie polecenia cmdlet. Jak pokazano w poprzedniej definicji klasy, przykładowe polecenie cmdlet Get-Proc definiuje klasę o nazwie GetProcCommand, która pochodzi z klasy bazowej System.Management.Automation.Cmdlet.

Ważne

Jeśli chcesz zdefiniować polecenie cmdlet, które uzyskuje bezpośredni dostęp do środowiska uruchomieniowego programu Windows PowerShell, klasa .NET powinna pochodzić z klasy bazowej System.Management.Automation.PSCmdlet. Aby uzyskać więcej informacji na temat tej klasy, zobacz Creating a Cmdlet that Defines Parameter Sets (Tworzenie polecenia cmdlet definiującego zestawy parametrów).

Uwaga

Klasa polecenia cmdlet musi być jawnie oznaczona jako publiczna. Klasy, które nie są oznaczone jako publiczne, zostaną domyślnie oznaczone jako wewnętrzne i nie zostaną znalezione przez Windows PowerShell uruchomieniowe.

Windows PowerShell używa przestrzeni nazw Microsoft.PowerShell.Commands dla swoich klas poleceń cmdlet. Zaleca się umieścić klasy poleceń cmdlet w przestrzeni nazw Poleceń przestrzeni nazw interfejsu API, na przykład xxx.PS.Commands.

Zastępowanie metody przetwarzania danych wejściowych

Klasa System.Management.Automation.Cmdlet udostępnia trzy główne metody przetwarzania danych wejściowych, z których co najmniej jedna musi zostać przesłoniona przez polecenie cmdlet. Aby uzyskać więcej informacji na temat sposobu Windows PowerShell rekordów, zobacz How Windows PowerShell Works.

W przypadku wszystkich typów danych wejściowych środowisko uruchomieniowe Windows PowerShell System.Management.Automation.Cmdlet.BeginProcessing w celu włączenia przetwarzania. Jeśli polecenie cmdlet musi wykonać przetwarzanie wstępne lub konfigurację, można to zrobić przez zastąpienie tej metody.

Uwaga

Windows PowerShell używa terminu "rekord" do opisania zestawu wartości parametrów podanych podczas wywoływania polecenia cmdlet.

Jeśli polecenie cmdlet akceptuje dane wejściowe potoku, musi zastąpić metodę System.Management.Automation.Cmdlet.ProcessRecord i opcjonalnie metodę System.Management.Automation.Cmdlet.EndProcessing. Na przykład polecenie cmdlet może przesłonić obie metody, jeśli zbierze wszystkie dane wejściowe przy użyciu elementu System.Management.Automation.Cmdlet.ProcessRecord, a następnie będzie działać na danych wejściowych jako całość, a nie na jednym elemencie jednocześnie, tak jak polecenie Sort-Object cmdlet.

Jeśli polecenie cmdlet nie bierze danych wejściowych potoku, powinno zastąpić metodę System.Management.Automation.Cmdlet.EndProcessing. Należy pamiętać, że ta metoda jest często używana w miejsce elementu System.Management.Automation.Cmdlet.BeginProcessing, gdy polecenie cmdlet nie może jednocześnie działać na jednym elemencie, tak jak w przypadku polecenia cmdlet sortowania.

Ponieważ to przykładowe polecenie cmdlet Get-Proc musi odbierać dane wejściowe potoku, zastępuje metodę System.Management.Automation.Cmdlet.ProcessRecord i używa domyślnych implementacji dla systemów System.Management.Automation.Cmdlet.BeginProcessing i System.Management.Automation.Cmdlet.EndProcessing. Przesłonięcie System.Management.Automation.Cmdlet.ProcessRecord pobiera procesy i zapisuje je w wierszu polecenia przy użyciu metody System.Management.Automation.Cmdlet.WriteObject.

protected override void ProcessRecord()
{
  // Get the current processes
  Process[] processes = Process.GetProcesses();

  // Write the processes to the pipeline making them available
  // to the next cmdlet. The second parameter of this call tells
  // PowerShell to enumerate the array, and send one process at a
  // time to the pipeline.
  WriteObject(processes, true);
}
Protected Overrides Sub ProcessRecord()

    '/ Get the current processes.
    Dim processes As Process()
    processes = Process.GetProcesses()

    '/ Write the processes to the pipeline making them available
    '/ to the next cmdlet. The second parameter of this call tells
    '/ PowerShell to enumerate the array, and send one process at a
    '/ time to the pipeline.
    WriteObject(processes, True)

End Sub 'ProcessRecord

Co należy pamiętać o przetwarzaniu danych wejściowych

  • Domyślnym źródłem danych wejściowych jest jawny obiekt (na przykład ciąg) dostarczony przez użytkownika w wierszu polecenia. Aby uzyskać więcej informacji, zobacz Creating a Cmdlet to Process Command Line Input (Tworzenie polecenia cmdlet do przetwarzania danych wejściowych wiersza polecenia).

  • Metoda przetwarzania danych wejściowych może również odbierać dane wejściowe z obiektu wyjściowego nadrzędnego polecenia cmdlet w potoku. Aby uzyskać więcej informacji, zobacz Creating a Cmdlet to Process Pipeline Input (Tworzenie polecenia cmdlet do przetwarzania danych wejściowych potoku). Należy pamiętać, że polecenie cmdlet może odbierać dane wejściowe z kombinacji źródeł wiersza polecenia i potoku.

  • Podrzędne polecenie cmdlet może nie zwracać się przez długi czas lub w ogóle nie. Z tego powodu metoda przetwarzania danych wejściowych w poleceńce cmdlet nie powinna przechowywać blokad podczas wywołań do obiektu System.Management.Automation.Cmdlet.WriteObject,szczególnie blokad, dla których zakres wykracza poza wystąpienie polecenia cmdlet.

Ważne

Polecenia cmdlet nigdy nie powinny wywołać polecenia System.Console.Writeline* ani jego odpowiednika.

Na przykład system.Management.Automation.Cmdlet.EndProcessing może nie zostać wywołany, jeśli polecenie cmdlet zostanie anulowane w połowie lub jeśli w dowolnej części polecenia cmdlet wystąpi błąd zakończenia. W związku z tym polecenie cmdlet wymagające oczyszczania obiektu powinno implementować kompletny wzorzec System.IDisposable, w tym finalizator, dzięki czemu środowisko uruchomieniowe może wywołać zarówno System.Management.Automation.Cmdlet.EndProcessing, jak i System.IDisposable.Dispose* na końcu przetwarzania.

Przykład kodu

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

Definiowanie typów obiektów i formatowania

Windows PowerShell przekazuje informacje między poleceniami cmdlet przy użyciu obiektów .NET. W związku z tym polecenie cmdlet może wymagać zdefiniowania własnego typu lub może być konieczne rozszerzenie istniejącego typu dostarczonego 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 za pośrednictwem 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

Po zarejestrowaniu polecenia cmdlet w Windows PowerShell można je przetestować, uruchamiając je w wierszu polecenia. Kod naszego przykładowego polecenia cmdlet Get-Proc jest mały, ale nadal używa środowiska uruchomieniowego Windows PowerShell i istniejącego obiektu .NET, co wystarczy, aby było przydatne. Przetestujmy go, aby lepiej zrozumieć, co Get-Proc i jak można używać jego danych wyjściowych. Aby uzyskać więcej informacji na temat używania poleceń cmdlet z wiersza polecenia, zobacz Wprowadzenie zWindows PowerShell .

  1. Uruchom Windows PowerShell i pobierz bieżące procesy uruchomione na komputerze.

    get-proc
    

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

    Handles  NPM(K)  PM(K)  WS(K)  VS(M)  CPU(s)  Id   ProcessName
    -------  ------  -----  -----  -----  ------  --   ----------
    254      7       7664   12048  66     173.75  1200  QCTRAY
    32       2       1372   2628   31       0.04  1860  DLG
    271      6       1216   3688   33       0.03  3816  lg
    27       2       560    1920   24       0.01  1768  TpScrex
    ...
    
  2. Przypisz zmienną do wyników polecenia cmdlet, aby ułatwić manipulowanie nimi.

    $p=get-proc
    
  3. Pobierz liczbę procesów.

    $p.length
    

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

    63
    
  4. Pobieranie określonego procesu.

    $p[6]
    

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

    Handles  NPM(K)  PM(K)  WS(K)  VS(M)  CPU(s)  Id    ProcessName
    -------  ------  -----  -----  -----  ------  --    -----------
    1033     3       2400   3336   35     0.53    1588  rundll32
    
  5. Pobierz czas rozpoczęcia tego procesu.

    $p[6].starttime
    

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

    Tuesday, July 26, 2005 9:34:15 AM
    
    $p[6].starttime.dayofyear
    
    207
    
  6. Pobierz procesy, dla których liczba dojścia jest większa niż 500, i posortuj wynik.

    $p | Where-Object {$_.HandleCount -gt 500 } | Sort-Object HandleCount
    

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

    Handles  NPM(K)  PM(K)  WS(K)  VS(M)  CPU(s)  Id   ProcessName
    -------  ------  -----  -----  -----  ------  --   ----------
    568      14      2164   4972   39     5.55    824  svchost
    716       7      2080   5332   28    25.38    468  csrss
    761      21      33060  56608  440  393.56    3300 WINWORD
    791      71      7412   4540   59     3.31    492  winlogon
    ...
    
  7. Użyj polecenia Get-Member cmdlet , aby wyświetlić listę właściwości dostępnych dla każdego procesu.

    $p | Get-Member -MemberType property
    
        TypeName: System.Diagnostics.Process
    

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

    Name                     MemberType Definition
    ----                     ---------- ----------
    BasePriority             Property   System.Int32 BasePriority {get;}
    Container                Property   System.ComponentModel.IContainer Conta...
    EnableRaisingEvents      Property   System.Boolean EnableRaisingEvents {ge...
    ...
    

Zobacz też

Tworzenie polecenia cmdlet do przetwarzania danych wejściowych wiersza polecenia

Tworzenie polecenia cmdlet do przetwarzania danych wejściowych potoku

How to Create a Windows PowerShell Cmdlet (Jak utworzyć Windows PowerShell cmdlet)

Rozszerzanie typów obiektów i formatowanie

Jak Windows PowerShell działa

Jak rejestrować polecenia cmdlet, dostawców i aplikacje hosta

Dokumentacja programu Windows PowerShell

Przykłady poleceń cmdlet