Directrices de desarrollo necesarias
Se deben seguir las instrucciones siguientes al escribir los cmdlets. Se separan en directrices para diseñar cmdlets e instrucciones para escribir el código de cmdlet. Si no sigue estas directrices, los cmdlets podrían producir errores y los usuarios podrían tener una mala experiencia cuando usan los cmdlets.
En este tema
Directrices de diseño
Directrices de código
Directrices de diseño
Se deben seguir las instrucciones siguientes al diseñar cmdlets para garantizar una experiencia de usuario coherente entre el uso de los cmdlets y otros cmdlets. Cuando encuentre una guía de diseño que se aplique a su situación, asegúrese de consultar las directrices de código para obtener instrucciones similares.
Usar solo verbos aprobados (RD01)
El verbo especificado en el atributo Cmdlet debe provenir del conjunto reconocido de verbos proporcionados por Windows PowerShell. No debe ser uno de los sinónimos prohibidos. Use las cadenas constantes definidas por las enumeraciones siguientes para especificar verbos de cmdlet:
Para obtener más información sobre los nombres de verbo aprobados, vea Cmdlet Verbs.
Los usuarios necesitan un conjunto de nombres de cmdlet reconocibles y esperados. Use el verbo adecuado para que el usuario pueda realizar una evaluación rápida de lo que hace un cmdlet y detectar fácilmente las funcionalidades del sistema. Por ejemplo, el siguiente comando de línea de comandos obtiene una lista de todos los comandos del sistema cuyos nombres comienzan por "Start": Get-Command Start-*. Use los nombres de los cmdlets para diferenciar los cmdlets de otros cmdlets. El nombre indica el recurso en el que se realizará la operación. La propia operación se representa mediante el verbo .
Nombres de cmdlet: caracteres que no se pueden usar (RD02)
Al asignar un nombre a los cmdlets, no use ninguno de los siguientes caracteres especiales.
| Carácter | Nombre |
|---|---|
| # | signo de número |
| , | coma |
| () | paréntesis |
| {} | ortodoncia |
| [] | corchetes |
| & | ampersand |
| - | guion Nota: El guión se puede usar para separar el verbo del nombre, pero no se puede usar dentro del nombre o dentro del verbo. |
| / | barra diagonal |
| \ | barra diagonal inversa |
| $ | signo de dólar |
| ^ | caret |
| ; | punto y coma |
| : | colon |
| " | comillas dobles |
| ' | comillas simples |
| <> | corchetes angulares |
| | | barra vertical |
| ? | signo de interrogación |
| @ | arroba |
| ` | tic trasero (énfasis grave) |
| * | asterisco |
| % | signo de porcentaje |
| + | signo más |
| = | signo igual |
| ~ | tilde |
Nombres de parámetros que no se pueden usar (RD03)
Windows PowerShell proporciona un conjunto común de parámetros a todos los cmdlets más parámetros adicionales que se agregan en situaciones específicas. Al diseñar sus propios cmdlets, no puede usar los nombres siguientes: Confirm, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, WarningVariable, WhatIf, UseTransaction y Verbose. Para obtener más información sobre estos parámetros, vea nombres de parámetros comunes.
Solicitudes de confirmación de soporte técnico (RD04)
En el caso de los cmdlets que realizan una operación que modifica el sistema, deben llamar al método System.Management.Automation.Cmdlet.ShouldProcess* para solicitar confirmación y, en casos especiales, llame al método System.Management.Automation.Cmdlet.ShouldContinue*. (Se debe llamar al método System.Management.Automation.Cmdlet.ShouldContinue* solo después de llamar al método System.Management.Automation.Cmdlet.ShouldProcess*).
Para realizar estas llamadas, el cmdlet debe especificar que admite solicitudes de confirmación estableciendo la palabra clave SupportsShouldProcess del atributo Cmdlet. Para obtener más información sobre cómo establecer este atributo, vea declaración de atributos de cmdlet.
Nota:
Si el atributo Cmdlet de la clase de cmdlet indica que el cmdlet admite llamadas al método System.Management.Automation.Cmdlet.ShouldProcess* y el cmdlet no puede realizar la llamada al método System.Management.Automation.Cmdlet.ShouldProcess*, el usuario podría modificar el sistema de forma inesperada.
Use el método System.Management.Automation.Cmdlet.ShouldProcess* para cualquier modificación del sistema. Una preferencia de usuario y el parámetro WhatIf controlan el método System.Management.Automation.Cmdlet.ShouldProcess*. En cambio, la llamada System.Management.Automation.Cmdlet.ShouldContinue* realiza una comprobación adicional de las modificaciones potencialmente peligrosas. Este método no está controlado por ninguna preferencia de usuario ni por el parámetro WhatIf. Si el cmdlet llama al método System.Management.Automation.Cmdlet.ShouldContinue*, debe tener un parámetro Force que omita las llamadas a estos dos métodos y que continúe con la operación. Esto es importante porque permite que el cmdlet se use en hosts y scripts no interactivos.
Si los cmdlets admiten estas llamadas, el usuario puede determinar si realmente se debe realizar la acción. Por ejemplo, el cmdlet Stop-Process llama al método System.Management.Automation.Cmdlet.ShouldContinue* antes de detener un conjunto de procesos críticos, incluidos los procesos System, Winlogon y Spoolsv.
Para obtener más información sobre cómo admitir estos métodos, vea Solicitud de confirmación.
Parámetro Force para sesiones interactivas (RD05)
Si el cmdlet se usa de forma interactiva, proporcione siempre un parámetro Force para invalidar las acciones interactivas, como mensajes o lectura de líneas de entrada). Esto es importante porque permite que el cmdlet se use en hosts y scripts no interactivos. Un host interactivo puede implementar los métodos siguientes.
System.Management.Automation.Host.PSHostUserInterface.Prompt*
System.Management.Automation.Host.PSHostUserInterface.PromptForChoice
System.Management.Automation.Host.IHostUISupportsMultipleChoiceSelection.PromptForChoice
System.Management.Automation.Host.PSHostUserInterface.PromptForCredential*
System.Management.Automation.Host.PSHostUserInterface.ReadLine*
System.Management.Automation.Host.PSHostUserInterface.ReadLineAsSecureString*
Objetos de salida de documento (RD06)
Windows PowerShell usa los objetos que se escriben en la canalización. Para que los usuarios aprovechen los objetos devueltos por cada cmdlet, debe documentar los objetos que se devuelven y debe documentar para qué se usan los miembros de esos objetos devueltos.
Directrices de código
Se deben seguir las instrucciones siguientes al escribir código de cmdlet. Cuando encuentre una guía de código que se aplique a su situación, asegúrese de examinar las directrices de diseño para obtener instrucciones similares.
Derivar de las clases cmdlet o PSCmdlet (RC01)
Un cmdlet debe derivar de la clase base System.Management.Automation.Cmdlet o System.Management.Automation.PSCmdlet. Los cmdlets que derivan de la clase System.Management.Automation.Cmdlet no dependen del entorno de ejecución de Windows PowerShell. Se puede llamar directamente desde cualquier lenguaje de Microsoft .NET Framework. Los cmdlets que derivan de la clase System.Management.Automation.PSCmdlet dependen del entorno de ejecución de Windows PowerShell. Por lo tanto, se ejecutan dentro de un espacio de ejecución.
Todas las clases de cmdlet que implemente deben ser clases públicas. Para obtener más información sobre estas clases de cmdlet, consulte Información general sobre cmdlets.
Especificar el atributo de cmdlet (RC02)
Para que Windows PowerShell reconozca un cmdlet, su clase de .NET Framework debe estar decorada con el atributo Cmdlet. Este atributo especifica las siguientes características del cmdlet.
Par verbo y sustantivo que identifica el cmdlet.
Conjunto de parámetros predeterminado que se usa cuando se especifican varios conjuntos de parámetros. El conjunto de parámetros predeterminado se usa cuando Windows PowerShell no tiene suficiente información para determinar qué parámetro se va a usar.
Indica si el cmdlet admite llamadas al método System.Management.Automation.Cmdlet.ShouldProcess*. Este método muestra un mensaje de confirmación al usuario antes de que el cmdlet realice un cambio en el sistema. Para obtener más información sobre cómo se realizan las solicitudes de confirmación, consulte solicitud de confirmación.
Indique el nivel de impacto (o gravedad) de la acción asociada al mensaje de confirmación. En la mayoría de los casos, se debe usar el valor predeterminado de Medium. Para obtener más información sobre cómo afecta el nivel de impacto a las solicitudes de confirmación que se muestran al usuario, consulte Requesting Confirmation.
Para obtener más información sobre cómo declarar el atributo de cmdlet, vea CmdletAttribute Declaration.
Invalidar un método de procesamiento de entrada (RC03)
Para que el cmdlet participe en el entorno de Windows PowerShell, debe invalidar al menos uno de los siguientes métodos de procesamiento de entrada .
System.Management.Automation.Cmdlet.BeginProcessing Este método se llama una vez y se usa para proporcionar funcionalidad de preprocesamiento.
System.Management.Automation.Cmdlet.ProcessRecord Este método se llama varias veces y se usa para proporcionar funcionalidad de registro por registro.
System.Management.Automation.Cmdlet.EndProcessing Este método se llama una vez y se usa para proporcionar funcionalidad posterior al procesamiento.
Especificar el atributo OutputType (RC04)
El atributo OutputType (introducido en Windows PowerShell 2.0) especifica el tipo de .NET Framework que el cmdlet devuelve a la canalización. Al especificar el tipo de salida de los cmdlets, los objetos devueltos por el cmdlet son más reconocibles por otros cmdlets. Para obtener más información sobre cómo decorar la clase de cmdlet con este atributo, consulte Declaración de atributo OutputType.
No conservar identificadores en objetos de salida (RC05)
El cmdlet no debe conservar los identificadores de los objetos que se pasan al método System.Management.Automation.Cmdlet.WriteObject*. Estos objetos se pasan al siguiente cmdlet de la canalización o los usa un script. Si conserva los identificadores de los objetos, dos entidades serán propietarias de cada objeto, lo que provocará errores.
Controlar errores de forma sólida (RC06)
Un entorno de administración detecta y realiza cambios importantes en el sistema que administra. Por lo tanto, es fundamental que los cmdlets controlen los errores correctamente. Para obtener más información sobre los registros de errores, vea informe de errores de Windows PowerShell.
Cuando un error impide que un cmdlet continúe procesando más registros, es un error de terminación. El cmdlet debe llamar al método System.Management.Automation.Cmdlet.ThrowTerminatingError* que hace referencia a un objeto System.Management.Automation.ErrorRecord. Si el cmdlet no detecta una excepción, el propio runtime de Windows PowerShell produce un error de terminación que contiene menos información.
Para un error de no terminación que no detenga la operación en el siguiente registro procedente de la canalización (por ejemplo, un registro generado por un proceso diferente), el cmdlet debe llamar al método System.Management.Automation.Cmdlet.WriteError* que hace referencia a un objeto System.Management.Automation.ErrorRecord. Un ejemplo de un error de no terminación es el error que se produce si un proceso determinado no se puede detener. Llamar al método System.Management.Automation.Cmdlet.WriteError* permite al usuario realizar de forma coherente las acciones solicitadas y conservar la información de acciones concretas que producen un error. El cmdlet debe controlar cada registro de la forma más independiente posible.
El objeto System.Management.Automation.ErrorRecord al que hace referencia el objeto System.Management.Automation.Cmdlet.ThrowTerminatingError* y System.Management.Automation.Cmdlet.WriteError* requiere una excepción en su núcleo. Siga las instrucciones de diseño de .NET Framework al determinar la excepción que se va a usar. Si el error es semánticamente igual que una excepción existente, use esa excepción o derive de esa excepción. De lo contrario, derive una nueva jerarquía de excepciones o excepciones directamente desde el tipo de System.Exception de.
Un objeto System.Management.Automation.ErrorRecord también requiere una categoría de error que agrupa los errores para el usuario. El usuario puede ver errores en función de la categoría estableciendo el valor de la variable de shell de $ErrorView en CategoryView. Las categorías posibles se definen mediante la enumeración System.Management.Automation.ErrorCategory.
Si un cmdlet crea un nuevo subproceso y, si el código que se ejecuta en ese subproceso produce una excepción no controlada, Windows PowerShell no detectará el error y finalizará el proceso.
Si un objeto tiene código en su destructor que provoca una excepción no controlada, Windows PowerShell no detectará el error y finalizará el proceso. Esto también ocurre si un objeto llama a métodos Dispose que provocan una excepción no controlada.
Usar un módulo de Windows PowerShell para implementar los cmdlets (RC07)
Cree un módulo de Windows PowerShell para empaquetar e implementar los cmdlets. La compatibilidad con módulos se presenta en Windows PowerShell 2.0. Puede usar los ensamblados que contienen las clases de cmdlet directamente como archivos de módulo binario (esto resulta muy útil al probar los cmdlets) o puede crear un manifiesto de módulo que haga referencia a los ensamblados de cmdlet. (También puede agregar ensamblados de complemento existentes al usar módulos). Para obtener más información sobre los módulos, consulte Escritura de un módulo de Windows PowerShell.
Véase también
instrucciones de desarrollo fuertemente fomentadas
