Directrices de desarrollo recomendadas encarecidamente

  • Artículo

En esta sección se describen las directrices que debe seguir al escribir los cmdlets. Se separan en instrucciones para diseñar cmdlets e instrucciones para escribir el código del cmdlet. Es posible que encuentre que estas directrices no son aplicables a todos los escenarios. Sin embargo, si se aplican y no se siguen estas directrices, es posible que los usuarios tengan una experiencia deficiente al usar los cmdlets.

Directrices de diseño

Se deben seguir las siguientes directrices 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 buscar instrucciones similares en las directrices de código.

Usar un nombre específico para un nombre de cmdlet (SD01)

Los nombres usados en la nomenclatura de cmdlets deben ser muy específicos para que el usuario pueda detectar los cmdlets. Prefijo de nombres genéricos como "servidor" con una versión abreviada del nombre del producto. Por ejemplo, si un sustantivo 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 prever rápidamente la funcionalidad, al tiempo 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 en Get-Process lugar de Get-Processes . Es mejor seguir esta regla para todos los nombres de cmdlet, incluso cuando es probable que un cmdlet actúe sobre más de un elemento.

Uso de Pascal Case para nombres de cmdlet (SD02)

Use el caso Pascal para los nombres de parámetro. En otras palabras, en mayúsculas, la primera letra del verbo y todos los términos usados en el sustantivo. 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 operar y parámetros que indiquen información que se usa para determinar las características de la operación. Por ejemplo, un cmdlet podría tener un parámetro que recibe datos de la canalización y el cmdlet podría tener un parámetro para indicar que el cmdlet se puede forzar para Name Force realizar su operación. No hay ningún límite en el número de parámetros que puede definir un cmdlet.

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 lo que 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 cmdlet tiene un parámetro que tiene un nombre genérico ( ) y Get-Service un alias más específico ( Name ServiceName ). Ambos términos se pueden usar para especificar el parámetro .

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

Usar nombres de parámetro singulares

Evite el uso de nombres plurales para los parámetros cuyo valor es un único elemento. Esto incluye parámetros que toman matrices o listas porque el usuario podría proporcionar una matriz o lista con un solo elemento.

Los nombres de parámetros plurales solo se deben usar en aquellos casos en los que el valor del parámetro sea siempre 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.

Uso de pascal case para nombres de parámetro

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

  • errorAction
  • erroraction

Parámetros que toman una lista de opciones

Hay dos maneras de crear un parámetro cuyo valor se puede seleccionar 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ámetro. Para obtener más información sobre este atributo, vea ValidateSet Attribute Declaration.

Usar tipos estándar para parámetros

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

Usar Strongly-Typed .NET Framework tipos de datos

Los parámetros deben definirse como tipos .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 los parámetros de cadena básicos para todas las propiedades de texto de forma libre, pero sin formato.

Usar tipos de parámetros coherentes

Cuando varios cmdlets usen el mismo parámetro, use siempre el mismo tipo de parámetro. Por ejemplo, si el parámetro es un tipo System.Int16 para un cmdlet, no haga que el parámetro de otro Process cmdlet sea de tipo Process System.Uint16.

Parámetros que toman True y False

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

Si el parámetro necesita diferenciar entre 3 valores: $true, $false y "unspecified", defina un parámetro de tipo que acepta valores <bool> NULL. La necesidad de un tercer valor "sin especificar" suele producirse 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 de matrices para parámetros

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

Compatibilidad con el parámetro PassThru

De forma predeterminada, muchos cmdlets que modifican el sistema, como el cmdlet Stop-Process, actúan como "receptores" para los 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 parámetro , el cmdlet devuelve un objeto mediante una llamada al método PassThru System.Management.Automation.Cmdlet.WriteObject. Por ejemplo, el siguiente comando detiene el proceso calc y pasa el proceso resultante a la canalización.

Stop-Process calc -passthru

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

Compatibilidad con 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 satisface 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, vea Cmdlet Parameter Sets.

Al especificar conjuntos de parámetros, establezca solo un parámetro del 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 atributo Cmdlet define el conjunto de parámetros predeterminado. El conjunto de parámetros predeterminado debe incluir los parámetros que es más probable que se utilicen en una sesión Windows PowerShell interactiva. Para obtener más información sobre cómo declarar el atributo Cmdlet, vea Declaración de CmdletAttribute.

Proporcionar comentarios al usuario (SD04)

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

El Windows PowerShell de ejecución permite a un usuario especificar cómo controlar la salida de cada llamada al método Write estableciendo 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 tomar medidas adicionales.

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 requiera algún detalle 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 desarrollador o ingeniero de soporte técnico de producto 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 parámetro presenta ambos conjuntos de Debug información.

Compatibilidad con WriteProgress para operaciones que llevan mucho tiempo

Las operaciones de cmdlet que llevan 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 de host

En ocasiones, un cmdlet debe comunicarse directamente con el usuario en lugar de mediante 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 diferentes niveles de tipo de comunicación, incluidos los tipos PromptForChoice, Prompt y WriteLine/ReadLine. En el nivel más específico, también proporciona maneras de leer y escribir claves individuales y tratar con 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.

Nota

Los cmdlets no deben usar la API System.Console.

Crear un archivo de ayuda de cmdlet (SD05)

Para cada ensamblado de cmdlet, cree un 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 y mucho más.

Directrices de código

Se deben seguir las instrucciones siguientes al codificar cmdlets para garantizar una experiencia de usuario coherente entre el uso de los cmdlets y otros cmdlets. Cuando encuentre una guía de código que se aplique a su situación, asegúrese de buscar directrices de diseño para instrucciones similares.

Parámetros de codificación (SC01)

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

Compatibilidad con Windows PowerShell de acceso

La Windows PowerShell de acceso es el mecanismo para normalizar el acceso a los espacios de nombres. Al asignar una ruta de acceso Windows PowerShell a un parámetro en el cmdlet , el usuario puede definir una "unidad" personalizada que actúe como 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 debe ser una matriz. El nombre del parámetro debe ser Path , con un alias de PSPath . Además, el parámetro Path 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 Windows PowerShell cmdlet deben ser un archivo, el cmdlet debe aceptar una entrada de ruta de acceso y el cmdlet debe usar la propiedad System.Management.Automation.Sessionstate.Path para convertir las rutas de acceso de Windows PowerShell en rutas de acceso que el sistema de archivos reconoce. Los mecanismos específicos incluyen los métodos siguientes:

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

Admitir 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 del tutorial StopProc define un parámetro para controlar Stop-Proc las Name 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 deben detener.

Cuando hay disponible compatibilidad con caracteres comodín, 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 elemento a la vez. Por ejemplo, el cmdlet Set-Location no necesita admitir una matriz porque el usuario establece solo una ubicación. En esta instancia, 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 Admitir 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.

Definición de miembros estándar

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

Definir ObjectMembers para que se utilicen 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 se pase de un cmdlet a otro.

A los objetos .NET Framework que devuelven los cmdlets les faltan con frecuencia algunos miembros importantes o prácticos que el desarrollador o el usuario del script necesitan. Estos miembros que faltan pueden ser especialmente importantes para mostrar y 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 propiedad de script al tipo Mode System.IO.FileInfo para mostrar los atributos de un archivo con mayor claridad. Además, podría agregar una propiedad de alias al tipo System.Array para permitir el uso coherente de ese nombre de Count propiedad (en lugar de Length ).

Implementación de 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 visualización

Si la presentación de un objeto no proporciona los resultados esperados, cree un <YourProductName> personalizado. Archivo Format.ps1xml 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 el centro de una canalización (es decir, otros cmdlets producirán su entrada o consumirán su salida). Por ejemplo, puede suponer que el cmdlet, porque genera datos, solo se usa como el Get-Process primer cmdlet de una canalización. Sin embargo, dado que este cmdlet está diseñado para el centro de una canalización, este cmdlet permite que los cmdlets o datos anteriores de la canalización especifiquen los procesos que se deben recuperar.

Entrada de compatibilidad 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 palabra clave , el atributo keyword o ambas palabras ValueFromPipeline clave en su ValueFromPipelineByPropertyName declaración. Si ninguno de los parámetros de un conjunto de parámetros admite las palabras clave o , el cmdlet no se puede colocar significativamente después de otro cmdlet porque omitirá cualquier entrada ValueFromPipeline ValueFromPipelineByPropertyName 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 contenerlos para almacenarlos en búfer en una matriz combinada. Los cmdlets que reciben los objetos como entrada podrán procesar, mostrar o procesar y mostrar los objetos de salida sin retraso. 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 en true .

Crear cmdlets Case-Insensitive y Case-Preserving (SC04)

De forma predeterminada, Windows PowerShell sí mismo no tiene en cuenta las mayúsculas y minúsculas. Sin embargo, dado que se ocupa de muchos sistemas preexistente, Windows PowerShell conserva las mayúsculas y minúsculas para facilitar el funcionamiento y la compatibilidad. En otras palabras, 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 tenga en cuenta las mayúsculas y 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.

Consulte también

Directrices de desarrollo necesarias

Directrices de desarrollo de consulta

Escribir un cmdlet de Windows PowerShell