Tworzenie polecenia cmdlet bez parametrów

2025-03-25

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 polecenie cmdlet Get-Proc, 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 odwołań środowiska Windows PowerShell® są pobierane na dysk (domyślnie w folderze C:\Program Files\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0). Nie są one zainstalowane w globalnej pamięci podręcznej zestawów (GAC).

Nazywanie polecenia cmdlet

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

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

Wybieranie nounu

Należy wybrać wartość określoną dla konkretnej ciołki. Najlepiej używać pojedynczego afiksu nounowego z skróconą wersją nazwy produktu. Przykładowa nazwa polecenia cmdlet tego typu to "Get-SQLServer".

Wybieranie zlecenia

Należy użyć zlecenia z zestawu zatwierdzonych nazw czasowników poleceń cmdlet. Aby uzyskać więcej informacji na temat zatwierdzonych czasowników poleceń cmdlet, zobacz Cmdlet Verb Names.

Definiowanie klasy poleceń cmdlet

Po wybraniu nazwy polecenia cmdlet zdefiniuj klasę .NET w celu zaimplementowania polecenia cmdlet. Oto definicja klasy dla tego przykładowego polecenia cmdlet Get-Proc:

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

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

Zwróć uwagę, że poprzednia definicja klasy System.Management.Automation.CmdletAttribute atrybut z składnią [Cmdlet(verb, noun, ...)]służy do identyfikowania tej klasy jako polecenia cmdlet. Jest to jedyny wymagany atrybut dla wszystkich poleceń cmdlet i umożliwia środowisko uruchomieniowe programu Windows PowerShell poprawne wywołanie ich. W razie potrzeby możesz ustawić słowa kluczowe atrybutu, aby dodatkowo zadeklarować klasę. Należy pamiętać, że deklaracja atrybutu dla naszej przykładowej klasy GetProcCommand deklaruje tylko nazwy rzeczowników i czasowników dla polecenia cmdlet Get-Proc.

Uwaga

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

Podczas nazewnictwa klasy polecenia cmdlet warto odzwierciedlić nazwę polecenia cmdlet w nazwie klasy. W tym celu użyj formularza "VerbNounCommand" i zastąp ciąg "Verb" i "Noun" czasownikiem i nounem 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 podstawowej 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 podstawowej System.Management.Automation.PSCmdlet. Aby uzyskać więcej informacji na temat tej klasy, zobacz 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, będą domyślnie wewnętrznych i nie zostaną znalezione przez środowisko uruchomieniowe programu Windows PowerShell.

Program Windows PowerShell używa Microsoft.PowerShell.Commands przestrzeni nazw dla klas poleceń cmdlet. Zaleca się umieszczenie klas poleceń cmdlet w przestrzeni nazw Polecenia przestrzeni nazw interfejsu API, na przykład xxx.PS. Polecenia.

Zastępowanie metody przetwarzania wejściowego

Klasa System.Management.Automation.Cmdlet udostępnia trzy główne metody przetwarzania danych wejściowych, z których co najmniej jedno polecenie cmdlet musi zastąpić. Aby uzyskać więcej informacji na temat sposobu przetwarzania rekordów przez program Windows PowerShell, zobacz Jak działa program Windows PowerShell.

W przypadku wszystkich typów danych wejściowych środowisko uruchomieniowe programu Windows PowerShell wywołuje System.Management.Automation.Cmdlet.BeginProcessing w celu włączenia przetwarzania. Jeśli polecenie cmdlet musi wykonać wstępne przetwarzanie lub konfigurację, może to zrobić, przesłaniając tę metodę.

Uwaga

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

Jeśli polecenie cmdlet akceptuje dane wejściowe potoku, musi zastąpić metodę System.Management.Automation.Cmdlet.ProcessRecord oraz opcjonalnie metodę System.Management.Automation.Cmdlet.EndProcessing. Na przykład polecenie cmdlet może zastąpić obie metody, jeśli zbiera wszystkie dane wejściowe przy użyciu System.Management.Automation.Cmdlet.ProcessRecord, a następnie działa na danych wejściowych jako całości, a nie na jednym elemecie jednocześnie, jak to robi polecenie cmdlet Sort-Object.

Jeśli polecenie cmdlet nie pobiera 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 zamiast System.Management.Automation.Cmdlet.BeginProcessing, gdy polecenie cmdlet nie może działać na jednym elemenie jednocześnie, podobnie 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 System.Management.Automation.Cmdlet.BeginProcessing i System.Management.Automation.Cmdlet.EndProcessing. System.Management.Automation.Cmdlet.ProcessRecord zastępuje 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) udostępniany przez użytkownika w wierszu polecenia. Aby uzyskać więcej informacji, zobacz Creating a Cmdlet to Process Command Line Input.
Metoda przetwarzania wejściowego może również odbierać dane wejściowe z obiektu wyjściowego nadrzędnego polecenia cmdlet w potoku. Aby uzyskać więcej informacji, zobacz Tworzenie polecenia cmdlet do przetwarzania danych wejściowych potoku. Pamiętaj, że polecenie cmdlet może odbierać dane wejściowe z kombinacji źródeł wiersza polecenia i potoku.
Polecenie cmdlet podrzędne może nie zwracać przez długi czas lub w ogóle nie. Z tego powodu metoda przetwarzania danych wejściowych w poleceniu cmdlet nie powinna przechowywać blokad podczas wywołań do System.Management.Automation.Cmdlet.WriteObject, szczególnie blokady, dla których zakres wykracza poza wystąpienie polecenia cmdlet.

Ważne

Polecenia cmdlet nigdy nie powinny wywoływać System.Console.Writeline* lub jego odpowiednik.

Polecenie cmdlet może mieć zmienne obiektu do czyszczenia po zakończeniu przetwarzania (na przykład jeśli otworzy dojście do pliku w System.Management.Automation.Cmdlet.BeginProcessing metody i utrzymuje otwarte dojście do użycia przez System.Management.Automation.Cmdlet.ProcessRecord). Należy pamiętać, że środowisko uruchomieniowe programu Windows PowerShell nie zawsze wywołuje metodę System.Management.Automation.Cmdlet.EndProcessing, która powinna wykonywać oczyszczanie obiektów.

Na przykład System.Management.Automation.Cmdlet.EndProcessing może nie być wywoływana, jeśli polecenie cmdlet zostanie anulowane w połowie lub jeśli w jakiejkolwiek części polecenia cmdlet wystąpi błąd zakończenia. W związku z tym polecenie cmdlet wymagające oczyszczania obiektów powinno zaimplementować kompletny wzorzec System.IDisposable, w tym finalizator, tak aby środowisko uruchomieniowe może wywoływać zarówno System.Management.Automation.Automation.Cmdlet.EndProcessing, jak i System.IDisposable.Dispose* na końcu przetwarzania.

Przykładowy kod

Aby uzyskać pełny przykładowy kod w języku C#, zobacz GetProcessSample01 Sample.

Definiowanie typów obiektów i formatowanie

Program Windows PowerShell przekazuje informacje między poleceniami cmdlet przy użyciu obiektów .NET. W związku z tym może być konieczne zdefiniowanie własnego typu polecenia cmdlet 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.

Kompilowanie polecenia cmdlet

Po zaimplementowaniu polecenia cmdlet należy zarejestrować je w programie Windows PowerShell za pomocą przystawki programu Windows PowerShell. Aby uzyskać więcej informacji na temat rejestrowania poleceń cmdlet, zobacz Jak rejestrować polecenia cmdlet, dostawcy i aplikacje hosta.

Testowanie polecenia cmdlet

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

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

Get-Proc

Zostanie wyświetlone 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
...

Przypisz zmienną do wyników polecenia cmdlet, aby ułatwić manipulowanie.
```
$p=Get-Proc
```
Pobierz liczbę procesów.
```
$p.Length
```
Zostanie wyświetlone następujące dane wyjściowe.
```
63
```

Pobieranie określonego procesu.

$p[6]

Zostanie wyświetlone 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

Uzyskaj godzinę rozpoczęcia tego procesu.
```
$p[6].StartTime
```
Zostanie wyświetlone następujące dane wyjściowe.
```
Tuesday, July 26, 2005 9:34:15 AM
```
```
$p[6].StartTime.DayOfYear
```
```
207
```

Pobierz procesy, dla których liczba dojść jest większa niż 500, i posortuj wynik.

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

Zostanie wyświetlone 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
...

Użyj polecenia cmdlet Get-Member, aby wyświetlić listę właściwości dostępnych dla każdego procesu.

$p | Get-Member -MemberType Property

    TypeName: System.Diagnostics.Process

Zostanie wyświetlone 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...
...