Directrices y procedimientos recomendados de publicación de PowerShellGallery

  • Artículo

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 para lo que hace que un buen paquete de la Galería de PowerShell, qué configuración de manifiesto opcional es más importante, lo que mejora el código con comentarios de los revisores iniciales y Analizador de scripts de PowerShell, control de versiones del módulo, documentación, pruebas y ejemplos para 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 obtener la mecánica de publicar 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 problemas en nuestro repositorio de documentación de GitHub de .

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 instrucciones de 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 de análisis de código estático gratuita que funciona en código de PowerShell. PSScriptAnalyzer identificará los problemas más comunes que se ven en el código de PowerShell y, a menudo, una recomendación para 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 analizarán mediante PSScriptAnalyzer, y los errores se notificarán al propietario y se deben solucionar.

El procedimiento recomendado es ejecutar Invoke-ScriptAnalyzer con -Recurse y advertencia de -Severity.

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 que los usuarios que descarguen paquetes de la Galería de PowerShell ejecuten PSScriptAnalyzer y evalúen todos los errores y advertencias. Es muy probable que los usuarios se comuniquen con los propietarios del paquete 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 Ayuda de cómo escribir cmdlets.
  • 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 cmdlets, comience con Ayuda para escribir cmdlets. 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. El procedimiento recomendado 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.

Puede encontrar un buen patrón para ejemplos en el módulo PSDscResource de en la carpeta Examples\RegistryResource. 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 con 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 use el campo RequiredVersion, para especificar una versión específica, es importante supervisar las actualizaciones de versiones en el módulo necesario. 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, consulte Escritura de 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 complementario mediante 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.

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 nuestras escudos de compatibilidad de la Galería de PowerShellejemplo de escudo de compatibilidad.

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 de y se incluye en Windows 10, Windows Server 2016, WMF 5.0 y WMF 5.1.

El sitio del proyecto Pester en GitHub incluye una buena documentación sobre la escritura de pruebas de Pester, desde la introducción a los procedimientos recomendados.

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

Todos los paquetes publicados en la Galería de PowerShell deben especificar los términos de licencia o estar enlazados por la licencia incluida en el de términos de uso de en exposición A. El mejor enfoque para especificar una licencia diferente es proporcionar un vínculo a la licencia mediante el LicenseURI de en PSData. Para obtener más información, consulte manifiesto paquetes yde la 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 archivo de .PS1 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 de . 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.

Los cmdlets PowerShellGetPublish-Module, Install-Moduley Update-Module comprobarán la firma para asegurarse de que es válido y, a continuación, confirmarán que el valor hash de cada paquete coincide con lo que está 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 entidad de firma de la nueva versión coincide con lo que se instaló anteriormente. Install-Module y Update-Module usarán la firma en un archivo .PSD1 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 interpretación sencilla 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 a partir de 0 indican que el paquete aún no está listo para producción y que el primer número solo debe comenzar con 0 si es el único número usado.
  • Los cambios en el primer número (1.9.9999 a 2.0.0) indican cambios importantes e importantes entre las versiones.
  • Los cambios realizados en el segundo número (1.1 a 1.2) indican cambios de 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 versiones, PowerShell ordenará las versiones como cadenas, por lo que 1.01.0 se tratará como mayor 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 resulta útil cuando un publicador 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 la Galería de PowerShell y cmdlets PowerShellGet.
  • PowerShell y la Galería de PowerShell permiten cadenas de versión con 1, 2 y 4 segmentos. Muchos módulos iniciales no seguían las directrices y las versiones del producto de Microsoft incluyen información de compilación como un bloque 4º 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 galería privada de PS de 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 de Nuget interno de . 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 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, use Register-PSRepository para definir un nuevo repositorio de , que se usa en el parámetro -Repository para Publish-Module.

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 publicadores usen los cmdlets Publish-Module y 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 publicación en la Galería de PowerShell. En ocasiones, los publicadores han elegido omitir powerShellGet y usar el cliente de NuGet o cmdlets packageManagement, en lugar de . 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. Abra un problema en el repositorio de GitHub de PowerShellGet y proporcione los detalles que hacen que elija NuGet o PackageManagement.

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 comentarios de revisores y analizador de scripts de PowerShell para obtener el código en 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 sienta que el proyecto está listo para usarse en un entorno de producción, publique una versión de 1.0.0 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.