Directrices de desarrollo recomendadas encarecidamente

En esta sección se describen las directrices que debe seguir al escribir los cmdlets. Se separan en directrices para diseñar cmdlets y directrices para escribir tu código de cmdlet. Es posible que estas directrices no sean aplicables a cada escenario. Sin embargo, si se aplican y usted no sigue estas instrucciones, es posible que los usuarios tengan una mala experiencia cuando usan sus cmdlets.

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 un sustantivo específico para el nombre de un cmdlet (SD01)

Los sustantivos utilizados en la denominación de los cmdlets deben ser muy específicos para que el usuario pueda descubrir sus cmdlets. Prefije nombres genéricos como "servidor" con una versión abreviada del nombre del producto. Por ejemplo, si un nombre hace referencia a un servidor que ejecuta una instancia de Microsoft SQL Server, use un nombre como "SQLServer". La combinación de nombres específicos y la breve lista de verbos aprobados permiten al usuario detectar y anticipar rápidamente la funcionalidad, a la vez que evita la duplicación entre los nombres de cmdlet.

Para mejorar la experiencia del usuario, el nombre que elija para un nombre de cmdlet debe ser singular. Por ejemplo, use el nombre Get-Process en lugar de Get-Processes. Es mejor seguir esta regla para todos los nombres de cmdlet, incluso cuando es probable que un cmdlet actúe con más de un elemento.

Usar el caso Pascal para los nombres de cmdlet (SD02)

Use el caso Pascal para los nombres de parámetro. En otras palabras, capitalice la primera letra del verbo y todos los términos usados en el nombre. Por ejemplo, "Clear-ItemProperty".

Directrices de diseño de parámetros (SD03)

Un cmdlet necesita parámetros que reciban los datos en los que debe funcionar y los parámetros que indican información que se usa para determinar las características de la operación. Por ejemplo, un cmdlet podría tener un Name parámetro que reciba datos de la canalización y el cmdlet podría tener un Force parámetro para indicar que el cmdlet se puede forzar para realizar su operación. No hay ningún límite para el número de parámetros que un cmdlet puede definir.

Usar nombres de parámetro estándar

El cmdlet debe usar nombres de parámetro estándar para que el usuario pueda determinar rápidamente qué significa un parámetro determinado. Si se requiere un nombre más específico, use un nombre de parámetro estándar y, a continuación, especifique un nombre más específico como alias. Por ejemplo, el Get-Service cmdlet tiene un parámetro que tiene un nombre genérico (Name) y un alias más específico (ServiceName). Ambos términos se pueden usar para especificar el parámetro .

Para obtener más información sobre los nombres de parámetro y sus tipos de datos, vea Cmdlet Parameter Name and Functionality Guidelines.

Usar nombres de parámetro singular

Evite usar nombres plurales para parámetros cuyo valor sea un único elemento. Esto incluye parámetros que toman matrices o listas porque el usuario puede proporcionar una matriz o lista con un solo elemento.

Los nombres de parámetro plural solo se deben usar en aquellos casos en los que el valor del parámetro siempre sea un valor de varios elementos. En estos casos, el cmdlet debe comprobar que se proporcionan varios elementos y el cmdlet debe mostrar una advertencia al usuario si no se proporcionan varios elementos.

Usa mayúsculas de Pascal para nombres de parámetros

Use el caso Pascal para los nombres de parámetro. En otras palabras, escriba en mayúsculas la primera letra de cada palabra del nombre del parámetro, incluida la primera letra del nombre. Por ejemplo, el nombre ErrorAction del parámetro usa la mayúscula correcta. Los nombres de parámetro siguientes usan mayúsculas incorrectas:

• errorAction
• erroraction

Parámetros que aceptan una lista de opciones

Hay dos maneras de crear un parámetro cuyo valor se puede seleccionar a partir de un conjunto de opciones.

• Defina un tipo de enumeración (o use un tipo de enumeración existente) que especifique los valores válidos. A continuación, use el tipo de enumeración para crear un parámetro de ese tipo.

• Agregue el atributo ValidateSet a la declaración de parámetros. Para obtener más información sobre este atributo, vea ValidateSet Attribute Declaration.

Uso de tipos estándar para parámetros

Para garantizar la coherencia con otros cmdlets, use tipos estándar para parámetros siempre que sea posible. Para obtener más información sobre los tipos que se deben usar para distintos parámetros, consulte Standard Cmdlet Parameter Names and Types. En este tema se proporcionan vínculos a varios temas que describen los nombres y los tipos de .NET Framework para grupos de parámetros estándar, como los "parámetros de actividad".

Tipos Fuertemente Tipados del .NET Framework

Los parámetros deben definirse como tipos de .NET Framework para proporcionar una mejor validación de parámetros. Por ejemplo, los parámetros que están restringidos a un valor de un conjunto de valores deben definirse como un tipo de enumeración. Para admitir un valor de Identificador uniforme de recursos (URI), defina el parámetro como un tipo System.Uri . Evite parámetros de cadena simples excepto para propiedades de texto libre.

Uso de tipos de parámetro coherentes

Cuando varios cmdlets usan el mismo parámetro, use siempre el mismo tipo de parámetro. Por ejemplo, si el Process parámetro es un tipo System.Int16 para un cmdlet, no convierta el Process parámetro para otro cmdlet en un tipo System.Uint16 .

Parámetros que toman los valores True y False

Si su parámetro solo toma true y false, defina el parámetro como tipo System.Management.Automation.SwitchParameter. Un [switch] parámetro se trata como true cuando se especifica en un comando. Si el parámetro no está incluido en un comando, Windows PowerShell considera que el valor del parámetro es false. No defina parámetros booleanos.

Si su parámetro necesita diferenciar entre tres valores: $true, $false y "sin especificar", defina un parámetro de tipo Nullable<bool>. La necesidad de un tercer valor "sin especificar" normalmente se produce cuando el cmdlet puede modificar una propiedad booleana de un objeto. En este caso, "sin especificar" significa no cambiar el valor actual de la propiedad.

Compatibilidad con matrices para parámetros

Con frecuencia, los usuarios deben realizar la misma operación con varios argumentos. Para estos usuarios, un cmdlet debe aceptar una matriz como entrada de parámetro para que un usuario pueda pasar los argumentos al parámetro como una variable de PowerShell de Windows. Por ejemplo, el cmdlet Get-Process usa una matriz para las cadenas que identifican los nombres de los procesos que se van a recuperar.

Soporte para el parámetro PassThru

De forma predeterminada, muchos cmdlets que modifican el sistema, como el cmdlet Stop-Process, funcionan como "receptores" de objetos y no devuelven un resultado. Este cmdlet debe implementar el PassThru parámetro para forzar al cmdlet a devolver un objeto . Cuando se especifica el PassThru parámetro , el cmdlet devuelve un objeto mediante una llamada al método System.Management.Automation.Cmdlet.WriteObject . Por ejemplo, el siguiente comando detiene Calc (CalculatorApp.exe) y pasa el proceso resultante a la canalización.

Stop-Process -Name CalculatorApp -PassThru

En la mayoría de los casos, los cmdlets Add, Set y New deben admitir un PassThru parámetro.

Soporte para conjuntos de parámetros

Un cmdlet está pensado para lograr un único propósito. Sin embargo, con frecuencia hay más de una manera de describir la operación o el destino de la operación. Por ejemplo, un proceso podría identificarse por su nombre, por su identificador o por un objeto de proceso. El cmdlet debe admitir todas las representaciones razonables de sus destinos. Normalmente, el cmdlet cumple este requisito especificando conjuntos de parámetros (denominados conjuntos de parámetros) que funcionan juntos. Un único parámetro puede pertenecer a cualquier número de conjuntos de parámetros. Para obtener más información sobre los conjuntos de parámetros, consulte Cmdlet Parameter Sets.

Al especificar conjuntos de parámetros, establezca solo un parámetro en el conjunto en ValueFromPipeline. Para obtener más información sobre cómo declarar el atributo Parameter , vea ParameterAttribute Declaration.

Cuando se usan conjuntos de parámetros, el conjunto de parámetros predeterminado se define mediante el atributo Cmdlet . El conjunto de parámetros predeterminado debe incluir los parámetros que es más probable que se usen en una sesión interactiva de PowerShell Windows. Para obtener más información sobre cómo declarar el atributo Cmdlet , vea CmdletAttribute Declaration.

Proporcionar comentarios al usuario (SD04)

Use las instrucciones de esta sección para proporcionar comentarios al usuario. Estos comentarios permiten al usuario tener en cuenta lo que ocurre en el sistema y tomar mejores decisiones administrativas.

El tiempo de ejecución de Windows PowerShell permite a un usuario especificar cómo controlar la salida de cada llamada al método Write al establecer una variable de preferencia. El usuario puede establecer varias variables de preferencia, incluida una variable que determina si el sistema debe mostrar información y una variable que determina si el sistema debe consultar al usuario antes de realizar más acciones.

Compatibilidad con los métodos WriteWarning, WriteVerbose y WriteDebug

Un cmdlet debe llamar al método System.Management.Automation.Cmdlet.WriteWarning cuando el cmdlet está a punto de realizar una operación que podría tener un resultado no deseado. Por ejemplo, un cmdlet debe llamar a este método si el cmdlet está a punto de sobrescribir un archivo de solo lectura.

Un cmdlet debe llamar al método System.Management.Automation.Cmdlet.WriteVerbose cuando el usuario requiere algunos detalles sobre lo que hace el cmdlet. Por ejemplo, un cmdlet debe llamar a esta información si el autor del cmdlet considera que hay escenarios que pueden requerir más información sobre lo que hace el cmdlet.

El cmdlet debe llamar al método System.Management.Automation.Cmdlet.WriteDebug cuando un ingeniero de soporte técnico para desarrolladores o productos debe comprender lo que ha dañado la operación del cmdlet. No es necesario que el cmdlet llame al método System.Management.Automation.Cmdlet.WriteDebug en el mismo código que llama al método System.Management.Automation.Cmdlet.WriteVerbose porque el Debug parámetro presenta ambos conjuntos de información.

Compatibilidad con WriteProgress para operaciones que tardan mucho tiempo

Las operaciones de cmdlet que tardan mucho tiempo en completarse y que no se pueden ejecutar en segundo plano deben admitir informes de progreso a través de llamadas periódicas al método System.Management.Automation.Cmdlet.WriteProgress .

Uso de las interfaces del anfitrión

En ocasiones, un cmdlet debe comunicarse directamente con el usuario en lugar de usar los distintos métodos Write o Should admitidos por la clase System.Management.Automation.Cmdlet . En este caso, el cmdlet debe derivar de la clase System.Management.Automation.PSCmdlet y usar la propiedad System.Management.Automation.PSCmdlet.Host* . Esta propiedad admite distintos niveles de tipo de comunicación, incluidos los tipos PromptForChoice, Prompt y WriteLine/ReadLine. En el nivel más específico, también provee formas de leer y escribir claves individuales y manipular búferes.

A menos que un cmdlet esté diseñado específicamente para generar una interfaz gráfica de usuario (GUI), no debe omitir el host mediante la propiedad System.Management.Automation.PSCmdlet.Host* . Un ejemplo de un cmdlet diseñado para generar una GUI es el cmdlet Out-GridView.

Crear un archivo de ayuda de cmdlet (SD05)

Para cada ensamblado de cmdlet, cree un archivo Help.xml que contenga información sobre el cmdlet. Esta información incluye una descripción del cmdlet, descripciones de los parámetros del cmdlet, ejemplos del uso del cmdlet, etc.

Directrices de código

Deben seguirse las siguientes pautas al programar cmdlets para garantizar una experiencia de usuario coherente entre el uso de tus cmdlets y otros cmdlets. 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.

Parámetros de codificación (SC01)

Defina un parámetro declarando una propiedad pública de la clase de cmdlet que está decorada con el atributo Parameter . Los parámetros no tienen que ser miembros estáticos de la clase derivada .NET Framework para el cmdlet . Para obtener más información sobre cómo declarar el atributo Parameter , vea Parameter Attribute Declaration.

Compatibilidad con rutas de Windows PowerShell

La ruta de acceso de Windows PowerShell es el mecanismo para normalizar el acceso a los espacios de nombres. Al asignar una ruta de acceso de Windows PowerShell a un parámetro del cmdlet, el usuario puede definir una unidad personalizada que funcione como un acceso directo a una ruta de acceso específica. Cuando un usuario designa dicha unidad, los datos almacenados, como los datos del Registro, se pueden usar de forma coherente.

Si el cmdlet permite al usuario especificar un archivo o un origen de datos, debe definir un parámetro de tipo System.String. Si se admite más de una unidad, el tipo debería ser una matriz. El nombre del parámetro debe ser Path, con un alias de PSPath. Además, el Path parámetro debe admitir caracteres comodín. Si no se requiere compatibilidad con caracteres comodín, defina un LiteralPath parámetro.

Si los datos que lee o escribe el cmdlet deben ser un archivo, el cmdlet debe aceptar la ruta de acceso de PowerShell de Windows y usar la propiedad System.Management.Automation.SessionState.Path para traducir las rutas de acceso de PowerShell de Windows en las que el sistema de archivos reconoce. Entre los mecanismos específicos se incluyen los métodos siguientes:

• System.Management.Automation.PSCmdlet.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PSCmdlet.GetUnresolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetUnresolvedProviderPathFromPSPath

Si los datos que el cmdlet lee o escribe son solo un conjunto de cadenas en lugar de un archivo, el cmdlet debe usar la información de contenido del proveedor (Content miembro) para leer y escribir. Esta información se obtiene de la propiedad System.Management.Automation.Provider.CmdletProvider.InvokeProvider . Estos mecanismos permiten que otros almacenes de datos participen en la lectura y escritura de datos.

Compatibilidad con caracteres comodín

Si es posible, un cmdlet debe admitir caracteres comodín. La compatibilidad con caracteres comodín se produce en muchos lugares de un cmdlet (especialmente cuando un parámetro toma una cadena para identificar un objeto de un conjunto de objetos). Por ejemplo, el cmdlet de ejemplo Stop-Proc del Tutorial de StopProc define un Name parámetro para controlar cadenas que representan nombres de proceso. Este parámetro admite caracteres comodín para que el usuario pueda especificar fácilmente los procesos que se van a detener.

Cuando la compatibilidad con caracteres comodín está disponible, una operación de cmdlet normalmente genera una matriz. En ocasiones, no tiene sentido admitir una matriz porque el usuario podría usar solo un solo elemento a la vez. Por ejemplo, el cmdlet Set-Location no necesita admitir una matriz porque el usuario está estableciendo solo una ubicación. En este caso, el cmdlet todavía admite caracteres comodín, pero fuerza la resolución a una sola ubicación.

Para obtener más información sobre los patrones de caracteres comodín, vea Compatibilidad de caracteres comodín en parámetros de cmdlet.

Definir objetos

Esta sección contiene instrucciones para definir objetos para cmdlets y para extender objetos existentes.

Definir miembros estándar

Defina miembros estándar para extender un tipo de objeto en un archivo Types.ps1xml personalizado (use el archivo Windows PowerShell Types.ps1xml como plantilla). Los miembros estándar se definen mediante un nodo con el nombre PSStandardMembers. Estas definiciones permiten que otros cmdlets y el entorno de ejecución de PowerShell de Windows funcionen con el objeto de forma coherente.

Definir ObjectMembers que se van a usar como parámetros

Si va a diseñar un objeto para un cmdlet, asegúrese de que sus miembros se asignan directamente a los parámetros de los cmdlets que lo usarán. Esta asignación permite que el objeto se envíe fácilmente a la canalización y que se pase de un cmdlet a otro.

Los objetos del marco .NET preexistente que devuelven los cmdlets frecuentemente les faltan algunos miembros importantes o convenientes que necesitan el desarrollador de scripts o el usuario. Estos miembros que faltan pueden ser especialmente importantes para mostrar y para crear los nombres de miembro correctos para que el objeto se pueda pasar correctamente a la canalización. Cree un archivo Types.ps1xml personalizado para documentar estos miembros necesarios. Al crear este archivo, se recomienda la siguiente convención de nomenclatura: <Your_Product_Name>. Types.ps1xml.

Por ejemplo, podría agregar una Mode propiedad de script al tipo System.IO.FileInfo para mostrar los atributos de un archivo con más claridad. Además, podría agregar una Count propiedad de alias al tipo System.Array para permitir el uso coherente de ese nombre de propiedad (en lugar de Length).

Implementar la interfaz IComparable

Implemente una interfaz System.IComparable en todos los objetos de salida. Esto permite canalizar fácilmente los objetos de salida a varios cmdlets de ordenación y análisis.

Actualizar información de pantalla

Si la presentación de un objeto no proporciona los resultados esperados, cree un archivo Format.ps1xml de YourProductName< personalizado> para ese objeto.

Compatibilidad con la entrada de canalización bien definida (SC02)

Implementación para el medio de una canalización

Implemente un cmdlet suponiendo que se llamará desde la mitad de una canalización (es decir, otros cmdlets generarán su entrada o consumirán su salida). Por ejemplo, puede suponer que el Get-Process cmdlet, ya que genera datos, solo se usa como primer cmdlet de una canalización. Sin embargo, dado que este cmdlet está diseñado para el medio de una canalización, este cmdlet permite que los cmdlets o datos anteriores de la canalización especifiquen los procesos que se van a recuperar.

Compatibilidad con la entrada desde la canalización

En cada conjunto de parámetros de un cmdlet, incluya al menos un parámetro que admita la entrada de la canalización. La compatibilidad con la entrada de canalización permite al usuario recuperar datos u objetos, enviarlos al conjunto de parámetros correcto y pasar los resultados directamente a un cmdlet.

Un parámetro acepta la entrada de la canalización si el atributo Parameter incluye la ValueFromPipeline palabra clave , el ValueFromPipelineByPropertyName atributo de palabra clave o ambas palabras clave en su declaración. Si ninguno de los parámetros de un conjunto de parámetros admite las ValueFromPipeline palabras clave o ValueFromPipelineByPropertyName, el cmdlet no se puede colocar de manera significativa después de otro cmdlet porque omitirá cualquier entrada del sistema de canalización.

Compatibilidad con el método ProcessRecord

Para aceptar todos los registros del cmdlet anterior en la canalización, el cmdlet debe implementar el método System.Management.Automation.Cmdlet.ProcessRecord . Windows PowerShell llama a este método varias veces, una vez por cada registro que se envía al cmdlet.

Escribir registros únicos en la canalización (SC03)

Cuando un cmdlet devuelve objetos, el cmdlet debe escribir los objetos inmediatamente a medida que se generan. El cmdlet no debe retenerlos para almacenarlos en un búfer dentro de una matriz combinada. Los cmdlets que reciben los objetos como entrada podrán procesar, mostrar o procesar y mostrar los objetos de salida sin demora. Un cmdlet que genera objetos de salida de uno en uno debe llamar al método System.Management.Automation.Cmdlet.WriteObject . Un cmdlet que genera objetos de salida en lotes (por ejemplo, porque una API subyacente devuelve una matriz de objetos de salida) debe llamar al método System.Management.Automation.Cmdlet.WriteObject con su segundo parámetro establecido trueen .

Hacer que los Cmdlets sean insensibles a mayúsculas y preserven el uso de mayúsculas (SC04)

De forma predeterminada, Windows powerShell no distingue mayúsculas de minúsculas. Sin embargo, dado que se ocupa de muchos sistemas preexistentes, Windows PowerShell conserva el caso para facilitar el funcionamiento y la compatibilidad. Es decir, si se proporciona un carácter en mayúsculas, Windows PowerShell lo mantiene en mayúsculas. Para que los sistemas funcionen bien, un cmdlet debe seguir esta convención. Si es posible, debe funcionar de una manera que no distingue mayúsculas de minúsculas. Sin embargo, debe conservar el caso original de los cmdlets que se producen más adelante en un comando o en la canalización.

Véase también

Directrices de desarrollo necesarias

Directrices de desarrollo de asesoramiento

Escribir un cmdlet de PowerShell de Windows