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 se pueden aplicar y, a veces, es posible que no.
Directrices de diseño
Se deben tener en cuenta las siguientes directrices al diseñar cmdlets. Cuando encuentre una guía de diseño que se aplique a su situación, asegúrese de ver las directrices de código para instrucciones similares.
Compatibilidad con un parámetro InputObject (AD01)
Dado Windows PowerShell funciona directamente con objetos de Microsoft .NET Framework, a menudo hay disponible un objeto .NET Framework que coincide 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 un objeto como entrada.
Por ejemplo, el cmdlet de ejemplo del tutorial StopProc define un parámetro de Stop-Proc tipo Process que admite la entrada de la InputObject canalización. El usuario puede obtener un conjunto de objetos de proceso, manipularlos para seleccionar los objetos exactos que se detendrá 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 que el usuario invalide esa protección si el usuario tiene permisos para realizar la operación.
Por ejemplo, el cmdlet Remove-Item normalmente no quita 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 las credenciales mediante 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 ambos cuando no se proporciona una credencial completa directamente. Para obtener más información sobre el atributo Credential, vea Declaración de atributo de credencial.
Compatibilidad con parámetros de codificación (AD04)
Si el cmdlet lee o escribe texto en o desde un formulario binario, como escribir en un archivo en un sistema de archivos o leerlo desde este, el cmdlet debe tener el parámetro Encoding que especifique cómo se codifica el texto en formato 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 siguientes directrices al escribir código de cmdlet. Cuando encuentre una directriz que se aplique a su situación, asegúrese de buscar directrices de diseño para instrucciones similares.
Seguir las convenciones de nomenclatura de clases de cmdlets (AC01)
Al seguir las convenciones de nomenclatura estándar, los cmdlets son más reconocibles y ayudan 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.
Definir un cmdlet en el espacio de nombres correcto
Normalmente se define la clase para un cmdlet en un espacio .NET Framework de nombres que anexa ". Comandos" para el 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 espacio de Microsoft.PowerShell.Commands nombres .
Asigne un nombre a la clase de cmdlet para que coincida con el nombre del cmdlet.
Cuando asigne un nombre a la clase .NET Framework que implementa un cmdlet, asigne un nombre a la clase " ", donde reemplace los marcadores de posición y por el verbo y el nombre que se usa para el <Verb><Noun><Command> <Verb> nombre del <Noun> 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 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 puedan iniciar su procesamiento.
Para controlar las solicitudes de detenerse, 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 detenerse. Algunos cmdlets necesitan mucho tiempo para completar su operación y permiten pasar mucho tiempo entre las llamadas al entorno de ejecución de Windows PowerShell, como cuando el cmdlet bloquea el subproceso en llamadas RPC de ejecución larga. Esto incluye cmdlets que hacen 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 detenerse a estos cmdlets.
Implementación de la interfaz IDisposable (AC04)
Si el cmdlet tiene objetos que el método System.Management.Automation.Cmdlet.ProcessRecord no desecharon (escritos en la canalización), es posible que el cmdlet requiera 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 Windows PowerShell runtime 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 .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 compatibles con la serialización (AC05)
Para admitir la ejecución del cmdlet en equipos remotos, use tipos que se puedan serializar fácilmente en el equipo cliente y, a continuación, rehidratarse en el equipo servidor. Los tipos siguientes son descriptivos para 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 rehidrátibles 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 datos confidenciales, use siempre el tipo de datos System.Security.Securestring. Esto podría incluir la entrada de canalización a los parámetros, así como la devolución de datos confidenciales a la canalización.
Consulte también
Directrices de desarrollo necesarias
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de