Información general del cmdletCmdlet Overview

Un cmdlet es un comando ligero que se usa en el entorno de PowerShell.A cmdlet is a lightweight command that is used in the PowerShell environment. El tiempo de ejecución de PowerShell invoca estos cmdlets en el contexto de los scripts de automatización que se proporcionan en la línea de comandos.The PowerShell runtime invokes these cmdlets within the context of automation scripts that are provided at the command line. El entorno de tiempo de ejecución de PowerShell también los invoca mediante programación a través de las API de PowerShell.The PowerShell runtime also invokes them programmatically through PowerShell APIs.

CmdletsCmdlets

Realizan una acción y normalmente devuelven un objeto Microsoft .NET al siguiente comando de la canalización.Cmdlets perform an action and typically return a Microsoft .NET object to the next command in the pipeline. Un cmdlet es un comando único que participa en la semántica de canalización de PowerShell.A cmdlet is a single command that participates in the pipeline semantics of PowerShell. Esto incluye cmdlets binarios (C#), funciones de script avanzadas, CDXML y flujos de trabajo.This includes binary (C#) cmdlets, advanced script functions, CDXML, and Workflows.

En esta documentación del SDK se describe cómo crear cmdlets binarios escritos en C#.This SDK documentation describes how to create binary cmdlets written in C#. Para obtener información acerca de los cmdlets basados en scripts, consulte:For information about script-based cmdlets, see:

Para crear un cmdlet binario, debe implementar una clase de cmdlet que derive de una de las dos clases base de cmdlets especializadas.To create a binary cmdlet, you must implement a cmdlet class that derives from one of two specialized cmdlet base classes. La clase derivada debe:The derived class must:

  • Declare un atributo que identifique la clase derivada como un cmdlet.Declare an attribute that identifies the derived class as a cmdlet.
  • Defina las propiedades públicas que se decoran con atributos que identifican las propiedades públicas como parámetros de cmdlet.Define public properties that are decorated with attributes that identify the public properties as cmdlet parameters.
  • Invalide uno o varios métodos de procesamiento de entrada para procesar los registros.Override one or more of the input processing methods to process records.

Puede cargar el ensamblado que contiene la clase directamente mediante el cmdlet Import-Module , o puede crear una aplicación host que cargue el ensamblado mediante elSystem.Management.Automation.Runspaces.IniAPI tialsessionstate .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. Ambos métodos proporcionan acceso de línea de comandos y mediante programación a la funcionalidad del cmdlet.Both methods provide programmatic and command-line access to the functionality of the cmdlet.

Términos del cmdletCmdlet Terms

Los siguientes términos se usan con frecuencia en la documentación del cmdlet de PowerShell:The following terms are used frequently in the PowerShell cmdlet documentation:

Atributo de cmdletCmdlet attribute

Un atributo de .NET que se usa para declarar una clase de cmdlet como un cmdlet.A .NET attribute that is used to declare a cmdlet class as a cmdlet. Aunque PowerShell usa otros atributos que son opcionales, el atributo de cmdlet es obligatorio.Although PowerShell uses several other attributes that are optional, the Cmdlet attribute is required. Para obtener más información sobre este atributo, vea declaración de atributos de cmdlet.For more information about this attribute, see Cmdlet Attribute Declaration.

Parámetro del cmdletCmdlet parameter

Propiedades públicas que definen los parámetros que están disponibles para el usuario o la aplicación que ejecuta el cmdlet.The public properties that define the parameters that are available to the user or to the application that is running the cmdlet. Los cmdlets pueden tener parámetros obligatorios, con nombre, posicionales y Modificadores .Cmdlets can have required, named, positional, and switch parameters. Los parámetros switch permiten definir parámetros que solo se evalúan si los parámetros se especifican en la llamada.Switch parameters allow you to define parameters that are evaluated only if the parameters are specified in the call. Para obtener más información sobre los diferentes tipos de parámetros, vea parámetros de cmdlet.For more information about the different types of parameters, see Cmdlet Parameters.

Conjunto de parámetrosParameter set

Grupo de parámetros que pueden usarse en el mismo comando para realizar una acción específica.A group of parameters that can be used in the same command to perform a specific action. Un cmdlet puede tener varios conjuntos de parámetros, pero cada conjunto de parámetros debe tener al menos un parámetro que sea único.A cmdlet can have multiple parameter sets, but each parameter set must have at least one parameter that is unique. Un buen diseño de los cmdlets sugiere que el parámetro único también sea un parámetro necesario.Good cmdlet design strongly suggests that the unique parameter also be a required parameter. Para obtener más información sobre los conjuntos de parámetros, vea conjuntos de parámetros de cmdlet.For more information about parameter sets, see Cmdlet Parameter Sets.

Parámetro dinámicoDynamic parameter

Parámetro que se agrega al cmdlet en tiempo de ejecución.A parameter that is added to the cmdlet at runtime. Normalmente, los parámetros dinámicos se agregan al cmdlet cuando otro parámetro se establece en un valor específico.Typically, the dynamic parameters are added to the cmdlet when another parameter is set to a specific value. Para obtener más información sobre los parámetros dinámicos, consulte parámetros dinámicos de cmdlet.For more information about dynamic parameters, see Cmdlet Dynamic Parameters.

Métodos de procesamiento de entradaInput processing methods

La clase System. Management. Automation. cmdlet proporciona los siguientes métodos virtuales que se usan para procesar registros.The System.Management.Automation.Cmdlet class provides the following virtual methods that are used to process records. Todas las clases de cmdlet derivadas deben invalidar uno o varios de los tres primeros métodos:All the derived cmdlet classes must override one or more of the first three methods:

Para obtener más información sobre estos métodos, vea métodos de procesamiento de entrada de cmdlet.For more information about these methods, see Cmdlet Input Processing Methods.

Al implementar un cmdlet, debe invalidar al menos uno de estos métodos de procesamiento de entrada.When you implement a cmdlet, you must override at least one of these input processing methods. Normalmente, el ProcessRecord () es el método que se invalida porque se llama para cada registro que el cmdlet procesa.Typically, the ProcessRecord() is the method that you override because it is called for every record that the cmdlet processes. Por el contrario, se llama una vez al método BeginProcessing () y al método EndProcessing () para realizar el procesamiento previo o posterior al procesamiento de los registros.In contrast, the BeginProcessing() method and the EndProcessing() method are called one time to perform pre-processing or post-processing of the records. Para obtener más información sobre estos métodos, vea métodos de procesamiento de entrada.For more information about these methods, see Input Processing Methods.

ShouldProcess (característica)ShouldProcess feature

PowerShell le permite crear cmdlets que solicitan información al usuario antes de que el cmdlet realice un cambio en el sistema.PowerShell allows you to create cmdlets that prompt the user for feedback before the cmdlet makes a change to the system. Para usar esta característica, el cmdlet debe declarar que admite la ShouldProcess característica cuando se declara el atributo de cmdlet y el cmdlet debe llamar a los métodos System. Management. Automation. cmdlet. ShouldProcess y System. Management. Automation. cmdlet. ShouldContinue desde dentro de un método de procesamiento de entrada.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. Para obtener más información sobre cómo admitir la ShouldProcess funcionalidad, consulte solicitar confirmación.For more information about how to support the ShouldProcess functionality, see Requesting Confirmation.

TransacciónTransaction

Grupo lógico de comandos que se tratan como una sola tarea.A logical group of commands that are treated as a single task. La tarea genera un error automáticamente si se produce un error en algún comando del grupo y el usuario tiene la opción de aceptar o rechazar las acciones realizadas dentro de la transacción.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. Para participar en una transacción, el cmdlet debe declarar que admite transacciones cuando se declara el atributo de cmdlet.To participate in a transaction, the cmdlet must declare that it supports transactions when the Cmdlet attribute is declared. La compatibilidad con transacciones se presentó en Windows PowerShell 2,0.Support for transactions was introduced in Windows PowerShell 2.0. Para obtener más información acerca de las transacciones, consulte How to Support Transactions.For more information about transactions, see How to Support Transactions.

Diferencias entre los cmdlets y los comandosHow Cmdlets Differ from Commands

Los cmdlets se diferencian de los comandos en otros entornos de Shell de comandos de las siguientes maneras:Cmdlets differ from commands in other command-shell environments in the following ways:

  • Los cmdlets son instancias de clases .NET; no son ejecutables independientes.Cmdlets are instances of .NET classes; they are not stand-alone executables.
  • Los cmdlets se pueden crear desde tan solo una docena de líneas de código.Cmdlets can be created from as few as a dozen lines of code.
  • Los cmdlets no realizan normalmente su propio análisis, presentación de errores o formato de salida.Cmdlets do not generally do their own parsing, error presentation, or output formatting. El tiempo de ejecución de PowerShell administra el análisis, la presentación de errores y el formato de salida.Parsing, error presentation, and output formatting are handled by the PowerShell runtime.
  • Los cmdlets procesan los objetos de entrada de la canalización en lugar de los flujos de texto, y los cmdlets suelen ofrecer objetos como salida a la canalización.Cmdlets process input objects from the pipeline rather than from streams of text, and cmdlets typically deliver objects as output to the pipeline.
  • Los cmdlets están orientados a registros porque procesan un solo objeto cada vez.Cmdlets are record-oriented because they process a single object at a time.

Clases base de cmdletCmdlet Base Classes

Windows PowerShell admite cmdlets que se derivan de las dos clases base siguientes.Windows PowerShell supports cmdlets that are derived from the following two base classes.

  • La mayoría de los cmdlets se basan en clases .NET que derivan de la clase base System. Management. Automation. cmdlet .Most cmdlets are based on .NET classes that derive from the System.Management.Automation.Cmdlet base class. La derivación de esta clase permite a un cmdlet usar el conjunto mínimo de dependencias en el tiempo de ejecución de Windows PowerShell.Deriving from this class allows a cmdlet to use the minimum set of dependencies on the Windows PowerShell runtime. lo que ofrece dos ventajas.This has two benefits. La primera ventaja es que los objetos de cmdlet son más pequeños y es menos probable que se vea afectado por los cambios en el tiempo de ejecución de 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. La segunda ventaja es que, si es necesario, puede crear directamente una instancia del objeto de cmdlet y, a continuación, invocarla directamente en lugar de invocarla a través del tiempo de ejecución de 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.

  • Los cmdlets más complejos se basan en clases .NET que derivan de la clase base System. Management. Automation. PSCmdlet .The more-complex cmdlets are based on .NET classes that derive from the System.Management.Automation.PSCmdlet base class. La derivación de esta clase proporciona mucho más acceso al tiempo de ejecución de PowerShell.Deriving from this class gives you much more access to the PowerShell runtime. Este acceso permite que el cmdlet llame a scripts, para obtener acceso a los proveedores y para obtener acceso al estado de sesión actual.This access allows your cmdlet to call scripts, to access providers, and to access the current session state. (Para tener acceso al estado de sesión actual, se obtienen y establecen las preferencias y las variables de la sesión). Sin embargo, la derivación de esta clase aumenta el tamaño del objeto de cmdlet y significa que el cmdlet se acopla más estrechamente a la versión actual del tiempo de ejecución de 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.

En general, a menos que necesite el acceso extendido al tiempo de ejecución de PowerShell, debe derivar de la clase 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. Sin embargo, el tiempo de ejecución de PowerShell tiene amplias capacidades de registro para la ejecución de cmdlets.However, the PowerShell runtime has extensive logging capabilities for the execution of cmdlets. Si el modelo de auditoría depende de este registro, puede impedir la ejecución de su cmdlet desde otro cmdlet mediante la derivación de la clase 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.

Atributos del cmdletCmdlet Attributes

PowerShell define varios atributos de .NET que se usan para administrar cmdlets y para especificar la funcionalidad común proporcionada por PowerShell y que el cmdlet puede necesitar.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. Por ejemplo, los atributos se usan para designar una clase como un cmdlet, especificar los parámetros del cmdlet y solicitar la validación de la entrada para que los desarrolladores de cmdlets no tengan que implementar esa funcionalidad en su código de 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. Para obtener más información sobre los atributos, consulte atributos de PowerShell.For more information about attributes, see PowerShell Attributes.

Nombres de cmdletsCmdlet Names

PowerShell usa un par de nombres de verbo y sustantivo para asignar nombres a los cmdlets.PowerShell uses a verb-and-noun name pair to name cmdlets. Por ejemplo, el Get-Command cmdlet incluido en PowerShell se usa para obtener todos los cmdlets que están registrados en el shell de comandos.For example, the Get-Command cmdlet included in PowerShell is used to get all the cmdlets that are registered in the command shell. El verbo identifica la acción que realiza el cmdlet y el nombre identifica el recurso en el que el cmdlet realiza su acción.The verb identifies the action that the cmdlet performs, and the noun identifies the resource on which the cmdlet performs its action.

Estos nombres se especifican cuando la clase .NET se declara como un cmdlet.These names are specified when the .NET class is declared as a cmdlet. Para obtener más información sobre cómo declarar una clase .NET como cmdlet, vea declaración de atributo de cmdlet.For more information about how to declare a .NET class as a cmdlet, see Cmdlet Attribute Declaration.

Escribir código de cmdletWriting Cmdlet Code

En este documento se proporcionan dos maneras de detectar cómo se escribe el código de cmdlet.This document provides two ways to discover how cmdlet code is written. Si prefiere ver el código sin mucha explicación, consulte ejemplos de código de cmdlet.If you prefer to see the code without much explanation, see Examples of Cmdlet Code. Si prefiere obtener una explicación más detallada sobre el código, vea los temas tutorial de GetProc, tutorial de StopProco tutorial de SelectStr .If you prefer more explanation about the code, see the GetProc Tutorial, StopProc Tutorial, or SelectStr Tutorial topics.

Para obtener más información sobre las instrucciones para escribir cmdlets, vea instrucciones para el desarrollo de cmdlets.For more information about the guidelines for writing cmdlets, see Cmdlet Development Guidelines.

Consulte tambiénSee Also

Conceptos de cmdlets de PowerShellPowerShell Cmdlet Concepts

Escritura de un cmdlet de PowerShellWriting a PowerShell Cmdlet

SDK de PowerShellPowerShell SDK