Adición de alias, expansión de caracteres comodín y Ayuda a los parámetros del cmdletAdding Aliases, Wildcard Expansion, and Help to Cmdlet Parameters

En esta sección se describe cómo agregar alias, expansión de caracteres comodín y mensajes de ayuda a los parámetros del cmdlet Stop-proc (que se describe en creación de un cmdlet que modifica el sistema).This section describes how to add aliases, wildcard expansion, and Help messages to the parameters of the Stop-Proc cmdlet (described in Creating a Cmdlet that Modifies the System).

Este cmdlet Stop-proc intenta detener los procesos que se recuperan con el cmdlet Get-proc (descrito en creación del primer cmdlet).This Stop-Proc cmdlet attempts to stop processes that are retrieved using the Get-Proc cmdlet (described in Creating Your First Cmdlet).

Definición del cmdletDefining the Cmdlet

El primer paso en la creación de un cmdlet es siempre nombrar el cmdlet y declarar la clase .NET que implementa el cmdlet.The first step in cmdlet creation is always naming the cmdlet and declaring the .NET class that implements the cmdlet. Dado que está escribiendo un cmdlet para cambiar el sistema, debe denominarse en consecuencia.Because you are writing a cmdlet to change the system, it should be named accordingly. Dado que este cmdlet detiene los procesos del sistema, utiliza el verbo "STOP", definido por la clase System. Management. Automation. Verbslifecycle , con el nombre "proc" para indicar el proceso.Because this cmdlet stops system processes, it uses the verb "Stop", defined by the System.Management.Automation.Verbslifecycle class, with the noun "Proc" to indicate process. Para obtener más información sobre los verbos de cmdlet aprobados, consulte nombres de verbos de cmdlet.For more information about approved cmdlet verbs, see Cmdlet Verb Names.

El código siguiente es la definición de clase para este cmdlet Stop-proc.The following code is the class definition for this Stop-Proc cmdlet.

[Cmdlet(VerbsLifecycle.Stop, "proc",
        SupportsShouldProcess = true)]
public class StopProcCommand : Cmdlet

Definir parámetros para la modificación del sistemaDefining Parameters for System Modification

El cmdlet debe definir parámetros que admitan las modificaciones del sistema y los comentarios de los usuarios.Your cmdlet needs to define parameters that support system modifications and user feedback. El cmdlet debe definir un Name parámetro o un equivalente para que el cmdlet pueda modificar el sistema mediante algún tipo de identificador.The cmdlet should define a Name parameter or equivalent so that the cmdlet will be able to modify the system by some sort of identifier. Además, el cmdlet debe definir los Force parámetros y PassThru .In addition, the cmdlet should define the Force and PassThru parameters. Para obtener más información acerca de estos parámetros, consulte crear un cmdlet que modifique el sistema.For more information about these parameters, see Creating a Cmdlet that Modifies the System.

Definir un alias de parámetroDefining a Parameter Alias

Un alias de parámetro puede ser un nombre alternativo o un nombre corto de 1 letra o 2 Letras bien definido para un parámetro de cmdlet.A parameter alias can be an alternate name or a well-defined 1-letter or 2-letter short name for a cmdlet parameter. En ambos casos, el objetivo de usar alias es simplificar la entrada del usuario desde la línea de comandos.In both cases, the goal of using aliases is to simplify user entry from the command line. Windows PowerShell admite alias de parámetro mediante el atributo System. Management. Automation. AliasAttribute , que usa la sintaxis de declaración [alias ()].Windows PowerShell supports parameter aliases through the System.Management.Automation.Aliasattribute attribute, which uses the declaration syntax [Alias()].

En el código siguiente se muestra cómo se agrega un alias al Name parámetro.The following code shows how an alias is added to the Name parameter.

/// <summary>
/// Specify the mandatory Name parameter used to identify the
/// processes to be stopped.
/// </summary>
[Parameter(
           Position = 0,
           Mandatory = true,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true,
           HelpMessage = "The name of one or more processes to stop. Wildcards are permitted."
)]
[Alias("ProcessName")]
public string[] Name
{
  get { return processNames; }
  set { processNames = value; }
}
private string[] processNames;

Además de usar el atributo System. Management. Automation. AliasAttribute , el tiempo de ejecución de Windows PowerShell realiza una coincidencia parcial de nombres, aunque no se especifique ningún alias.In addition to using the System.Management.Automation.Aliasattribute attribute, the Windows PowerShell runtime performs partial name matching, even if no aliases are specified. Por ejemplo, si el cmdlet tiene un FileName parámetro y este es el único parámetro que comienza con F , el usuario podría escribir Filename , Filenam , File , Fi o F y seguir reconociendo la entrada como el FileName parámetro.For example, if your cmdlet has a FileName parameter and that is the only parameter that starts with F, the user could enter Filename, Filenam, File, Fi, or F and still recognize the entry as the FileName parameter.

Crear ayuda para parámetrosCreating Help for Parameters

Windows PowerShell le permite crear ayuda para los parámetros de cmdlet.Windows PowerShell allows you to create Help for cmdlet parameters. Haga esto para cualquier parámetro utilizado para la modificación del sistema y los comentarios de los usuarios.Do this for any parameter used for system modification and user feedback. Para que cada parámetro admita la ayuda, puede establecer la HelpMessage palabra clave Attribute en la declaración de atributo System. Management. Automation. Parameterattribute .For each parameter to support Help, you can set the HelpMessage attribute keyword in the System.Management.Automation.Parameterattribute attribute declaration. Esta palabra clave define el texto que se va a mostrar al usuario para obtener ayuda sobre el uso del parámetro.This keyword defines the text to display to the user for assistance in using the parameter. También puede establecer la HelpMessageBaseName palabra clave para identificar el nombre base de un recurso que se va a usar para el mensaje.You can also set the HelpMessageBaseName keyword to identify the base name of a resource to use for the message. Si establece esta palabra clave, también debe establecer la HelpMessageResourceId palabra clave para especificar el identificador de recursos.If you set this keyword, you must also set the HelpMessageResourceId keyword to specify the resource identifier.

El siguiente código de este cmdlet Stop-proc define la HelpMessage palabra clave de atributo para el Name parámetro.The following code from this Stop-Proc cmdlet defines the HelpMessage attribute keyword for the Name parameter.

/// <summary>
/// Specify the mandatory Name parameter used to identify the
/// processes to be stopped.
/// </summary>
[Parameter(
           Position = 0,
           Mandatory = true,
           ValueFromPipeline = true,
           ValueFromPipelineByPropertyName = true,
           HelpMessage = "The name of one or more processes to stop. Wildcards are permitted."
)]

Reemplazar un método de procesamiento de entradaOverriding an Input Processing Method

El cmdlet debe invalidar un método de procesamiento de entrada, lo que suele ser System. Management. Automation. cmdlet. ProcessRecord.Your cmdlet must override an input processing method, most often this will be System.Management.Automation.Cmdlet.ProcessRecord. Al modificar el sistema, el cmdlet debe llamar a los métodos System. Management. Automation. cmdlet. ShouldProcess y System. Management. Automation. cmdlet. ShouldContinue para permitir que el usuario proporcione comentarios antes de que se realice un cambio.When modifying the system, the cmdlet should call the System.Management.Automation.Cmdlet.ShouldProcess and System.Management.Automation.Cmdlet.ShouldContinue methods to allow the user to provide feedback before a change is made. Para obtener más información acerca de estos métodos, consulte crear un cmdlet que modifique el sistema.For more information about these methods, see Creating a Cmdlet that Modifies the System.

Compatibilidad con la expansión de caracteres comodínSupporting Wildcard Expansion

Para permitir la selección de varios objetos, el cmdlet puede usar las clases System. Management. Automation. Wildcardpattern y System. Management. Automation. Wildcardoptions para proporcionar compatibilidad con la expansión de caracteres comodín para la entrada de parámetros.To allow the selection of multiple objects, your cmdlet can use the System.Management.Automation.Wildcardpattern and System.Management.Automation.Wildcardoptions classes to provide wildcard expansion support for parameter input. Algunos ejemplos de patrones de caracteres comodín son LSA *, * . txt y [a-c] * .Examples of wildcard patterns are lsa*, *.txt, and [a-c]*. Use el carácter de comilla inversa (') como carácter de escape cuando el patrón contenga un carácter que se deba usar literalmente.Use the back-quote character (`) as an escape character when the pattern contains a character that should be used literally.

Las expansiones de comodín de los nombres de archivo y de ruta de acceso son ejemplos de escenarios comunes en los que el cmdlet puede querer permitir la compatibilidad con entradas de ruta de acceso cuando se requiere la selección de varios objetos.Wildcard expansions of file and path names are examples of common scenarios where the cmdlet may want to allow support for path inputs when the selection of multiple objects is required. Un caso común está en el sistema de archivos, en el que un usuario desea ver todos los archivos que residen en la carpeta actual.A common case is in the file system, where a user wants to see all files residing in the current folder.

Solo necesitará una implementación personalizada de coincidencia de patrones de caracteres comodín.You should need a customized wildcard pattern matching implementation only rarely. En este caso, el cmdlet debe ser compatible con la especificación de POSIX 1003,2, 3,13 completa para la expansión de caracteres comodín o el siguiente subconjunto simplificado:In this case, your cmdlet should support either the full POSIX 1003.2, 3.13 specification for wildcard expansion or the following simplified subset:

  • Signo de interrogación (?).Question mark (?). Coincide con cualquier carácter que se encuentra en la ubicación especificada.Matches any character at the specified location.

  • Asterisco ( * ).Asterisk (*). Coincide con cero o más caracteres que comienzan en la ubicación especificada.Matches zero or more characters starting at the specified location.

  • Corchete de apertura ([).Open bracket ([). Introduce una expresión entre corchetes de patrón que puede contener caracteres o un intervalo de caracteres.Introduces a pattern bracket expression that can contain characters or a range of characters. Si se requiere un intervalo, se usa un guión (-) para indicar el intervalo.If a range is required, a hyphen (-) is used to indicate the range.

  • Corchete de cierre (]).Close bracket (]). Finaliza una expresión de corchete de patrón.Ends a pattern bracket expression.

  • Carácter de escape de comilla inversa (').Back-quote escape character (`). Indica que el siguiente carácter debe tomarse literalmente.Indicates that the next character should be taken literally. Tenga en cuenta que al especificar el carácter de comilla inversa desde la línea de comandos (en lugar de especificarlo mediante programación), el carácter de escape de comilla inversa debe especificarse dos veces.Be aware that when specifying the back-quote character from the command line (as opposed to specifying it programmatically), the back-quote escape character must be specified twice.

Nota

Para obtener más información sobre los patrones de caracteres comodín, consulte compatibilidad con caracteres comodín en parámetros de cmdlet.For more information about wildcard patterns, see Supporting Wildcards in Cmdlet Parameters.

El código siguiente muestra cómo establecer las opciones de carácter comodín y definir el patrón de caracteres comodín que se usa para resolver el Name parámetro de este cmdlet.The following code shows how to set wildcard options and define the wildcard pattern used for resolving the Name parameter for this cmdlet.

WildcardOptions options = WildcardOptions.IgnoreCase |
                          WildcardOptions.Compiled;
WildcardPattern wildcard = new WildcardPattern(name,options);

En el código siguiente se muestra cómo comprobar si el nombre del proceso coincide con el patrón de caracteres comodín definido.The following code shows how to test whether the process name matches the defined wildcard pattern. Tenga en cuenta que, en este caso, si el nombre del proceso no coincide con el patrón, el cmdlet continúa para obtener el nombre del proceso siguiente.Notice that, in this case, if the process name does not match the pattern, the cmdlet continues on to get the next process name.

if (!wildcard.IsMatch(processName))
{
  continue;
}

Ejemplo de códigoCode Sample

Para obtener el código de ejemplo de C# completo, vea el ejemplo StopProcessSample03.For the complete C# sample code, see StopProcessSample03 Sample.

Definir tipos de objeto y formatoDefine Object Types and Formatting

Windows PowerShell pasa información entre cmdlets mediante objetos .net.Windows PowerShell passes information between cmdlets using .Net objects. Por lo tanto, es posible que un cmdlet tenga que definir su propio tipo o que el cmdlet tenga que extender un tipo existente proporcionado por otro cmdlet.Consequently, a cmdlet may need to define its own type, or the cmdlet may need to extend an existing type provided by another cmdlet. Para obtener más información sobre la definición de nuevos tipos o la extensión de tipos existentes, vea extender tipos de objeto y formato.For more information about defining new types or extending existing types, see Extending Object Types and Formatting.

Compilación del cmdletBuilding the Cmdlet

Después de implementar un cmdlet, debe registrarse con Windows PowerShell a través de un complemento de Windows PowerShell.After implementing a cmdlet, it must be registered with Windows PowerShell through a Windows PowerShell snap-in. Para obtener más información acerca del registro de cmdlets, consulte Cómo registrar cmdlets, proveedores y aplicaciones host.For more information about registering cmdlets, see How to Register Cmdlets, Providers, and Host Applications.

Prueba del cmdletTesting the Cmdlet

Cuando el cmdlet se ha registrado con Windows PowerShell, puede probarlo mediante su ejecución en la línea de comandos.When your cmdlet has been registered with Windows PowerShell, you can test it by running it on the command line. Vamos a probar el cmdlet Stop-proc de ejemplo.Let's test the sample Stop-Proc cmdlet. Para obtener más información sobre el uso de cmdlets desde la línea de comandos, consulte la Introducción con Windows PowerShell.For more information about using cmdlets from the command line, see the Getting Started with Windows PowerShell.

  • Inicie Windows PowerShell y use STOP-proc para detener un proceso con el alias processName para el Name parámetro.Start Windows PowerShell and use Stop-Proc to stop a process using the ProcessName alias for the Name parameter.

    PS> stop-proc -ProcessName notepad
    

    Aparece el siguiente resultado.The following output appears.

    Confirm
    Are you sure you want to perform this action?
    Performing operation "stop-proc" on Target "notepad (3496)".
    [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y
    
  • Realice la siguiente entrada en la línea de comandos.Make the following entry on the command line. Dado que el parámetro name es obligatorio, se le pedirá que lo indique.Because the Name parameter is mandatory, you are prompted for it. Escribiendo "!?"Entering "!?" muestra el texto de ayuda asociado al parámetro.brings up the help text associated with the parameter.

    PS> stop-proc
    

    Aparece el siguiente resultado.The following output appears.

    Cmdlet stop-proc at command pipeline position 1
    Supply values for the following parameters:
    (Type !? for Help.)
    Name[0]: !?
    The name of one or more processes to stop. Wildcards are permitted.
    Name[0]: notepad
    
  • Ahora realice la siguiente entrada para detener todos los procesos que coinciden con el patrón de carácter comodín "* note * ".Now make the following entry to stop all processes that match the wildcard pattern "*note*". Se le pedirá antes de detener cada proceso que coincida con el patrón.You are prompted before stopping each process that matches the pattern.

    PS> stop-proc -Name *note*
    

    Aparece el siguiente resultado.The following output appears.

    Confirm
    Are you sure you want to perform this action?
    Performing operation "stop-proc" on Target "notepad (1112)".
    [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y
    

    Aparece el siguiente resultado.The following output appears.

    Confirm
    Are you sure you want to perform this action?
    Performing operation "stop-proc" on Target "ONENOTEM (3712)".
    [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N
    

    Aparece el siguiente resultado.The following output appears.

    Confirm
    Are you sure you want to perform this action?
    Performing operation "stop-proc" on Target "ONENOTE (3592)".
    [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N
    

Consulte tambiénSee Also

Crear un cmdlet que modifique el sistemaCreate a Cmdlet that Modifies the System

Cómo crear un cmdlet de Windows PowerShellHow to Create a Windows PowerShell Cmdlet

Extender tipos de objeto y formatoExtending Object Types and Formatting

Cómo registrar cmdlets, proveedores y aplicaciones hostHow to Register Cmdlets, Providers, and Host Applications

Compatibilidad con caracteres comodín en parámetros de cmdletSupporting Wildcards in Cmdlet Parameters

Windows PowerShell SDKWindows PowerShell SDK