Directrices de desarrollo de consulta

En esta sección se describen las directrices que debe tener en cuenta para garantizar un buen desarrollo y experiencias de usuario. A veces podrían aplicarse y, a veces, no.

Directrices de diseño

Se deben tener en cuenta las instrucciones siguientes al diseñar 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.

Compatibilidad con un parámetro InputObject (AD01)

Dado que Windows PowerShell funciona directamente con objetos de Microsoft .NET Framework, un objeto de .NET Framework suele estar disponible que coincida exactamente con el tipo que el usuario necesita para realizar una operación determinada. InputObject es el nombre estándar de un parámetro que toma este objeto como entrada. Por ejemplo, el cmdlet de ejemplo Stop-Proc de StopProc Tutorial define un InputObject parámetro de tipo Process que admite la entrada de la canalización. El usuario puede obtener un conjunto de objetos de proceso, manipularlos para seleccionar los objetos exactos que se van a detener y, a continuación, pasarlos al Stop-Proc cmdlet directamente.

Compatibilidad con el parámetro Force (AD02)

En ocasiones, un cmdlet debe proteger al usuario de realizar una operación solicitada. Este cmdlet debe admitir un parámetro Force para permitir al usuario invalidar esa protección si el usuario tiene permisos para realizar la operación.

Por ejemplo, el cmdlet Remove-Item no suele quitar un archivo de solo lectura. Sin embargo, este cmdlet admite un parámetro Force para que un usuario pueda forzar la eliminación de un archivo de solo lectura. Si el usuario ya tiene permiso para modificar el atributo de solo lectura y el usuario quita el archivo, el uso del parámetro Force simplifica la operación. Sin embargo, si el usuario no tiene permiso para quitar el archivo, el parámetro Force no tiene ningún efecto.

Controlar credenciales a través de Windows PowerShell (AD03)

Un cmdlet debe definir un Credential parámetro para representar las credenciales. Este parámetro debe ser de tipo System.Management.Automation.PSCredential y debe definirse mediante una declaración de atributo Credential. Esta compatibilidad solicita automáticamente al usuario el nombre de usuario, la contraseña o ambas cuando no se proporciona directamente una credencial completa. Para obtener más información sobre el atributo Credential, vea Credential Attribute Declaration.

Compatibilidad con parámetros de codificación (AD04)

Si el cmdlet lee o escribe texto en un formulario binario, como escribir o leer desde un archivo en un sistema de archivos, el cmdlet debe tener el parámetro Encoding que especifica cómo se codifica el texto en el formulario binario.

Los cmdlets de prueba deben devolver un valor booleano (AD05)

Los cmdlets que realizan pruebas en sus recursos deben devolver un tipo System.Boolean a la canalización para que se puedan usar en expresiones condicionales.

Directrices de código

Se deben tener en cuenta las instrucciones siguientes al escribir código de cmdlet. Cuando encuentre una guía que se aplique a su situación, asegúrese de consultar las directrices de diseño para obtener instrucciones similares.

Seguir las convenciones de nomenclatura de clases de cmdlet (AC01)

Al seguir las convenciones de nomenclatura estándar, los cmdlets son más reconocibles y ayuda al usuario a comprender exactamente lo que hacen los cmdlets. Esta práctica es especialmente importante para otros desarrolladores que usan Windows PowerShell porque los cmdlets son tipos públicos.

Definición de un cmdlet en el espacio de nombres correcto

Normalmente, se define la clase para un cmdlet en un espacio de nombres de .NET Framework que se anexa .Commands al espacio de nombres que representa el producto en el que se ejecuta el cmdlet. Por ejemplo, los cmdlets que se incluyen con Windows PowerShell se definen en el Microsoft.PowerShell.Commands espacio de nombres .

Asigne un nombre a la clase de cmdlet para que coincida con el nombre del cmdlet.

Al asignar un nombre a la clase de .NET Framework que implementa un cmdlet, asigne un nombre a la clase <Verb><Noun>Command, donde reemplace los <Verb> marcadores de posición y <Noun> por el verbo y el nombre que se usa para el nombre del cmdlet. Por ejemplo, el cmdlet Get-Process se implementa mediante una clase denominada GetProcessCommand.

Si ninguna entrada de canalización invalida el método BeginProcessing (AC02)

Si el cmdlet no acepta la entrada de la canalización, el procesamiento debe implementarse en el método System.Management.Automation.Cmdlet.BeginProcessing . El uso de este método permite a Windows PowerShell mantener el orden entre cmdlets. El primer cmdlet de la canalización siempre devuelve sus objetos antes de que los cmdlets restantes de la canalización obtengan la oportunidad de iniciar su procesamiento.

Para controlar las solicitudes de detención, invalide el método StopProcessing (AC03)

Invalide el método System.Management.Automation.Cmdlet.StopProcessing para que el cmdlet pueda controlar la señal de detención. Algunos cmdlets tardan mucho tiempo en completar su operación y permiten pasar mucho tiempo entre llamadas al entorno de ejecución de Windows PowerShell, como cuando el cmdlet bloquea el subproceso en llamadas RPC de larga duración. Esto incluye cmdlets que realizan llamadas al método System.Management.Automation.Cmdlet.WriteObject , al método System.Management.Automation.Cmdlet.WriteError y a otros mecanismos de comentarios que pueden tardar mucho tiempo en completarse. En estos casos, es posible que el usuario tenga que enviar una señal de detención a estos cmdlets.

Implementar la interfaz IDisposable (AC04)

Si el cmdlet tiene objetos que no se eliminan (escritos en la canalización) mediante el método System.Management.Automation.Cmdlet.ProcessRecord , el cmdlet podría requerir la eliminación de objetos adicional. Por ejemplo, si el cmdlet abre un identificador de archivo en su método System.Management.Automation.Cmdlet.BeginProcessing y mantiene el identificador abierto para que lo use el método System.Management.Automation.Cmdlet.ProcessRecord , este identificador debe cerrarse al final del procesamiento.

El entorno de ejecución de Windows PowerShell no siempre llama al método System.Management.Automation.Cmdlet.EndProcessing . Por ejemplo, es posible que no se llame al método System.Management.Automation.Cmdlet.EndProcessing si el cmdlet se cancela a mitad de su operación o si se produce un error de terminación en cualquier parte del cmdlet. Por lo tanto, la clase de .NET Framework para un cmdlet que requiere limpieza de objetos debe implementar el patrón de interfaz System.IDisposable completo, incluido el finalizador, para que el entorno de ejecución de Windows PowerShell pueda llamar a los métodos System.Management.Automation.Cmdlet.EndProcessing y System.IDisposable.Dispose* al final del procesamiento.

Usar tipos de parámetros descriptivos de serialización (AC05)

Para admitir la ejecución del cmdlet en equipos remotos, use tipos que se pueden serializar en el equipo cliente y, a continuación, rehidratar en el equipo servidor. Los siguientes tipos son compatibles con la serialización.

Tipos primitivos:

• Byte, SByte, Decimal, Single, Double, Int16, Int32, Int64, Uint16, UInt32 y UInt64.
• Boolean, Guid, Byte[], TimeSpan, DateTime, Uri y Version.
• Char, String, XmlDocument.

Tipos rehidratables integrados:

• PSPrimitiveDictionary
• SwitchParameter
• PSListModifier
• PSCredential
• IPAddress, MailAddress
• CultureInfo
• X509Certificate2, X500DistinguishedName
• DirectorySecurity, FileSecurity, RegistrySecurity

Otros tipos:

• SecureString
• Contenedores (listas y diccionarios del tipo anterior)

Uso de SecureString para datos confidenciales (AC06)

Al controlar los datos confidenciales, use siempre el tipo de datos System.Security.SecureString . Esto podría incluir la entrada de canalización en parámetros, así como devolver datos confidenciales a la canalización.

Aunque .NET recomienda usar SecureString para el nuevo desarrollo, PowerShell sigue admitiendo la clase SecureString para la compatibilidad con versiones anteriores. El uso de una SecureString sigue siendo más seguro que usar una cadena de texto sin formato. PowerShell todavía se basa en el tipo SecureString para evitar exponer accidentalmente el contenido a la consola o en los registros. Use SecureString cuidadosamente, ya que se puede convertir fácilmente en una cadena de texto sin formato. Para obtener una explicación completa sobre el uso de SecureString, consulte la documentación de Clase System.Security.SecureString.

Véase también

directrices de desarrollo necesarias

instrucciones de desarrollo fuertemente fomentadas

escribir un cmdlet de Windows PowerShell