Módulos

La página Modules proporciona información sobre los módulos instalados en el sistema.

Visualización de módulos

Puede ver y buscar los módulos accesibles por PowerShell Universal visitando la página Platform \ Modules. Las búsquedas proporcionan un resultado con comodines de los módulos encontrados en cada uno de los entornos definidos en PowerShell Universal.

Instalar módulos desde la Gallery

Los módulos se pueden instalar desde la PowerShell Gallery. Para buscar un módulo, puede cambiar el menú desplegable situado junto al cuadro de búsqueda de Local a PowerShell Gallery. Las búsquedas realizadas se ejecutarán contra la Gallery en lugar de localmente.

Una vez encontrado un módulo, podrá hacer clic en el botón Install para guardarlo localmente. Los módulos instalados con este método se instalarán en el directorio Repository, dentro de Modules.

Orígenes de paquetes

PowerShell Universal se integra con el módulo PackageManagement v3 y detectará automáticamente los orígenes de paquetes registrados. Por ejemplo, puede registrar un origen de paquetes con el comando siguiente.

Register-PSResourceRepository -Name MyNuGet -Uri https://www.nuget.org/api/v2

Una vez registrado el origen, se mostrará en el menú desplegable de la página de módulos.

Creación de módulos

También puede crear módulos directamente en PowerShell Universal. Estos módulos se crearán en el directorio Repository, dentro de Modules.

Estos módulos estarán disponibles en todos los entornos.

Para crear un nuevo módulo, navegue a Platform \ Modules y haga clic en Create New Module. Defina el nombre y la versión del módulo.

Una vez creado, el módulo aparecerá en Universal Modules con la opción de editar propiedades y contenido, así como de eliminar el módulo.

Al editar el módulo, se abrirá un editor de código donde puede definir funciones, variables y alias para exportar.

Módulos con recursos de Universal

Puede encontrar aquí un módulo de ejemplo.

Instalar

Los módulos pueden contener recursos de PowerShell Universal, como scripts, API y aplicaciones. Al añadir estos módulos a su entorno, se añadirán automáticamente estos recursos a su instancia de PowerShell Universal. Estos recursos serán de solo lectura dentro del entorno. Para eliminarlos, tendrá que eliminar el módulo.

En la Admin Console, haga clic en Platform \ Modules y luego seleccione PowerShell Universal Modules.

PowerShell Universal Modules

Haga clic en el botón de descarga situado a la izquierda del módulo para instalarlo. Una vez instalado, se añadirán recursos de solo lectura a su entorno.

Aplicación de información del sistema Windows

También puede guardar módulos directamente en la carpeta del repositorio de PowerShell Universal.

Save-Module Universal.Apps.WindowsSystemInformation -Path $Env:ProgramData\UniversalAutomation\Repository\Modules

Crear

A continuación se muestra un ejemplo de la estructura de un módulo de Universal. Si el módulo contiene la carpeta .universal, los recursos se cargarán desde ella automáticamente.

.universal 
    scripts.ps1
PSUModule.psd1
PSUModule.psm1

Los recursos no pueden usar rutas y deben usar el nombre del módulo y del comando para asociar los recursos con sus respectivos scripts.

Por ejemplo, el fichero scripts.ps1 anterior tendría que escribirse de esta manera.

New-PSUScript -Module 'PSUModule' -Command 'Start-MyScript'

Dentro de PSUModule.psm1, tendría que definir la función Start-MyScript. Esta es la función que se llamará al ejecutar el script.

function Start-MyScript {

}

Publicar

Al crear módulos que amplían PowerShell Universal, puede incluir la etiqueta PowerShellUniversal en el manifiesto del módulo para que se listen en la página de módulos de PowerShell Universal y en la consola de administración de PSU.

Publique módulos en la PowerShell Gallery para compartirlos con otros.

Módulo raíz

Puede definir un módulo raíz como la configuración de PowerShell Universal. Esto permite configuraciones reproducibles basadas en módulos publicados. Un módulo raíz se define en la configuración de la aplicación del servidor de PowerShell Universal. Cuando PowerShell Universal se inicia, cargará este módulo y sus dependencias automáticamente. El módulo raíz debe encontrarse en el PSModulePath o en la carpeta Modules del Repository.

Ejemplo

A continuación se muestra un ejemplo del uso de un módulo raíz y dependencias para definir una configuración de PowerShell Universal. Los recursos proporcionados por los módulos son de solo lectura dentro de la plataforma. Al usar módulos, puede asegurarse de que versiones específicas de los recursos se empaqueten e implementen en sus instancias de PowerShell Universal.

El módulo raíz puede aparecer en cualquier lugar del PSModulePath registrado para su servidor o cuenta de servicio. También pueden residir en la carpeta de módulos de su repositorio. El ejemplo siguiente utiliza rutas relativas.

ARD.Core

El módulo ARD.Core define algunas funciones y un entorno que utilizan otros módulos. Aquí tiene un ejemplo de un entorno básico que se define.

Modules\ARD.Core\1.0.0\.universal\environments.ps1

New-PSUEnvironment -Name 'ARD.Core' -Path pwsh.exe -Type PowerShell7

Las funciones se definen en el fichero PSM1 del módulo.

Modules\ARD.Core\1.0.0\ARD.Core.psm1

function Get-ARDCore {
    @{
        Name = "ARD.Core"
        Description = "This is a test function result"
    }
}

El manifiesto del módulo exporta la función y proporciona algunos metadatos básicos.

Modules\ARD.Core\1.0.0\ARD.Core.psd1

@{
    RootModule = "ARD.Core.psm1"
    Description = "ARD.Core is the base module for other modules"
    Version = "1.0.0"
    FunctionsToExport = @("Get-ARDCore")
}

ARD.Endpoints

El módulo ARD.Endpoints tiene una estructura similar a la del módulo ARD.Core, pero expone un endpoint en lugar de un entorno. Este endpoint de ejemplo llama a la función Get-ARDResponse cuando se llama a la URL ard.endpoint. Observe que el endpoint utiliza el endpoint de ARD.Core proporcionado por el módulo anterior.

Modules\ARD.Endpoints\1.0.0\.universal\endpoints.ps1

New-PSUEndpoint -Url /ard.endpoint -Module 'ARD.Endpoints' -Command "Get-ARDResponse" -Environment 'ARD.Core'

El fichero ARD.Endpoints.psm1 define la función que se va a exportar y que también podemos usar para el endpoint. El endpoint utiliza la función de ARD.Core para devolver una respuesta. Esto funciona porque todos son simplemente módulos normales de PowerShell.

Modules\ARD.Endpoints\1.0.0\ARD.Endpoints.psm1

function Get-ARDResponse {
    Get-ARDCore
}

El fichero ARD.Endpoints.psd1 exportará la función y también tomará una dependencia de ARD.Core para garantizar que ese módulo se cargue primero, ya que el endpoint depende de que existan tanto la función como el entorno.

Modules\ARD.Endpoints\1.0.0\ARD.Endpoints.psd1

@{
    RootModule = "ARD.Endpoints.psm1"
    Description = "Sample endpoints"
    Version = "1.0.0"
    RequiredModules = @("ARD.Core")
    FunctionsToExport = @("Get-ARDResponse")
}

ARD.Root

PowerShell Universal cargará primero el módulo raíz. Toma una dependencia tanto del módulo core como del de endpoints, pero no define ninguna funcionalidad por sí mismo. PowerShell Universal determinará el orden de carga adecuado y luego cargará los recursos durante el inicio.

@{
    Description = "A PowerShell Universal configuration"
    Version = "1.0.0"
    RequiredModules = @("ARD.Core", "ARD.Endpoints")
}

En la configuración de la aplicación, puede seleccionar el módulo raíz y la versión.

appsettings.json

{
    "Data": {
        "Module": "ARD.Root",
        "ModuleVersion": "1.0.0"
    }
}

También puede configurarlo mediante variables de entorno. Cambiar el fichero o las variables de entorno requerirá reiniciar PowerShell Universal.

$ENV:Data__Module = "ARD.Root"
$ENV:Data__ModuleVersion = "1.0.0"

Instalar módulos manualmente

PowerShell Universal añadirá el directorio Modules del repositorio al $ENV:PSModulePath de todos los entornos. Añadir módulos a este directorio garantizará que el módulo esté disponible para cualquier proceso de PowerShell que se ejecute con PowerShell Universal.

Información del módulo

Esta sección incluye información sobre ciertos módulos y su uso en PowerShell Universal.

ActiveDirectory

El módulo ActiveDirectory admite compatibilidad nativa con PowerShell 7 al usar la versión 1.0.1.0. Al usar la versión 1.0.0.0, se utiliza la capa de compatibilidad de Windows al ejecutar los comandos en PowerShell 7 y el entorno Integrated. Esto puede causar problemas en PowerShell Universal. Nuestras recomendaciones para este módulo son las siguientes.

Windows Server 2019 y superior

Actualice el módulo ActiveDirectory a la versión 1.0.1.0, que tiene compatibilidad con PowerShell Core

Windows Server 2016 e inferior

Elija 1 de las 2 soluciones alternativas disponibles:

• Incluya el parámetro -SkipEditionCheck con Import-Module al importar el módulo ActiveDirectory
• Utilice el entorno Windows PowerShell 5.1 en lugar de Integrated/PowerShell Core

Lecturas adicionales

Increased Windows Modules coverage with PowerShell Core 6.1 - PowerShell TeamPowerShell Team

Exchange

Microsoft Exchange local se puede gestionar usando sesiones remotas en PowerShell. Si utiliza sesiones en aplicaciones, deberá considerar gestionar la sesión de forma que evite tener que abrir una nueva sesión para cada solicitud. Esto mejora considerablemente el rendimiento. El ejemplo siguiente utiliza el ámbito $Cache: para conservar la sesión entre solicitudes.

Aunque este ejemplo utiliza PSSessions y Exchange, podría usar el mismo patrón para otros tipos de conexiones persistentes.

$Cache:ExchangeServer = ''
$Cache:ExchangeCredential = ''
$Cache:ExchangeSessionInfo = @{

    Authentication    = 'Kerberos'
    ConfigurationName = 'Microsoft.Exchange'
    ConnectionUri     = 'https://{0}/PowerShell/' -f $Cache:ExchangeServer
    Credential        = $Cache:ExchangeCredential
    WarningAction     = 'SilentlyContinue'
}

#region PRIVATE FUNCTIONS

Function Script:Connect-ExchServer {
    $exchSession = New-PSSession @Cache:ExchangeSessionInfo
    Import-PSSession $exchSession -WarningAction 'SilentlyContinue'
}


Function Script:Test-ExchConnected {
    $Current = Get-PSSession | Where-Object { $_.ConfigurationName -eq 'Microsoft.Exchange' }
    if ($Current.State -eq 'Opened' -and $Current.Availability -eq 'Available') {
        $true
    }
    else {
        $false
    }
}

#endregion

#region PUBLIC FUNCTIONS 

Function Clear-ExchConnection {
    # called publicly in "End{}" blocks.
    Get-PSSession | Where-Object { $_.ConfigurationName -eq 'Microsoft.Exchange' } | Remove-PSSession -ErrorAction $Cache:ErrorAction
    Get-Module | Where-Object { $_.Description -match $Cache:ExchangeServer } | Remove-Module -Force -ErrorAction $Cache:ErrorAction
}


Function Confirm-ExchConnected {
     # called publicly in "Begin{}" blocks, or just before Exhange actions in functions or scripts.
    if (!( Test-ExchConnected )) {
        Clear-ExchConnection
        Connect-ExchServer
    }
}

#endregion

function Invoke-ExampleExchFunction {
    Param (
        $something
    )

    Begin {
        $null = Confirm-ExchConnected
    }
    
    Process {
        return $something
    }
    
    End {
        Clear-ExchConnection
    }
}

Versiones de módulos validadas

Las versiones de módulos que se indican a continuación se han validado con PowerShell Universal. La validación de módulos garantiza que estos módulos se cargan e interactúan con sus respectivos servicios.

Módulo	Versión del módulo	Versión de PSU	Entornos de PSU
Microsoft.Graph.Authentication	2.26.1	5.5.2	PowerShell 7
ExchangeOnlineManagement	3.7.2	5.5.2	PowerShell 7
MicrosoftTeams	6.9.0	5.5.2	PowerShell 7
Az.Accounts	4.1.0	5.5.2	PowerShell 7, Integrated