Adam el Automatizador

Trabajar con módulos de PowerShell es una pieza importante de la automatización de PowerShell. Cuando se empieza a aprender PowerShell, los primeros pasos suelen ser utilizando comandos individuales. Esto conduce a la construcción de secuencias de comandos que luego conduce a la construcción de funciones.

Al utilizar funciones, usted puede hacer sus scripts más modular. Esto le permite ser capaz de utilizar el mismo código en muchos lugares sin tener que copiar y pegar el código en todo el lugar. El uso de funciones le permite pasar menos tiempo haciendo la misma edición al mismo código en todos los lugares donde se utiliza. En su lugar, puede trabajar en hacer su código mejor en un solo lugar.

Para llevar las funciones al siguiente nivel, puede combinar estas funciones juntas en un módulo.

Un módulo es una colección de funciones en un archivo de texto con una extensión psm1. Hay algunas adiciones opcionales, como un manifiesto del módulo y una ayuda basada en comentarios o externa que también puede ser incluida. Estos serán cubiertos más adelante.

Requisitos previos

En este artículo utilizaré Windows PowerShell 5.1. Si usted está usando una versión anterior o PowerShell Core, su kilometraje puede variar en cuanto a los resultados que usted ve.

Interactuar con los módulos

Una vez que abra por primera vez una sesión de PowerShell, usted comenzará con dos módulos. El primero es Microsoft.PowerShell.Utility que contiene muchas funciones básicas de PowerShell que ya utilizas. El otro módulo es PSReadline. Puedes ver estos módulos de inicio utilizando el comando Get-Module.

Dicho esto, esta no es una lista completa de todos los módulos disponibles. Desde PowerShell 3, los módulos que se instalen se importarán según sea necesario. Si usted está ejecutando una versión anterior de PowerShell se le pedirá que utilice el comando Import-Module para importar primero el módulo antes de utilizar cualquiera de los comandos.

Hay veces en que usted todavía querría usar Import-Module incluso en versiones posteriores. Si desea importar un módulo después de que ya está instalado, puede utilizar Import-Module así:

Mientras que Get-Module mostrará todos los módulos que se importan, no verá los módulos que aún no se han importado. Puede entonces utilizar el parámetro ListAvailable para mostrar todos los demás módulos que están disponibles.

No se muestran todos los comandos por defecto

La propiedad ExportedCommandscontiene una lista de todos los comandos disponibles que se exportan desde el módulo. Puede ver algunas diferencias entre esta lista y lo que está en el archivo del módulo. Los comandos exportados es una característica incorporada en el manifiesto del módulo que permite al escritor dejar una función como oculta. Los autores de módulos también pueden utilizar el cmdlet Export-ModuleMember pero eso está fuera del alcance de este artículo.

Los autores de módulos pueden querer tener una función oculta porque está destinada a soportar otras funciones, no a ser vista por el usuario. Para tener una función oculta el autor la excluiría de la matriz FunctionsToExport en el manifiesto. Aquí puede ver una vista ampliada de la propiedad ExportedCommands.

Importación de módulos

Hay muchas maneras de empezar a utilizar los módulos. Puede importar manualmente el módulo utilizando la ruta de acceso a los archivos del módulo. Esto le permite ser capaz de probar y actualizar el módulo sin tener que hacer mucho trabajo. Pero esto no permite mucha portabilidad, ya que tendrías que usar la ruta exacta al módulo. PowerShell tampoco importará automáticamente los módulos que no estén en la variable $env:PSModulePath.

Importación selectiva de comandos

Puede utilizar Import-Module para importar sólo funciones específicas en lugar de todo el módulo mediante el parámetro Function. Esto puede ahorrar tiempo al importar módulos de sistemas remotos, como los módulos de Office 365.

Todos los módulos de usuario

Los módulos instalados para todos los usuarios se colocan en C:\NArchivos de programa\NWindowsPowerShell\Nmódulos. Este directorio contiene muchos módulos pre-agregados incluyendo cualquier módulo instalado usando Install-Module usando el ámbito por defecto AllUsers.

Módulos de Usuario Actuales

Si usted está instalando un módulo pero sólo quiere que un solo usuario lo use, hay un ámbito CurrentUser. Esto pone los archivos del módulo en su carpeta de Documentos en C:\NUsuarios<nombre de usuario>\NDocumentos\NWindowsPowerShell\NMódulos. Esto puede ser útil en un entorno en el que se utiliza la redirección de carpetas con la carpeta Documentos.

En este caso, se puede instalar un módulo en un equipo y utilizarlo en otro, ya que ambos estarían compartiendo la misma carpeta de documentos.

Módulos del sistema

Para completar, también hay un directorio de módulos en C:\NWindows\NSystem32\NWindowsPowerShell\1.0\NMódulos. Aunque técnicamente, un módulo colocado en esta ruta se importaría como una de las otras rutas, pero no se recomienda ya que esto está reservado para los módulos del sistema de Microsoft.

La denominación es importante

Puede colocar manualmente su módulo en una de estas rutas para que esté disponible por defecto con una nueva sesión, pero tiene que asegurarse de seguir la denominación requerida para los módulos. La carpeta en la que se colocan los archivos del módulo, debe tener el mismo nombre que el archivo del módulo psm1 y el manifiesto del módulo psd1 si hay uno.

Usando Get-Module -ListAvailable que habíamos mencionado anteriormente hace referencia a estas rutas. Puede ver todas las rutas de los módulos utilizando $env:PSModulePath -Split ';'. Usted puede notar otras rutas en la lista de lo que se muestra aquí. Muchos programas añaden sus propias rutas de módulos cuando se instalan. Uno de los ejemplos de esto es SQL, que tiene sus propios módulos incluidos en sus propias rutas de módulos.

También hay algunos módulos que usted instalaría con un proceso diferente. Uno de los ejemplos más significativos es el módulo ActiveDirectory. Desde Windows 7 hasta Windows 10 1803, lo instalarías con el instalador de las Herramientas de Administración Remota del Servidor (RSAT).

En las versiones más nuevas de Windows 10 (1809+) esto sólo está disponible a través de las Características Bajo Demanda. Al instalar RSAT se instalan los módulos de ActiveDirectory y muchos otros que se utilizarían para administrar otros roles de Windows. En los sistemas operativos de servidor de Windows, estos módulos se instalan a través del Administrador del servidor.

Importación de módulos remotos (Remoting implícito)

Hay algunos casos en los que no es práctico tener un módulo ejecutándose localmente. En su lugar, es mejor conectarse a un dispositivo remoto e importar un módulo instalado en él. Al hacer esto, los comandos se ejecutan realmente en la máquina remota. Esto se utiliza con frecuencia con los módulos de Office 365 de Microsoft. Muchos de ellos se conectan a un servidor de Office 365 que luego importa un módulo. Cuando se ejecuta cualquiera de los comandos, se ejecutan en el servidor remoto y luego la salida se envía de nuevo a su sesión.

Otro uso de la importación de módulos remotos es cuando usted no tiene el módulo instalado localmente. Esto es lo que obtendría si no tuviera instalado el módulo ActiveDirectory, pero intentara importarlo.

Para importar un módulo remoto, primero tiene que crear una PSSession. Puedes usar New-PSSession para crear la sesión. A continuación, importaría el módulo disponible en el dispositivo remoto utilizando el parámetro PSSession con Import-Module.

PS51> $AdminServer = New-PSSession -ComputerName $AdminServerName -Credential (Get-Credential)PS51> Import-Module -Name ActiveDirectory -PSSession $AdminServer -Prefix 'Rmt'

Usar este método de importación de módulos remotos permite una ejecución más rápida del código en un entorno distribuido. Por ejemplo, si está trabajando desde su ordenador, pero los servidores en los que está trabajando están al otro lado de los Estados Unidos, puede tardar mucho más en ejecutar ciertos comandos localmente contra los servidores. Mientras que la ejecución de los comandos en un servidor y la alimentación de la salida de nuevo a su sesión local es mucho más rápido.

Agregar un prefijo de módulo

También puede agregar un prefijo en las funciones importadas de la máquina remota. Esta opción está disponible al importar módulos locales, pero rara vez se utiliza fuera de la prueba de diferentes versiones de un módulo de lado a lado.

Si ejecutó el comando de importación anterior y esto es lo que vería al mirar los comandos:

En este caso, puede utilizar un prefijo para mostrar que no es un módulo local. Esto se puede utilizar en los casos en que usted está importando un módulo que también está disponible localmente. Añadiendo el prefijo se reduce la confusión sobre dónde se está ejecutando el código.

Eliminar módulos

También puede eliminar un módulo de la sesión actual sin utilizar Remove-Module. Esto elimina un módulo de la sesión local sin eliminar los archivos del módulo. Usted puede querer usar esto en un caso donde usted estaba usando una sesión remota para usar un módulo. Usted podría utilizar Remove-Module para limpiar su sesión y luego desconectar la sesión remota.

Otro uso de Remove-Module es si usted está haciendo cambios en un módulo y no desea iniciar una nueva sesión de PowerShell. En este caso, utilizarías Remove-Module seguido de Import-Module para recargarlo en tu sesión. Alternativamente, puede utilizar el parámetro Force con Import-Module. Esto completará la descarga y recarga del módulo para usted.

Lo que compone un módulo de PowerShell

Un módulo puede consistir en uno o más archivos. Para cumplir con los requisitos mínimos de un módulo, debe tener un archivo de módulo. Este puede ser un archivo PSM1 o cualquier otro archivo de módulo, como un archivo de módulo binario. Para construir sobre eso, su psm1 debe tener funciones definidas en él, o no será de mucha utilidad para nadie.

Aunque no hay requisitos sobre cómo deben ser las funciones o lo que deben hacer, hay algunas directrices. Normalmente se prefiere que todas las funciones de un módulo estén construidas en torno al mismo concepto.

Los módulos contienen funciones afines

Por ejemplo, el módulo ActiveDirectory sólo incluye funciones que interactúan con Active Directory de alguna manera. Normalmente los nombres de las funciones también contienen un prefijo. Volviendo al módulo ActiveDirectory como ejemplo, todos los nombres de las funciones empiezan por AD.

Usar estas directrices ayuda a descubrir las funciones. Imagínese que acaba de importar este nuevo módulo y que quiere consultar las funciones. Esto es mucho más fácil de hacer si todas las funciones tienen una estructura de nombres similar. Aunque a menudo vea que los módulos comienzan con PS, este prefijo está reservado oficialmente sólo para los módulos de Microsoft. Probablemente no causará un problema si utiliza PS al comienzo de su módulo, puede crear un conflicto con el nombre de otro módulo.

Usando estas directrices, si tuviera un montón de funciones que todas tuvieran que ver con la interacción con el registro podría tener algo como:

function Get-ATARegistryKey {...}function Set-ATARegistryKey {...}

Manifiestos de Módulo

Para construir en el archivo de módulo de texto, también puede incluir un manifiesto de módulo. Estos archivos tienen una extensión PSD1 y contienen metadatos sobre el módulo. Aquí es donde usted incluiría información sobre el autor, la descripción del módulo, otros módulos requeridos, y muchos otros atributos. Para publicar en un repositorio, se requiere tener los campos Author y Description poblados.

Aquí hay un ejemplo de un manifiesto que podemos tener para nuestro módulo de registro:

#Module manifest for module 'ATARegistry'#Generated by: Tyler#Generated on: 8/11/2019@{#Script module or binary module file associated with this manifest.RootModule = 'ATARegistry'#Version number of this module.ModuleVersion = '1.0'#Supported PSEditions#CompatiblePSEditions = @()#ID used to uniquely identify this moduleGUID = 'fef619fa-016d-4b11-a09d-b222e094de3e'#Author of this moduleAuthor = 'Tyler Muir'#Company or vendor of this moduleCompanyName = 'Adam the Automator'#Copyright statement for this moduleCopyright = '(c) 2019 tyler. All rights reserved.'#Description of the functionality provided by this moduleDescription = 'This is a test module.'#Minimum version of the Windows PowerShell engine required by this module#PowerShellVersion = ''#Name of the Windows PowerShell host required by this module#PowerShellHostName = ''#Minimum version of the Windows PowerShell host required by this module#PowerShellHostVersion = ''#Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.#DotNetFrameworkVersion = ''#Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.#CLRVersion = ''#Processor architecture (None, X86, Amd64) required by this module#ProcessorArchitecture = ''#Modules that must be imported into the global environment prior to importing this module#RequiredModules = @()#Assemblies that must be loaded prior to importing this module#RequiredAssemblies = @()#Script files (.ps1) that are run in the caller's environment prior to importing this module.#ScriptsToProcess = @()#Type files (.ps1xml) to be loaded when importing this module#TypesToProcess = @()#Format files (.ps1xml) to be loaded when importing this module#FormatsToProcess = @()#Modules to import as nested modules of the module specified in RootModule/ModuleToProcess#NestedModules = @()#Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.FunctionsToExport = @('Get-RegistryKey','Set-RegistryKey')#Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.CmdletsToExport = @()#Variables to export from this moduleVariablesToExport = '*'#Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.AliasesToExport = @()#DSC resources to export from this module#DscResourcesToExport = @()#List of all modules packaged with this module#ModuleList = @()#List of all files packaged with this module#FileList = @()#Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.PrivateData = @{PSData = @{#Tags applied to this module. These help with module discovery in online galleries.#Tags = @()#A URL to the license for this module.#LicenseUri = ''#A URL to the main website for this project.#ProjectUri = ''#A URL to an icon representing this module.#IconUri = ''#ReleaseNotes of this module#ReleaseNotes = ''} #End of PSData hashtable} #End of PrivateData hashtable#HelpInfo URI of this module#HelpInfoURI = ''#Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.#DefaultCommandPrefix = ''}

Aunque esto puede parecer intimidante al principio, Microsoft tiene un práctico cmdlet que puedes usar para generar un manifiesto de módulo. El comando incluido es New-ModuleManifest. Para generar el manifiesto que se muestra arriba podría utilizar:

PS51> New-ModuleManifest -Path .\Scripts\TestModule.psd1 -Author 'Tyler Muir' -CompanyName 'Adam the Automator' -RootModule 'TestModule.psm1' -FunctionsToExport @('Get-RegistryKey','Set-RegistryKey') -Description 'This is a test module.'

Archivos de ayuda externos

También puede ver archivos de ayuda externos en algunos módulos. Podrían ser identificados por el <NombreMódulo>-Help.xml al final del nombre del archivo. Estos archivos de ayuda externa contienen la misma información que normalmente estaría contenida en la ayuda basada en comandos que puede encontrar en la definición de una función.

Esto también requeriría que usted agregue # .ExternalHelp <ModulePath>-Help.xml a su función para que funcione correctamente al usar el comando Get-Help después de importar el módulo. Por lo general, sólo es común ver archivos de ayuda externa con módulos muy grandes y debido a que están fuera del alcance.

Aunque estos son los tipos más comunes de archivos que verá en un módulo, estos no son los únicos archivos. A veces verá archivos binarios además de un módulo de texto, ya que hay otras dependencias. Al explorar a través de las rutas de los módulos, usted puede encontrar muchos ejemplos de tipos de archivos adicionales en los módulos.

Para tener archivos de módulos no estándar publicar correctamente usted incluiría otros archivos en el parámetro FileList en su manifiesto del módulo.

Dentro del manifiesto del módulo, usted notará muchos otros parámetros que actualmente están vacíos. Puede utilizarlos para definir otros requisitos para el uso de su módulo. Por ejemplo, puede definir las versiones de PowerShell con las que el módulo puede funcionar. Si intenta importar el módulo en una versión no soportada de PowerShell, esto es lo que vería:

PSRepositorios

Una de las opciones de distribución clave para los módulos es un PSRepositorio. En una vista de 1000′, un PSRepository es un local donde múltiples personas o múltiples dispositivos pueden acceder a los archivos del módulo. Estos son frecuentemente servidores web donde se pueden publicar los archivos.

También puede utilizar un directorio para el repositorio, pero esto le limita en la funcionalidad de su repositorio. Puede alojar un PSRepository usted mismo, o puede utilizar una de las muchas opciones disponibles en Internet como la Galería PowerShell. Usted puede ver su PSRepositories utilizando el comando Get-PSRepository.

Por defecto, sólo tendrá una entrada y será para la Galería de PowerShell. Puedes notar que dirá que no es de confianza. Esto se debe a que PowerShell le hace saber que al usar la Galería PowerShell puede estar usando código no escrito y aprobado por Microsoft. Esto significa que antes de instalar cualquier módulo desde ella, tendrás que dar permiso explícito.

Añadir PSRepositorios

También puedes añadir tus propios repositorios. Para confiar en la Galería PowerShell, puedes ejecutar Get-PSRepository -Name PSGallery | Set-PSRepository -InstallationPolicy Trusted o puedes aceptar la advertencia la primera vez que instales un módulo desde la Galería PowerShell.

Todos los comandos que utilizarías para interactuar con estos PSRepositorios se encuentran en el módulo PowerShellGet. Puedes ver las funciones aquí:

Puede ser necesario actualizar el módulo PowerShellGet antes de interactuar con ciertos repositorios.

Búsqueda de módulos

Otra característica clave del uso de un PSRepository es poder buscar módulos. Esto se logra utilizando el comando Find-Module. Hay múltiples formas de filtrar para encontrar específicamente lo que estás buscando, pero por ahora puedes buscar los módulos de VMware así:

Esto mostrará todos los módulos que comienzan con VMware. Aunque la mayoría de ellos son de VMware, es necesario mirar el atributo de autor para ver quién publicó el módulo.

Dado que cualquiera puede subir a la Galería PowerShell, hay miles de módulos disponibles. Esto significa que puede encontrar módulos que no funcionan correctamente para su caso de uso. Muchos módulos que encontrarás son de código abierto por lo que puedes contribuir a ellos para mejorar la funcionalidad del módulo.

Instalación de módulos

Para utilizar el comando Install-Module, tienes que tener un PSRepository de confianza que esté alojando el módulo. Esto puede ser la Galería PowerShell, otro PSRepository de Internet, o un sitio auto-alojado. Puede tuberías del comando Find-Module para estar disponible para confirmar fácilmente el módulo antes de instalarlo.

También puede definir la versión de un módulo mediante el uso de los parámetros MinimumVersion, MaximumVersion, o RequiredVersion.

Para ver todos los módulos instalados utilizando Install-Module puede utilizar Get-InstalledModule. Esto listará todos los módulos instalados en el ámbito AllUsers o en su ámbito CurrentUser.

Desinstalación de módulos

Así como puede instalar un módulo, también puede desinstalar un módulo. Si el módulo no se instaló mediante el comando Install-Module, no se puede desinstalar con el comando Uninstall-Module.

Como puede ver aquí estamos intentando desinstalar el módulo ActiveDirectory. Como este módulo no se instala con Install-Module, recibirá un error al intentar utilizar Uninstall-Module. Para que pueda desinstalar este módulo, tendríamos que desinstalarlo invirtiendo lo que utilizó para instalar el módulo.

Para ver una desinstalación exitosa de un módulo, puede desinstalar el módulo VMware.PowerCLI que instaló anteriormente.

Aunque haya desinstalado VMware.PowerCLI, puede ver que todavía hay muchas dependencias instaladas. Si quisieras desinstalar todos los módulos podríamos usar Get-InstalledModule VMware.* | Uninstall-Module -Force.

La razón por la que tendrías tantas dificultades para desinstalar completamente este módulo es porque tiene muchas dependencias. Además, algunos de estos módulos son dependencias de los demás, por lo que el parámetro Force sería necesario.

Actualización de módulos

Ahora que sabe cómo instalar y desinstalar un módulo, usted puede preguntarse cómo actualizar un módulo que ha instalado.

Al igual que otros procesos, si el módulo no se instaló utilizando Install-Module, no se puede actualizar el uso de los comandos de PowerShell. Puede utilizar Update-Module para actualizar un módulo a la versión más reciente, o a una versión específica más reciente.

También hay un interruptor de AllowPreRelease que le permitiría actualizar a una versión que no ha sido lanzado oficialmente. A veces esto puede ayudar, ya que puede haber una solución a un error que está experimentando o una nueva característica que se añadió que le gustaría utilizar.

Inspección/Guardar un módulo

Uno de los comandos mucho menos utilizados que es muy útil al examinar los módulos antes de su uso es Save-Module. Usando este comando, puede descargar un módulo a una ruta sin instalarlo.

A continuación, puede inspeccionar los archivos y si el módulo no es un módulo binario puede abrir y mirar el código que compone el módulo. Esto puede ser bueno no sólo para asegurarse de que un módulo no está haciendo nada malicioso, sino también para aprender cómo otros están estructurando sus módulos.

En este ejemplo, no sólo se descarga el módulo VMware.PowerCLI, sino también todas las dependencias. Esto es lo que se muestra en la carpeta VMware.PowerCLI:

Este es un buen ejemplo de cómo a veces hay archivos de módulo no estándar incluidos en el módulo, como el acuerdo de licencia del usuario final.

Escribiendo su propio módulo

Ahora ha visto cómo interactuar con el módulo de otra persona. Ahora quieres aprender a crear el tuyo propio para que puedas empezar a optimizar tu código para la escalabilidad.

Crear archivos de plantilla

Primero necesitas crear una carpeta para todos tus archivos de módulo. Después de tener el contenedor, usted necesita para crear su archivo de módulo. Usted tiene que asegurarse de que su archivo de módulo tiene el mismo nombre que su carpeta o de lo contrario al tratar de publicar su módulo, PowerShell no descubrirá el módulo correctamente.

PS51> New-Item -Path .\Scripts -Name ATARegistry -ItemType DirectoryPS51> New-Item -Path .\Scripts\ATARegistry -Name ATARegistry.psm1

Ahora usted también desea utilizar un manifiesto, tendrá que también el mismo nombre que el contenedor y el archivo de módulo.

PS51> New-ModuleManifest -Path .\Scripts\ATARegistry\ATARegistry.psd1 -Author 'Tyler Muir' -CompanyName 'Adam the Automator' -RootModule ATARegistry.psm1 -Description 'Used for interacting with registry keys'

Con el contenedor, el archivo de módulo, y el archivo de manifiesto, usted tiene un módulo completo de funcionamiento. Podrías publicar este módulo en un PSRepository y empezar a instalarlo donde quisieras. Aunque, como el archivo del módulo está vacío, probablemente no le servirá de mucho. Aún así puede utilizar estos archivos para probar la publicación y asegurarse de que su repositorio funciona.

Registrando un PSRepository

Antes de poder publicar su módulo, necesitará añadir otro PSRepository a su sesión. Para las pruebas, puede utilizar una ruta local como su PSRepository ya que será fácil de configurar y desmontar.

Normalmente, si fuera a configurar un PSRepository con un directorio, querría asegurarse de que varios equipos pueden acceder a él. Puedes crear un repositorio local así:

PS51> New-Item -Path C:\ -Name Repo -ItemType DirectoryPS51> Register-PSRepository -Name 'LocalRepo' -SourceLocation 'C:\Repo' -PublishLocation 'C:\Repo' -InstallationPolicy Trusted

Si sólo fueras a descargar desde el PSRepository y nunca a publicar, podrías excluir el parámetro PublishLocation.

Publicando tu Módulo

Como ya has configurado la política de instalación como de confianza, no obtendrás una confirmación para permitir que se instale un módulo desde el repositorio. Ahora que tiene un nuevo PSRepository disponible, puede publicar su módulo usando Publish-Module -Name .\Scripts\ATARegistry -Repository LocalRepo.

Después de publicar su módulo, puede usar los comandos de arriba para encontrar el módulo e instalarlo.

Ahora que ha instalado el módulo, puede usar Get-Module para ver el módulo importado en su sesión local. Como no has añadido ninguna función a la matriz FunctionsToExport en el manifiesto, la propiedad ExportedCommands está vacía.

Añadir a tu módulo

Ahora que sabes que puedes publicar e instalar tu módulo, puedes empezar a añadirle alguna funcionalidad. Podrías añadir una función que devuelva una clave de registro para que se vea así:

function Get-ATARegistryKey { param ( $Path ) Get-Item $Path}

Si dejaras el manifiesto como está e intentaras subir tu nuevo módulo te encontrarías con dos problemas. El primero es que recibirías un error indicando que la versión de tu módulo ya existe en tu repositorio. Esto se debe a que no has cambiado la versión del módulo en el archivo de manifiesto.

Exportación de funciones del módulo

El otro problema sería que después de haber importado el módulo, seguirías sin ver ninguna función en la propiedad ExportedCommands porque no has añadido tu nueva función al manifiesto.

Si bien tu función podría ser utilizada sin listarla en la lista FunctionsToExport, haría mucho más difícil su localización.

Para solucionar estos dos problemas, puedes actualizar tu archivo de módulo de la siguiente manera:

ModuleVersion = '1.1'FunctionsToExport = 'Get-RegistryKey'

Ahora que has añadido una función a tu módulo y has actualizado tu manifiesto para reflejar estos cambios, puedes publicar la nueva versión de tu módulo usando el mismo comando que antes.

PS51> Publish-Module -Name .\Scripts\ATARegistry -Repository LocalRepo.

Actualizando tu módulo

El último paso sería que actualizaras tu módulo en tu sesión para poder usar los archivos actualizados. Usando Update-Module ATARegistry descargas la actualización que acabas de publicar en el repositorio.

Ahora puedes ver que tienes la nueva versión del módulo y puedes ver la función que has definido en el manifiesto.

Construyendo el contenido de la ayuda

Una de las opciones que se ha pasado antes es el sistema de ayuda que lleva incorporado PowerShell. Probablemente en algún momento has utilizado Get-Help en una función. Esta información se puede añadir de dos formas principales.

La primera es añadir ayuda basada en comentarios en la definición de la función. Esta es normalmente la forma que muchos escritores de módulos implementan. La otra forma es utilizar un archivo de ayuda externo. Puede utilizar el parámetro Full para mostrar todo lo que la ayuda tiene que ofrecer.

Como puede ver, realmente no hay mucha información y la poca información que obtiene muy probablemente no sería útil para nadie.

Puede añadir alguna ayuda basada en comentarios a su archivo de módulo para rellenar estos campos en el sistema de ayuda. Usted puede leer acerca de todas las opciones para la ayuda basada en comentarios utilizando Get-Help about_Comment_Based_Help.

Por ahora, usted puede actualizar su función para que se vea como abajo. Esta es una lista de los parámetros de ayuda más utilizados, pero todos ellos siguen siendo opcionales y hay otros que podrían añadirse en su lugar.

Ahora su función se ve así:

 function Get-RegistryKey {<# .SYNOPSIS Returns registry key using provided path. .DESCRIPTION The function uses the Get-Item command to return the information for a provided registry key. .PARAMETER Path The path that will be searched for a registry key. .EXAMPLE Get-RegistryKey -Path 'HKLM:\HARDWARE\DESCRIPTION\System' .INPUTS System.String .OUTPUTS Microsoft.Win32.RegistryKey .NOTES This module is an example of what a well documented function could look. .LINKhttps://adamtheautomator.com#>param($Path)Get-Item $Path}

Hay algunos parámetros de ayuda especiales, como .FORWARDHELPTARGETNAME. Esta opción reenvía todas las solicitudes de ayuda entrantes a un comando diferente. Esto podría usarse en un caso en el que la ayuda debería mostrar la misma información para múltiples comandos.

Ahora que ha añadido la ayuda, puede actualizar la versión en el manifiesto del módulo, publicar la nueva versión y actualizar la versión instalada para su sesión como hizo anteriormente.

Si ahora mira la ayuda para la función, puede ver que hay mucha más información disponible. Esta es una gran manera de incluir la documentación sobre cómo utilizar las funciones especialmente para alguien que tiene menos experiencia y puede no ser capaz de entender rápidamente lo que el módulo está haciendo mirando el código.

En el caso de un archivo de ayuda externa, la información añadida es la misma, pero la información se coloca en un archivo separado y se vincula dentro de la función.

Si miras en la ruta del módulo AllUserspodrás ver la versión del módulo y todos los archivos del módulo que has ido instalando.

Si vuelves a la ruta de tu PSRepository C:\Repo que has creado antes, podrás ver un montón de archivos NUPKG. Habrá uno por cada versión que se publicó. Estas son versiones comprimidas de lo que publicaste cuando usaste Publish-Module.

Resumen

Una vez que has conseguido manejar la consola de PowerShell, PowerShell como lenguaje y escribir scripts, construir tus propios módulos es el último paso. Los módulos le permiten comenzar a desarrollar herramientas útiles en PowerShell. Si se diseñan y construyen correctamente creando módulos con un único propósito, inevitablemente te encontrarás escribiendo cada vez menos código con el tiempo. Empezarás a hacer referencia a tus funciones de módulo en más código y a construir a partir de ahí.

Las funciones de módulo te permiten abstraer el código que te encuentras repitiendo en los scripts. Representan «etiquetas» a las que hacer referencia más adelante en el código que puede ser llamado en cualquier momento en lugar de reinventar la rueda y tratar de averiguar cómo usted ya había logrado su objetivo anteriormente. Los módulos son el «empaquetado» final del código PowerShell que agrupa código similar para evitar perder tiempo en problemas que ya has resuelto.