Polecenia cmdlet — omówienieCmdlet Overview

Polecenie cmdlet jest lekkim poleceniem, które jest używane w środowisku programu PowerShell.A cmdlet is a lightweight command that is used in the PowerShell environment. Środowisko uruchomieniowe programu PowerShell wywołuje te polecenia cmdlet w kontekście skryptów automatyzacji, które są dostępne w wierszu polecenia.The PowerShell runtime invokes these cmdlets within the context of automation scripts that are provided at the command line. Środowisko uruchomieniowe programu PowerShell również wywołuje je programowo za pomocą interfejsów API programu PowerShell.The PowerShell runtime also invokes them programmatically through PowerShell APIs.

Polecenia cmdletCmdlets

Polecenia cmdlet wykonują akcję i zwykle zwracają obiekt Microsoft .NET do następnego polecenia w potoku.Cmdlets perform an action and typically return a Microsoft .NET object to the next command in the pipeline. Polecenie cmdlet to pojedyncze polecenie, które uczestniczy w semantyce potoku programu PowerShell.A cmdlet is a single command that participates in the pipeline semantics of PowerShell. Obejmuje to binarne polecenia cmdlet (C#), zaawansowane funkcje skryptu, CDXML i przepływy pracy.This includes binary (C#) cmdlets, advanced script functions, CDXML, and Workflows.

Ta dokumentacja zestawu SDK zawiera opis sposobu tworzenia binarnych poleceń cmdlet, które są zapisywane w języku C#.This SDK documentation describes how to create binary cmdlets written in C#. Aby uzyskać informacje na temat poleceń cmdlet opartych na skryptach, zobacz:For information about script-based cmdlets, see:

Aby utworzyć binarne polecenie cmdlet, należy zaimplementować klasę poleceń cmdlet, która dziedziczy z jednej z dwóch wyspecjalizowanych klas podstawowych poleceń cmdlet.To create a binary cmdlet, you must implement a cmdlet class that derives from one of two specialized cmdlet base classes. Klasa pochodna musi:The derived class must:

  • Zadeklaruj atrybut, który identyfikuje klasę pochodną jako polecenie cmdlet.Declare an attribute that identifies the derived class as a cmdlet.
  • Definiowanie właściwości publicznych, które są uzupełnione atrybutami, które identyfikują właściwości publiczne jako parametry poleceń cmdlet.Define public properties that are decorated with attributes that identify the public properties as cmdlet parameters.
  • Zastąp jedną lub więcej metod przetwarzania danych wejściowych w celu przetworzenia rekordów.Override one or more of the input processing methods to process records.

Zestaw, który zawiera klasę, można załadować bezpośrednio przy użyciu polecenia cmdlet Import-Module lub można utworzyć aplikację hosta ładującą zestaw za pomocą interfejsu API System.Management.Automation.Runspaces.Initialsessionstate .You can load the assembly that contains the class directly by using the Import-Module cmdlet, or you can create a host application that loads the assembly by using the System.Management.Automation.Runspaces.Initialsessionstate API. Obie metody zapewniają programowy i dostęp do funkcji polecenia cmdlet w wierszu polecenia.Both methods provide programmatic and command-line access to the functionality of the cmdlet.

Warunki polecenia cmdletCmdlet Terms

Poniższe terminy są często używane w dokumentacji poleceń cmdlet programu PowerShell:The following terms are used frequently in the PowerShell cmdlet documentation:

Cmdlet — atrybutCmdlet attribute

Atrybut platformy .NET, który jest używany do deklarowania klasy polecenia cmdlet jako polecenia cmdlet.A .NET attribute that is used to declare a cmdlet class as a cmdlet. Chociaż program PowerShell używa kilku innych atrybutów, które są opcjonalne, wymagany jest atrybut cmdlet.Although PowerShell uses several other attributes that are optional, the Cmdlet attribute is required. Aby uzyskać więcej informacji na temat tego atrybutu, zobacz polecenie cmdlet Attribute deklaracji.For more information about this attribute, see Cmdlet Attribute Declaration.

Parametr polecenia cmdletCmdlet parameter

Właściwości publiczne, które definiują parametry dostępne dla użytkownika lub aplikacji, na których działa polecenie cmdlet.The public properties that define the parameters that are available to the user or to the application that is running the cmdlet. Polecenia cmdlet mogą mieć wymagane, nazwane, pozycyjne i parametry przełącznika .Cmdlets can have required, named, positional, and switch parameters. Parametry przełącznika umożliwiają definiowanie parametrów, które są oceniane tylko wtedy, gdy parametry są określone w wywołaniu.Switch parameters allow you to define parameters that are evaluated only if the parameters are specified in the call. Aby uzyskać więcej informacji na temat różnych typów parametrów, zobacz Parametry poleceń cmdlet.For more information about the different types of parameters, see Cmdlet Parameters.

Zestaw parametrówParameter set

Grupa parametrów, które mogą być używane w tym samym poleceniu, aby wykonać konkretną akcję.A group of parameters that can be used in the same command to perform a specific action. Polecenie cmdlet może mieć wiele zestawów parametrów, ale każdy zestaw parametrów musi mieć co najmniej jeden parametr, który jest unikatowy.A cmdlet can have multiple parameter sets, but each parameter set must have at least one parameter that is unique. Dobry projekt polecenia cmdlet jest silnie sugerujący, że unikatowy parametr również jest wymaganym parametrem.Good cmdlet design strongly suggests that the unique parameter also be a required parameter. Aby uzyskać więcej informacji na temat zestawów parametrów, zobacz zestawy parametrów poleceń cmdlet.For more information about parameter sets, see Cmdlet Parameter Sets.

Parametr dynamicznyDynamic parameter

Parametr, który jest dodawany do polecenia cmdlet w czasie wykonywania.A parameter that is added to the cmdlet at runtime. Zwykle parametry dynamiczne są dodawane do polecenia cmdlet, gdy inny parametr ma określoną wartość.Typically, the dynamic parameters are added to the cmdlet when another parameter is set to a specific value. Aby uzyskać więcej informacji na temat parametrów dynamicznych, zobacz parametry dynamiczne poleceń cmdlet.For more information about dynamic parameters, see Cmdlet Dynamic Parameters.

Metody przetwarzania danych wejściowychInput processing methods

Klasa System. Management. Automation. cmdlet udostępnia następujące metody wirtualne, które są używane do przetwarzania rekordów.The System.Management.Automation.Cmdlet class provides the following virtual methods that are used to process records. Wszystkie pochodne klasy poleceń cmdlet muszą przesłaniać co najmniej jedną z pierwszych trzech metod:All the derived cmdlet classes must override one or more of the first three methods:

Aby uzyskać więcej informacji na temat tych metod, zobacz metody przetwarzania danych wejściowych poleceń cmdlet.For more information about these methods, see Cmdlet Input Processing Methods.

Podczas implementowania polecenia cmdlet należy zastąpić co najmniej jedną z tych metod przetwarzania danych wejściowych.When you implement a cmdlet, you must override at least one of these input processing methods. Zazwyczaj ProcessRecord () to metoda, która została przesłonięta, ponieważ jest wywoływana dla każdego rekordu, który przetwarza polecenie cmdlet.Typically, the ProcessRecord() is the method that you override because it is called for every record that the cmdlet processes. Z kolei Metoda BeginProcessing () i Metoda EndProcessing () są wywoływane jednokrotnie w celu przeprowadzenia wstępnego przetwarzania lub przetworzenia rekordów.In contrast, the BeginProcessing() method and the EndProcessing() method are called one time to perform pre-processing or post-processing of the records. Aby uzyskać więcej informacji na temat tych metod, zobacz metody przetwarzania danych wejściowych.For more information about these methods, see Input Processing Methods.

Funkcja ShouldProcessShouldProcess feature

Program PowerShell umożliwia tworzenie poleceń cmdlet, które monitują użytkownika o opinię, zanim polecenie cmdlet dokona zmiany w systemie.PowerShell allows you to create cmdlets that prompt the user for feedback before the cmdlet makes a change to the system. Aby użyć tej funkcji, polecenie cmdlet musi deklarować, że obsługuje ShouldProcess funkcję przy deklarowaniu atrybutu polecenia cmdlet, a polecenie cmdlet musi wywołać metody System. Management. Automation. cmdlet. ShouldProcess i System. Management. Automation. cmdlet. ShouldContinue z metody przetwarzania danych wejściowych.To use this feature, the cmdlet must declare that it supports the ShouldProcess feature when you declare the Cmdlet attribute, and the cmdlet must call the System.Management.Automation.Cmdlet.ShouldProcess and System.Management.Automation.Cmdlet.ShouldContinue methods from within an input processing method. Aby uzyskać więcej informacji na temat obsługi ShouldProcess funkcji, zobacz żądanie potwierdzenia.For more information about how to support the ShouldProcess functionality, see Requesting Confirmation.

TransakcjaTransaction

Logiczna Grupa poleceń, które są traktowane jako pojedyncze zadanie.A logical group of commands that are treated as a single task. Zadanie automatycznie kończy się niepowodzeniem w przypadku niepowodzenia jakiegokolwiek polecenia w grupie, a użytkownik może zaakceptować lub odrzucić akcje wykonywane w ramach transakcji.The task automatically fails if any command in the group fails, and the user has the choice to accept or reject the actions performed within the transaction. Aby wziąć udział w transakcji, polecenie cmdlet musi deklarować, że obsługuje transakcje, gdy atrybut cmdlet jest zadeklarowany.To participate in a transaction, the cmdlet must declare that it supports transactions when the Cmdlet attribute is declared. Obsługa transakcji została wprowadzona w programie Windows PowerShell 2,0.Support for transactions was introduced in Windows PowerShell 2.0. Aby uzyskać więcej informacji o transakcjach, zobacz How to support Transactions.For more information about transactions, see How to Support Transactions.

Jak polecenia cmdlet różnią się od poleceńHow Cmdlets Differ from Commands

Polecenia cmdlet różnią się od poleceń w innych środowiskach powłoki poleceń w następujący sposób:Cmdlets differ from commands in other command-shell environments in the following ways:

  • Polecenia cmdlet są wystąpieniami klas .NET; nie są to autonomiczne pliki wykonywalne.Cmdlets are instances of .NET classes; they are not stand-alone executables.
  • Polecenia cmdlet mogą być tworzone z kilku wierszy kodu.Cmdlets can be created from as few as a dozen lines of code.
  • Polecenia cmdlet nie zwykle wykonują własnych analiz, prezentacji błędów ani formatowania danych wyjściowych.Cmdlets do not generally do their own parsing, error presentation, or output formatting. Analizowanie, prezentacja błędów i formatowanie danych wyjściowych są obsługiwane przez środowisko uruchomieniowe programu PowerShell.Parsing, error presentation, and output formatting are handled by the PowerShell runtime.
  • Polecenia cmdlet przetwarzają obiekty wejściowe z potoku, a nie ze strumieni tekstu, a polecenia cmdlet zazwyczaj dostarczają obiekty jako dane wyjściowe do potoku.Cmdlets process input objects from the pipeline rather than from streams of text, and cmdlets typically deliver objects as output to the pipeline.
  • Polecenia cmdlet są zorientowane na rekordy, ponieważ przetwarzają pojedynczy obiekt w danym momencie.Cmdlets are record-oriented because they process a single object at a time.

Klasy bazowe poleceń cmdletCmdlet Base Classes

Program Windows PowerShell obsługuje polecenia cmdlet, które pochodzą z następujących dwóch klas podstawowych.Windows PowerShell supports cmdlets that are derived from the following two base classes.

  • Większość poleceń cmdlet jest opartych na klasach .NET, które pochodzą z klasy podstawowej System. Management. Automation. cmdlet .Most cmdlets are based on .NET classes that derive from the System.Management.Automation.Cmdlet base class. Wyprowadzanie z tej klasy umożliwia poleceniem cmdlet użycie minimalnego zestawu zależności w środowisku uruchomieniowym środowiska Windows PowerShell.Deriving from this class allows a cmdlet to use the minimum set of dependencies on the Windows PowerShell runtime. Ma to dwie korzyści.This has two benefits. Pierwsza korzyść polega na tym, że obiekty poleceń cmdlet są mniejsze i prawdopodobnie mają wpływ na zmiany środowiska uruchomieniowego programu PowerShell.The first benefit is that the cmdlet objects are smaller, and you are less likely to be affected by changes to the PowerShell runtime. Druga korzyść polega na tym, że w razie potrzeby można bezpośrednio utworzyć wystąpienie obiektu polecenia cmdlet, a następnie wywołać je bezpośrednio zamiast wywoływania go za pomocą środowiska uruchomieniowego programu PowerShell.The second benefit is that, if you have to, you can directly create an instance of the cmdlet object and then invoke it directly instead of invoking it through the PowerShell runtime.

  • Bardziej złożone polecenia cmdlet są oparte na klasach .NET, które pochodzą z klasy podstawowej System. Management. Automation. PSCmdlet .The more-complex cmdlets are based on .NET classes that derive from the System.Management.Automation.PSCmdlet base class. Wyprowadzanie z tej klasy zapewnia znacznie większy dostęp do środowiska uruchomieniowego programu PowerShell.Deriving from this class gives you much more access to the PowerShell runtime. Ten dostęp umożliwia poleceniu cmdlet Wywoływanie skryptów, dostęp do dostawców i dostęp do bieżącego stanu sesji.This access allows your cmdlet to call scripts, to access providers, and to access the current session state. (Aby uzyskać dostęp do bieżącego stanu sesji, uzyskasz i ustawiasz zmienne sesji i preferencje). Jednak wyprowadzanie z tej klasy zwiększa rozmiar obiektu polecenia cmdlet i oznacza, że polecenie cmdlet jest bardziej ściśle powiązane z bieżącą wersją środowiska uruchomieniowego programu PowerShell.(To access the current session state, you get and set session variables and preferences.) However, deriving from this class increases the size of the cmdlet object, and it means that your cmdlet is more tightly coupled to the current version of the PowerShell runtime.

Ogólnie rzecz biorąc, jeśli nie potrzebujesz rozszerzonego dostępu do środowiska uruchomieniowego programu PowerShell, należy utworzyć wynik z klasy System. Management. Automation. cmdlet .In general, unless you need the extended access to the PowerShell runtime, you should derive from the System.Management.Automation.Cmdlet class. Jednak środowisko uruchomieniowe programu PowerShell ma szerokie możliwości rejestrowania na potrzeby wykonywania poleceń cmdlet.However, the PowerShell runtime has extensive logging capabilities for the execution of cmdlets. Jeśli model inspekcji zależy od tego rejestrowania, można zapobiec wykonaniu polecenia cmdlet z innego polecenia cmdlet, pobierając z klasy System. Management. Automation. PSCmdlet .If your auditing model depends on this logging, you can prevent the execution of your cmdlet from within another cmdlet by deriving from the System.Management.Automation.PSCmdlet class.

Atrybuty poleceń cmdletCmdlet Attributes

Program PowerShell definiuje kilka atrybutów platformy .NET, które są używane do zarządzania poleceniami cmdlet i określania typowych funkcji zapewnianych przez program PowerShell, które mogą być wymagane przez polecenie cmdlet.PowerShell defines several .NET attributes that are used to manage cmdlets and to specify common functionality that is provided by PowerShell and that might be required by the cmdlet. Na przykład atrybuty są używane do wyznaczania klasy jako polecenia cmdlet, do określenia parametrów polecenia cmdlet i żądania walidacji danych wejściowych, aby deweloperzy poleceń cmdlet nie musieli implementować tej funkcji w kodzie poleceń cmdlet.For example, attributes are used to designate a class as a cmdlet, to specify the parameters of the cmdlet, and to request the validation of input so that cmdlet developers do not have to implement that functionality in their cmdlet code. Aby uzyskać więcej informacji na temat atrybutów, zobacz atrybuty programu PowerShell.For more information about attributes, see PowerShell Attributes.

Nazwy poleceń cmdletCmdlet Names

Program PowerShell używa pary nazw czasownik-and-rzeczownik do nazwy poleceń cmdlet.PowerShell uses a verb-and-noun name pair to name cmdlets. Na przykład Get-Command polecenie cmdlet zawarte w programie PowerShell służy do pobierania wszystkich poleceń cmdlet, które są zarejestrowane w powłoce poleceń.For example, the Get-Command cmdlet included in PowerShell is used to get all the cmdlets that are registered in the command shell. Zlecenie identyfikuje akcję wykonywaną przez polecenie cmdlet, a rzeczownik identyfikuje zasób, na którym wykonuje akcję polecenie cmdlet.The verb identifies the action that the cmdlet performs, and the noun identifies the resource on which the cmdlet performs its action.

Te nazwy są określane, gdy Klasa .NET jest zadeklarowana jako polecenie cmdlet.These names are specified when the .NET class is declared as a cmdlet. Aby uzyskać więcej informacji na temat sposobu deklarowania klasy .NET jako polecenia cmdlet, zobacz polecenie cmdlet Attribute deklaracji.For more information about how to declare a .NET class as a cmdlet, see Cmdlet Attribute Declaration.

Pisanie kodu polecenia cmdletWriting Cmdlet Code

Ten dokument zawiera dwa sposoby, aby poznać sposób pisania kodu poleceń cmdlet.This document provides two ways to discover how cmdlet code is written. Jeśli wolisz zobaczyć kod bez wyjaśnień, zobacz przykłady kodu poleceń cmdlet.If you prefer to see the code without much explanation, see Examples of Cmdlet Code. Jeśli wolisz uzyskać więcej wyjaśnień dotyczących kodu, zobacz temat samouczek getproc, samouczek StopProclub samouczek SelectStr .If you prefer more explanation about the code, see the GetProc Tutorial, StopProc Tutorial, or SelectStr Tutorial topics.

Aby uzyskać więcej informacji na temat wytycznych dotyczących pisania poleceń cmdlet, zobacz wskazówki dotyczące programowania poleceń cmdlet.For more information about the guidelines for writing cmdlets, see Cmdlet Development Guidelines.

Zobacz teżSee Also

Pojęcia dotyczące poleceń cmdlet programu PowerShellPowerShell Cmdlet Concepts

Pisanie polecenia cmdlet programu PowerShellWriting a PowerShell Cmdlet

PowerShell SDKPowerShell SDK