Directrices y procedimientos recomendados de publicación de PowerShellGallery

En este artículo se describen los pasos recomendados que usan los equipos de Microsoft para asegurarse de que los paquetes publicados en la Galería de PowerShell se adoptarán ampliamente y proporcionarán un gran valor a los usuarios, en función de cómo la Galería de PowerShell controla los datos del manifiesto y los comentarios de un gran número de usuarios de la Galería de PowerShell. Los paquetes que se publican siguiendo estas directrices serán más probables que se instalen, confíen y atraerán a más usuarios.

A continuación se incluyen instrucciones sobre lo que hace que un paquete de la Galería de PowerShell sea bueno, qué configuración de manifiesto opcional es más importante, cómo mejorar el código con los comentarios de los revisores iniciales y el analizador de scripts de PowerShell, cómo versionar el módulo, documentación, pruebas y ejemplos sobre cómo usar lo que ha compartido. Gran parte de esta documentación sigue las directrices para publicar módulos de recursos de DSC de alta calidad.

Para conocer la mecánica de publicación de un paquete en la Galería de PowerShell, consulte Creación y publicación de un paquete.

Se agradecen los comentarios sobre estas directrices. Si tiene comentarios, abra los problemas en nuestro repositorio de documentación de GitHub.

Procedimientos recomendados para publicar paquetes

Los siguientes procedimientos recomendados son los que dicen los usuarios de los elementos de la Galería de PowerShell y se enumeran en orden de prioridad nominal. Los paquetes que siguen estas directrices son mucho más probables que otros usuarios descarguen y adopten.

• Uso de PSScriptAnalyzer
• Incluir documentación y ejemplos
• Responder a los comentarios
• Proporcionar módulos en lugar de scripts
• Proporcionar vínculos a un sitio de proyecto
• Etiquete el paquete con las plataformas y PSEdition compatibles
• Incluir pruebas con los módulos
• Incluir o vincular a los términos de licencia
• Firmar el código
• Siga las directrices de SemVer para el control de versiones
• Uso de etiquetas comunes, como se documenta en Etiquetas comunes de la Galería de PowerShell
• Prueba de publicación mediante un repositorio local
• Uso de PowerShellGet para publicar

Cada uno de estos se trata brevemente en las secciones siguientes.

Uso de PSScriptAnalyzer

PSScriptAnalyzer es una herramienta gratuita de análisis de código estático que funciona en código de PowerShell. PSScriptAnalyzer identificará los problemas más comunes que se observan en el código de PowerShell y, a menudo, una recomendación sobre cómo solucionar el problema. La herramienta es fácil de usar y clasifica los problemas como Errores (grave, debe solucionarse), Advertencia (debe revisarse y solucionarse) e Información (vale la pena consultar los procedimientos recomendados). Todos los paquetes publicados en la Galería de PowerShell se examinarán mediante PSScriptAnalyzer y los errores se notificarán al propietario y deberán solucionarse.

La práctica recomendada es ejecutar Invoke-ScriptAnalyzer con -Recurse y -Severity Warning.

Revise los resultados y asegúrese de que:

• Todos los errores se corrigen o se tratan en la documentación.
• Todas las advertencias se revisan y se tratan cuando corresponda.

Se recomienda encarecidamente a los usuarios que descarguen paquetes de la Galería de PowerShell que ejecuten PSScriptAnalyzer y evalúen todos los errores y advertencias. Es muy probable que los usuarios se pongan en contacto con los propietarios de paquetes si ven que hay un error notificado por PSScriptAnalyzer. Si hay una razón convincente para que el paquete mantenga el código marcado como un error, agregue esa información a la documentación para evitar tener que responder a la misma pregunta muchas veces.

Incluir documentación y ejemplos

La documentación y los ejemplos son la mejor manera de garantizar que los usuarios puedan aprovechar cualquier código compartido.

La documentación es lo más útil para incluir en los paquetes publicados en la Galería de PowerShell. Por lo general, los usuarios omitirán los paquetes sin documentación, ya que la alternativa es leer el código para comprender qué es el paquete y cómo usarlo. Hay varios artículos disponibles sobre cómo proporcionar documentación con paquetes de PowerShell, entre los que se incluyen:

• Las instrucciones para proporcionar ayuda se encuentran en Cómo escribir ayuda de cmdlet.
• Creación de ayuda de cmdlets, que es el mejor enfoque para cualquier script, función o cmdlet de PowerShell. Para obtener información sobre cómo crear ayuda de cmdlet, comience con Cómo escribir ayuda de cmdlet. Para agregar ayuda dentro de un script, consulte Acerca de la ayuda basada en comentarios.
• Muchos módulos también incluyen documentación en formato de texto, como archivos MarkDown. Esto puede ser especialmente útil cuando hay un sitio de proyecto en GitHub, donde Markdown es un formato muy usado. La práctica recomendada es usar Markdown con sabor a GitHub.

Los ejemplos muestran a los usuarios cómo se pretende usar el paquete. Muchos desarrolladores dirán que examinan ejemplos antes de la documentación para comprender cómo usar algo. Los mejores tipos de ejemplos muestran el uso básico, además de un caso de uso realista simulado y el código está bien comentado. Los ejemplos de módulos publicados en la Galería de PowerShell deben estar en una carpeta Examples en la raíz del módulo.

Se puede encontrar un buen patrón de ejemplos en el módulo PSDscResource en la Examples\RegistryResource carpeta. Hay cuatro casos de uso de ejemplo con una breve descripción en la parte superior de cada archivo que documenta lo que se muestra.

Administrar dependencias

Es importante especificar los módulos en los que depende el módulo en el manifiesto del módulo. Esto permite al usuario final no tener que preocuparse de instalar las versiones adecuadas de los módulos en los que el usuario toma una dependencia. Para especificar módulos dependientes, debe usar el campo de módulo necesario en el manifiesto del módulo. Esto cargará los módulos enumerados en el entorno global antes de importar el módulo a menos que ya se hayan cargado. Por ejemplo, es posible que algunos módulos ya se carguen mediante otro módulo. También es posible especificar una versión específica para cargar mediante el campo RequiredVersion en lugar del campo ModuleVersion . Al usar ModuleVersion, cargará la versión más reciente disponible con un mínimo de la versión especificada. Cuando no se usa el campo RequiredVersion , para especificar una versión específica es importante supervisar las actualizaciones de versión del módulo requerido. Es especialmente importante tener en cuenta los cambios importantes que podrían afectar a la experiencia del usuario con el módulo.

Example: RequiredModules = @(@{ModuleName="myDependentModule"; ModuleVersion="2.0"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Example: RequiredModules = @(@{ModuleName="myDependentModule"; RequiredVersion="1.5"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Responder a los comentarios

Los propietarios de paquetes que responden correctamente a los comentarios son muy valorados por la comunidad. Los usuarios que proporcionan comentarios constructivos son importantes para responder, ya que están interesados lo suficiente en el paquete para intentar ayudar a mejorarlo.

Hay un método de comentarios disponible en la Galería de PowerShell:

• Propietario del contacto: esto permite que un usuario envíe un correo electrónico al propietario del paquete. Como propietario del paquete, es importante supervisar la dirección de correo electrónico que se usa con los paquetes de la Galería de PowerShell y responder a los problemas que se producen. La única desventaja de este método es que solo el usuario y el propietario verán la comunicación, por lo que el propietario puede tener que responder a la misma pregunta muchas veces.

Los propietarios que responden a los comentarios de forma constructiva son agradecidos por la comunidad. Use la oportunidad en el informe para solicitar más información. Si es necesario, proporcione una solución alternativa o identifique si una actualización corrige un problema.

Si hay un comportamiento inadecuado observado desde cualquiera de estos canales de comunicación, use la característica Notificar abuso de la Galería de PowerShell para ponerse en contacto con los administradores de la galería.

Módulos frente a scripts

Compartir un script con otros usuarios es excelente y proporciona a otros usuarios ejemplos de cómo resolver problemas que pueden tener. El problema es que los scripts de la Galería de PowerShell son archivos únicos sin documentación, ejemplos y pruebas independientes.

Los módulos de PowerShell tienen una estructura de carpetas que permite incluir varias carpetas y archivos con el paquete. La estructura del módulo permite incluir los otros paquetes que se enumeran como procedimientos recomendados: ayuda de cmdlets, documentación, ejemplos y pruebas. La mayor desventaja es que un script dentro de un módulo debe exponerse y usarse como función. Para obtener información sobre cómo crear un módulo, vea Escribir un módulo de Windows PowerShell.

Hay situaciones en las que un script proporciona una mejor experiencia para el usuario, especialmente con configuraciones de DSC. El procedimiento recomendado para las configuraciones de DSC es publicar la configuración como un script con un módulo complementario que contenga los documentos, ejemplos y pruebas. El script enumera el módulo adjunto usando RequiredModules = @(Name of the Module). Este enfoque se puede usar con cualquier script.

Los scripts independientes que siguen los otros procedimientos recomendados proporcionan valor real a otros usuarios. Se recomienda encarecidamente proporcionar documentación basada en comentarios y un vínculo a un sitio de proyecto al publicar un script en la Galería de PowerShell.

Proporcionar un vínculo a un sitio de proyecto

Un sitio de proyecto es donde un publicador puede interactuar directamente con los usuarios de sus paquetes de la Galería de PowerShell. Los usuarios prefieren los paquetes que proporcionan esto, ya que les permite obtener información sobre el paquete más fácilmente. Muchas de las organizaciones con presencia web dedicada proporcionan muchos paquetes en la Galería de PowerShell en GitHub. Cada uno de estos se puede considerar un sitio de proyecto.

Para agregar un vínculo, incluya ProjectURI en la sección PSData del manifiesto de la siguiente manera:

  # A URL to the main website for this project.
  ProjectUri = 'https://github.com/powershell/powershell'

Cuando se proporciona un ProjectURI, la Galería de PowerShell incluirá un vínculo al sitio del proyecto en el lado izquierdo de la página del paquete.

Etiquete el paquete con las plataformas y PSEdition compatibles

Use las siguientes etiquetas para demostrar a los usuarios qué paquetes funcionarán bien con su entorno:

• PSEdition_Desktop: paquetes compatibles con Windows PowerShell
• PSEdition_Core: paquetes compatibles con PowerShell 6 y versiones posteriores
• Windows: paquetes compatibles con el sistema operativo Windows
• Linux: paquetes compatibles con sistemas operativos Linux
• MacOS: paquetes compatibles con el sistema operativo Mac

Al etiquetar el paquete con las plataformas compatibles, se incluirá en los filtros de búsqueda galería en el panel izquierdo de los resultados de búsqueda. Si hospeda el paquete en GitHub, al etiquetar el paquete, también puede aprovechar nuestro de escudos de compatibilidad de la Galería de PowerShell.

Incluir pruebas

La inclusión de pruebas con código fuente abierto es importante para los usuarios, ya que proporciona garantías sobre lo que valida y proporciona información sobre cómo funciona el código. También permite a los usuarios asegurarse de que no interrumpen la funcionalidad original si modifican el código para ajustarse a su entorno.

Se recomienda encarecidamente que las pruebas se escriban para aprovechar el marco de pruebas de Pester, que se ha diseñado específicamente para PowerShell. Pester está disponible en GitHub, la Galería de PowerShell y se incluye en Windows 10, Windows Server 2016, WMF 5.0 y WMF 5.1.

El sitio del proyecto Pester en GitHub incluye buena documentación sobre la escritura de pruebas de Pester, desde la introducción hasta las mejores prácticas.

Los destinos para la cobertura de prueba se indican en la documentación del módulo de recursos de alta calidad, con una cobertura de código de prueba unitaria de 70% recomendada.

Incluir o vincular a los términos de licencia

Todos los paquetes publicados en la Galería de PowerShell deben especificar los términos de licencia o estar sujetos a la licencia incluida en los Términos de uso en el Anexo A. El mejor enfoque para especificar una licencia diferente es proporcionar un vínculo a la licencia mediante el LicenseURI en PSData. Para obtener más información, consulte Manifiesto de paquetes e interfaz de usuario de la galería.

PrivateData = @{
    PSData = @{

        # Tags applied to this module. These help with module discovery in online galleries.
        Tags = @('.net','acl','active-directory')

        # A URL to the license for this module.
        LicenseUri = 'http://www.apache.org/licenses/LICENSE-2.0'

Firmar el código

La firma de código proporciona a los usuarios el mayor nivel de garantía para quién publicó el paquete y que la copia del código que adquiere es exactamente lo que publicó el publicador. Para obtener más información sobre la firma de código en general, consulte Introducción a la firma de código. PowerShell admite la validación de la firma de código a través de dos enfoques principales:

• Firma de archivos de script
• Firma de catálogo de un módulo

La firma de archivos de PowerShell es un enfoque bien establecido para garantizar que el código que se ejecuta se ha generado mediante un origen confiable y no se ha modificado. Los detalles sobre cómo firmar archivos de script de PowerShell se tratan en el artículo Acerca de la firma . En información general, se puede agregar una firma a cualquier .PS1 archivo que PowerShell valide cuando se carga el script. PowerShell se puede restringir mediante los cmdlets de directiva de ejecución para garantizar el uso de scripts firmados.

Los módulos de firma de catálogos son una característica agregada a PowerShell en la versión 5.1. Cómo firmar un módulo se trata en el artículo Cmdlets de catálogo . En información general, la firma del catálogo se realiza mediante la creación de un archivo de catálogo, que contiene un valor hash para cada archivo del módulo y, a continuación, firma ese archivo.

PowerShellGetPublish-ModuleInstall-Module y Update-Module los cmdlets comprobarán la firma para asegurarse de que es válida y, a continuación, confirmarán que el valor hash de cada paquete coincide con lo que hay en el catálogo. Save-Module no valida una firma. Si se instala una versión anterior del módulo en el sistema, Install-Module confirmará que la autoridad de firma para la nueva versión coincide con la instalada anteriormente. Install-Module y Update-Module usará la firma en un .PSD1 archivo si el paquete no está firmado por el catálogo. La firma de catálogo funciona con, pero no reemplaza los archivos de script de firma. PowerShell no valida las firmas de catálogo en tiempo de carga del módulo.

Siga las instrucciones de SemVer para el control de versiones.

SemVer es una convención pública que describe cómo estructurar y cambiar una versión para permitir una fácil interpretación de los cambios. La versión del paquete debe incluirse en los datos del manifiesto.

• La versión debe estructurarse como tres bloques numéricos separados por puntos, como en 0.1.1 o 4.11.192.
• Las versiones que comienzan con 0 indican que el paquete aún no está listo para la producción, y el primer número solo debe comenzar con 0 si ese es el único número utilizado.
• Los cambios en el primer número (1.9.9999 a 2.0.0) indican cambios importantes y de importancia entre las versiones.
• Los cambios en el segundo número (1.1 to 1.2) indican cambios en el nivel de característica, como agregar nuevos cmdlets a un módulo.
• Los cambios realizados en el tercer número indican cambios no importantes, como nuevos parámetros, ejemplos actualizados o nuevas pruebas.
• Al enumerar las versiones, PowerShell ordenará las versiones como cadenas, por lo que 1.01.0 se tratarán como mayores que 1.001.0.

PowerShell se creó antes de que SemVer se publicara, por lo que proporciona compatibilidad con la mayoría de los elementos de SemVer, en concreto:

• No admite cadenas de versión preliminar en números de versión. Esto es útil cuando un editor desea entregar una versión preliminar de una nueva versión principal después de proporcionar una versión 1.0.0. Esto se admitirá en una versión futura de los cmdlets Galería de PowerShell y PowerShellGet .
• PowerShell y la Galería de PowerShell permiten cadenas de versión con 1, 2 y 4 segmentos. Muchos de los primeros módulos no seguían las pautas, y las versiones de productos de Microsoft incluyen información de compilación como un 4º bloque de números (por ejemplo 5.1.14393.1066). Desde el punto de vista del control de versiones, estas diferencias se omiten.

Prueba mediante un repositorio local

La Galería de PowerShell no está diseñada para ser un destino para probar el proceso de publicación. La mejor manera de probar el proceso completo de publicación en la Galería de PowerShell es configurar y usar su propio repositorio local. Esto se puede hacer de varias maneras, entre las que se incluyen:

• Configure una instancia local de la Galería de PowerShell mediante el proyecto de la Galería privada de PS en GitHub. Este proyecto de versión preliminar le ayudará a configurar una instancia de la Galería de PowerShell que puede controlar y usar para las pruebas.
• Configure un repositorio interno de Nuget. Esto requerirá más trabajo para configurar, pero tendrá la ventaja de validar algunos de los requisitos, especialmente validar el uso de una clave de API y si las dependencias están presentes en el destino al publicar.
• Configure un recurso compartido de archivos como repositorio de prueba. Esto es fácil de configurar, pero como es un recurso compartido de archivos, las validaciones indicadas anteriormente no tendrán lugar. Una posible ventaja en este caso es que el recurso compartido de archivos no comprueba la clave de API necesaria, por lo que puede usar la misma clave que usaría para publicar en la Galería de PowerShell.

Con cualquiera de estas soluciones, utilícelo Register-PSRepository para definir un nuevo repositorio, que se utiliza en el parámetro para Publish-Module.-Repository

Un punto adicional sobre la publicación de pruebas: cualquier paquete que publique en la Galería de PowerShell no se puede eliminar sin ayuda del equipo de operaciones, que confirmará que nada depende del paquete que desea publicar. Por ese motivo, no se admite la Galería de PowerShell como destino de prueba y se pondrá en contacto con cualquier publicador que lo haga.

Uso de PowerShellGet para publicar

Se recomienda encarecidamente que los editores usen los Publish-Module cmdlets and Publish-Script al trabajar con la Galería de PowerShell. PowerShellGet se creó para ayudarle a evitar recordar detalles importantes sobre la instalación y la publicación en la Galería de PowerShell. En ocasiones, los editores han optado por omitir PowerShellGet y usar el cliente NuGet , o los cmdlets PackageManagement , en lugar de Publish-Module. Hay una serie de detalles que se pierden fácilmente, lo que da lugar a una variedad de solicitudes de soporte técnico.

Si hay una razón por la que no puede usar Publish-Module o Publish-Script, háganoslo saber. Presente un problema en el repositorio de GitHub de PowerShellGet y proporcione los detalles que le hacen elegir NuGet o PackageManagement.

Flujo de trabajo recomendado

El enfoque más exitoso que hemos encontrado para los paquetes publicados en la Galería de PowerShell es este:

• Realice el desarrollo inicial en un sitio de proyecto de código abierto. El equipo de PowerShell usa GitHub.
• Use los comentarios de los revisores y el Analizador de scripts de PowerShell para que el código llegue a un estado estable.
• Incluya documentación para que otros usuarios sepan cómo usar su trabajo.
• Pruebe la acción de publicación mediante un repositorio local.
• Publique una versión estable o Alfa en la Galería de PowerShell, asegurándose de incluir la documentación y el vínculo al sitio del proyecto.
• Recopile comentarios e iteración en el código del sitio del proyecto y, a continuación, publique actualizaciones estables en la Galería de PowerShell.
• Agregue ejemplos y pruebas pester en el proyecto y el módulo.
• Decida si desea codificar la firma del paquete.
• Cuando crea que el proyecto está listo para usarse en un entorno de producción, publique una 1.0.0 versión en la Galería de PowerShell.
• Continúe recopilando comentarios e iteración en el código en función de la entrada del usuario.