Parancsmag – áttekintésCmdlet Overview

A parancsmag egy egyszerű parancs, amely a PowerShell-környezetben használatos.A cmdlet is a lightweight command that is used in the PowerShell environment. A PowerShell-futtatókörnyezet a parancssorban megadott Automation-parancsfájlok kontextusában hívja meg ezeket a parancsmagokat.The PowerShell runtime invokes these cmdlets within the context of automation scripts that are provided at the command line. A PowerShell-futtatókörnyezet a PowerShell API-kkal programozott módon is meghívja őket.The PowerShell runtime also invokes them programmatically through PowerShell APIs.

ParancsmagokCmdlets

A parancsmagok műveletet hajtanak végre, és általában egy Microsoft .NET objektumot adnak vissza a folyamat következő parancsához.Cmdlets perform an action and typically return a Microsoft .NET object to the next command in the pipeline. A parancsmag egyetlen parancs, amely részt vesz a PowerShell folyamat szemantikaában.A cmdlet is a single command that participates in the pipeline semantics of PowerShell. Ide tartozik a bináris (C#) parancsmagok, a speciális parancsfájl-függvények, a CDXML és a munkafolyamatok.This includes binary (C#) cmdlets, advanced script functions, CDXML, and Workflows.

Ez az SDK-dokumentáció a C# nyelven írt bináris parancsmagok létrehozását ismerteti.This SDK documentation describes how to create binary cmdlets written in C#. A parancsfájl-alapú parancsmagokkal kapcsolatos információkért lásd:For information about script-based cmdlets, see:

Bináris parancsmag létrehozásához olyan parancsmag-osztályt kell megvalósítani, amely a két speciális parancsmag alaposztályának egyikén alapul.To create a binary cmdlet, you must implement a cmdlet class that derives from one of two specialized cmdlet base classes. A származtatott osztálynak a következőket kell tennie:The derived class must:

  • Deklaráljon egy attribútumot, amely azonosítja a származtatott osztályt parancsmagként.Declare an attribute that identifies the derived class as a cmdlet.
  • Definiálja a nyilvános tulajdonságokat a parancsmag paramétereinek azonosítására szolgáló attribútumokkal díszített nyilvános tulajdonságokat.Define public properties that are decorated with attributes that identify the public properties as cmdlet parameters.
  • Egy vagy több bemeneti feldolgozási módszer felülbírálásával dolgozza fel a rekordokat.Override one or more of the input processing methods to process records.

Az osztályt közvetlenül az import-Module parancsmaggal is betöltheti, vagy létrehozhat egy olyan gazda alkalmazást, amely betölti a szerelvényt a System.Management.Automation.Runspaces.Initialsessionstate API használatával.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. Mindkét módszer programozási és parancssori hozzáférést biztosít a parancsmag működéséhez.Both methods provide programmatic and command-line access to the functionality of the cmdlet.

Parancsmag feltételeiCmdlet Terms

A PowerShell-parancsmag dokumentációjában gyakran használják a következő feltételeket:The following terms are used frequently in the PowerShell cmdlet documentation:

Parancsmag-attribútumCmdlet attribute

Egy olyan .NET-attribútum, amely a parancsmag osztályának deklarálása parancsmagként történik.A .NET attribute that is used to declare a cmdlet class as a cmdlet. Bár a PowerShell számos más, nem kötelező attribútumot használ, a parancsmag attribútum megadása kötelező.Although PowerShell uses several other attributes that are optional, the Cmdlet attribute is required. További információ erről az attribútumról: parancsmag-attribútum deklarációja.For more information about this attribute, see Cmdlet Attribute Declaration.

Parancsmag paraméterCmdlet parameter

A felhasználó vagy a parancsmagot futtató alkalmazás számára elérhető paramétereket meghatározó nyilvános tulajdonságok.The public properties that define the parameters that are available to the user or to the application that is running the cmdlet. A parancsmagok kötelező, elnevezett, pozícionáló és kapcsoló paramétereket tartalmazhatnak.Cmdlets can have required, named, positional, and switch parameters. A Switch paraméterek lehetővé teszik olyan paraméterek meghatározását, amelyek kiértékelése csak akkor történik meg, ha a paraméterek meg vannak adva a hívásban.Switch parameters allow you to define parameters that are evaluated only if the parameters are specified in the call. A különböző típusú paraméterekkel kapcsolatos további információkért lásd a parancsmag paramétereit.For more information about the different types of parameters, see Cmdlet Parameters.

Paraméter beállítvaParameter set

Olyan paraméterek csoportja, amelyek ugyanabban a parancsban használhatók egy adott művelet végrehajtásához.A group of parameters that can be used in the same command to perform a specific action. Egy parancsmagnak több paramétere is lehet, de minden egyes paraméternek legalább egy egyedi paraméterrel kell rendelkeznie.A cmdlet can have multiple parameter sets, but each parameter set must have at least one parameter that is unique. A jó parancsmag kialakítása határozottan azt sugallja, hogy az egyedi paraméter is kötelező paraméter.Good cmdlet design strongly suggests that the unique parameter also be a required parameter. További információ a paraméter-készletekről: parancsmag-paraméterek készletei.For more information about parameter sets, see Cmdlet Parameter Sets.

Dinamikus paraméterDynamic parameter

Egy paraméter, amely futásidőben kerül a parancsmaghoz.A parameter that is added to the cmdlet at runtime. A dinamikus paramétereket általában a rendszer hozzáadja a parancsmaghoz, ha egy másik paraméter egy adott értékre van állítva.Typically, the dynamic parameters are added to the cmdlet when another parameter is set to a specific value. További információ a dinamikus paraméterekről: parancsmag dinamikus paraméterek.For more information about dynamic parameters, see Cmdlet Dynamic Parameters.

Bemeneti feldolgozási módszerekInput processing methods

A System. Management. Automation. parancsmag osztály a következő virtuális metódusokat biztosítja, amelyek a rekordok feldolgozására szolgálnak.The System.Management.Automation.Cmdlet class provides the following virtual methods that are used to process records. Az összes származtatott parancsmag-osztálynak felül kell bírálnia az első három módszer közül egyet vagy többet:All the derived cmdlet classes must override one or more of the first three methods:

További információ ezekről a módszerekről: parancsmag bemeneti feldolgozási módszerei.For more information about these methods, see Cmdlet Input Processing Methods.

Parancsmag megvalósításakor felül kell bírálnia legalább egy ilyen bemeneti feldolgozási módszert.When you implement a cmdlet, you must override at least one of these input processing methods. Általában a ProcessRecord () az a módszer, amelyet felülbírál, mert a parancsmag által feldolgozott összes rekordhoz meghívva van.Typically, the ProcessRecord() is the method that you override because it is called for every record that the cmdlet processes. Ezzel szemben a BeginProcessing () metódust és a EndProcessing () metódust egyszer kell meghívni a rekordok előfeldolgozásának vagy utólagos feldolgozásának elvégzéséhez.In contrast, the BeginProcessing() method and the EndProcessing() method are called one time to perform pre-processing or post-processing of the records. További információ ezekről a módszerekről: input Processing Methods.For more information about these methods, see Input Processing Methods.

ShouldProcess funkcióShouldProcess feature

A PowerShell lehetővé teszi, hogy olyan parancsmagokat hozzon létre, amelyek visszajelzést kérik a felhasználónak, mielőtt a parancsmag módosítja a rendszerét.PowerShell allows you to create cmdlets that prompt the user for feedback before the cmdlet makes a change to the system. A szolgáltatás használatához a parancsmagnak nyilatkoznia kell arról, hogy támogatja a ShouldProcess szolgáltatást, amikor deklarálja a parancsmag attribútumot, és a parancsmagnak meg kell hívnia a System. Management. Automation. parancsmag. ShouldProcess és System. Management. Automation. parancsmag. ShouldContinue metódusokat egy bemeneti feldolgozási módszerből.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. További információ a funkciók támogatásáról ShouldProcess : megerősítés kérése.For more information about how to support the ShouldProcess functionality, see Requesting Confirmation.

TranzakcióTransaction

Egyetlen feladatként kezelt parancsok logikai csoportja.A logical group of commands that are treated as a single task. A feladat automatikusan meghiúsul, ha a csoport bármelyik parancsa meghibásodik, és a felhasználó dönthet úgy, hogy elfogadja vagy elutasítja a tranzakción belül végrehajtott műveleteket.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. Egy tranzakcióban való részvételhez a parancsmagnak nyilatkoznia kell arról, hogy támogatja a tranzakciókat, amikor a parancsmag attribútum deklarálva van.To participate in a transaction, the cmdlet must declare that it supports transactions when the Cmdlet attribute is declared. A Windows PowerShell 2,0-ben vezették be a tranzakciók támogatását.Support for transactions was introduced in Windows PowerShell 2.0. További információ a tranzakciókkal kapcsolatban: a tranzakciók támogatása.For more information about transactions, see How to Support Transactions.

Miben különböznek a parancsmagok a parancsokkalHow Cmdlets Differ from Commands

A parancsmagok a következő módokon különböznek a többi parancssori környezet parancsaitól:Cmdlets differ from commands in other command-shell environments in the following ways:

  • A parancsmagok a .NET-osztályok példányai; nem önálló végrehajtható fájlok.Cmdlets are instances of .NET classes; they are not stand-alone executables.
  • A parancsmagok akár több tucat sornyi kóddal is létrehozhatók.Cmdlets can be created from as few as a dozen lines of code.
  • A parancsmagok általában nem végzik el a saját elemzését, a hibák megjelenítését vagy a kimeneti formázást.Cmdlets do not generally do their own parsing, error presentation, or output formatting. A PowerShell-futtatókörnyezet kezeli az elemzést, a hibák bemutatását és a kimeneti formázást.Parsing, error presentation, and output formatting are handled by the PowerShell runtime.
  • A parancsmagok a bemeneti objektumokat feldolgozzák a folyamatból, nem a szöveges adatfolyamokból, és a parancsmagok jellemzően kimenetként továbbítják az objektumokat a folyamatnak.Cmdlets process input objects from the pipeline rather than from streams of text, and cmdlets typically deliver objects as output to the pipeline.
  • A parancsmagok rekord-orientáltak, mert egyszerre egyetlen objektumot dolgoz fel.Cmdlets are record-oriented because they process a single object at a time.

Parancsmag-alaposztályokCmdlet Base Classes

A Windows PowerShell támogatja a következő két alaposztályból származtatott parancsmagokat.Windows PowerShell supports cmdlets that are derived from the following two base classes.

  • A legtöbb parancsmag a System. Management. Automation. parancsmag alaposztályból származtatott .net-osztályokon alapul.Most cmdlets are based on .NET classes that derive from the System.Management.Automation.Cmdlet base class. Ebből az osztályból származtatott parancsmag lehetővé teszi, hogy a parancsmagok a Windows PowerShell futtatókörnyezetben a függőségek minimális készletét használják.Deriving from this class allows a cmdlet to use the minimum set of dependencies on the Windows PowerShell runtime. Ez két előnnyel jár.This has two benefits. Az első előny, hogy a parancsmag-objektumok kisebbek, és a PowerShell-futtatókörnyezet módosításai kevésbé valószínű hatással lesznek rá.The first benefit is that the cmdlet objects are smaller, and you are less likely to be affected by changes to the PowerShell runtime. A második előny az, hogy ha Önnek kell lennie, közvetlenül is létrehozhatja a parancsmag objektum egy példányát, majd közvetlenül meghívja azt ahelyett, hogy a PowerShell-futtatókörnyezeten keresztül meghívja őket.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.

  • A bonyolultabb parancsmagok a System. Management. Automation. PSCmdlet alaposztályból származtatott .net-osztályokon alapulnak.The more-complex cmdlets are based on .NET classes that derive from the System.Management.Automation.PSCmdlet base class. Az ebből az osztályból származtatott adatok sokkal több hozzáférést biztosítanak a PowerShell futtatókörnyezethez.Deriving from this class gives you much more access to the PowerShell runtime. Ez a hozzáférés lehetővé teszi a parancsmagnak a parancsfájlok meghívását, a szolgáltatók elérését, valamint az aktuális munkamenet-állapot elérését.This access allows your cmdlet to call scripts, to access providers, and to access the current session state. (Az aktuális munkamenet-állapot eléréséhez beolvashatja és beállíthatja a munkamenet-változókat és a beállításokat.) Ebben az osztályban azonban a parancsmag objektum mérete nő, és ez azt jelenti, hogy a parancsmag szorosabban párosul a PowerShell-futtatókörnyezet aktuális verziójával.(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.

Általánosságban elmondható, hogy ha nincs szüksége a PowerShell futtatókörnyezethez való kiterjesztett hozzáférésre, a System. Management. Automation. parancsmag osztályból kell származnia.In general, unless you need the extended access to the PowerShell runtime, you should derive from the System.Management.Automation.Cmdlet class. A PowerShell-futtatókörnyezet azonban kiterjedt naplózási képességekkel rendelkezik a parancsmagok végrehajtásához.However, the PowerShell runtime has extensive logging capabilities for the execution of cmdlets. Ha a naplózási modell ettől a naplózástól függ, meggátolhatja a parancsmag végrehajtását a System. Management. Automation. PSCmdlet osztályból származtatva egy másik parancsmagon belül.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.

Parancsmag-attribútumokCmdlet Attributes

A PowerShell számos olyan .NET-attribútumot határoz meg, amely a parancsmagok kezelésére szolgál, valamint a PowerShell által biztosított általános funkciók megadására, amelyek a parancsmaghoz szükségesek.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. Az attribútumok például egy osztály parancsmagként való kijelölésére szolgálnak, a parancsmag paramétereinek megadásához és a bemenet érvényesítéséhez, így a parancsmag-fejlesztőknek nem kell végrehajtaniuk ezt a funkciót a parancsmag kódjában.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. További információ az attribútumokról: PowerShell-attribútumok.For more information about attributes, see PowerShell Attributes.

Parancsmagok neveiCmdlet Names

A PowerShell egy művelet-és főnévi név párokat használ a name parancsmagokhoz.PowerShell uses a verb-and-noun name pair to name cmdlets. A Get-Command PowerShellben szereplő parancsmag például a parancs-rendszerhéjban regisztrált összes parancsmag beolvasására szolgál.For example, the Get-Command cmdlet included in PowerShell is used to get all the cmdlets that are registered in the command shell. A művelet azonosítja a parancsmag által végrehajtott műveletet, és a főnév azonosítja azt az erőforrást, amelyen a parancsmag végrehajtja a műveletet.The verb identifies the action that the cmdlet performs, and the noun identifies the resource on which the cmdlet performs its action.

Ezek a nevek akkor vannak megadva, ha a .NET-osztály parancsmagként van deklarálva.These names are specified when the .NET class is declared as a cmdlet. További információ a .NET-osztály parancsmagként való deklaráláról: parancsmag-attribútum deklarációja.For more information about how to declare a .NET class as a cmdlet, see Cmdlet Attribute Declaration.

Parancsmag kódjának írásaWriting Cmdlet Code

Ez a dokumentum két módszert biztosít a parancsmag kódjának megírására.This document provides two ways to discover how cmdlet code is written. Ha azt szeretné, hogy a kód nagy magyarázat nélkül legyen látható, tekintse át a parancsmag-kód példáit.If you prefer to see the code without much explanation, see Examples of Cmdlet Code. Ha további magyarázatra van szüksége a kóddal kapcsolatban, tekintse meg a GetProc-oktatóanyagot, a StopProc-oktatóanyagot, vagy a SelectStr oktatóanyagát ismertető témákat.If you prefer more explanation about the code, see the GetProc Tutorial, StopProc Tutorial, or SelectStr Tutorial topics.

A parancsmagok írásával kapcsolatos további információkért lásd a parancsmagok fejlesztési irányelveit.For more information about the guidelines for writing cmdlets, see Cmdlet Development Guidelines.

Lásd még:See Also

A PowerShell-parancsmagok fogalmaiPowerShell Cmdlet Concepts

PowerShell-parancsmag írásaWriting a PowerShell Cmdlet

PowerShell SDKPowerShell SDK