about_Modules

Artículo
05/25/2021
Tiempo de lectura: 13 minutos

Descripción breve

Explica cómo instalar, importar y usar módulos de PowerShell.

Descripción larga

Un módulo es un paquete que contiene miembros de PowerShell, como cmdlets, proveedores, funciones, flujos de trabajo, variables y alias.

Las personas que escriben comandos pueden utilizar módulos para organizar sus comandos y compartirlos con otras personas. Las personas que reciben módulos pueden agregar los comandos de los módulos a sus sesiones de PowerShell y usarlos igual que los comandos integrados.

En este tema se explica cómo usar módulos de PowerShell. Para obtener información sobre cómo escribir módulos de PowerShell, vea Escribir un módulo de PowerShell.

¿Qué es un módulo?

Un módulo es un paquete que contiene miembros de PowerShell, como cmdlets, proveedores, funciones, flujos de trabajo, variables y alias. Los miembros de este paquete se pueden implementar en un script de PowerShell, un archivo DLL compilado o una combinación de ambos. Estos archivos normalmente se agrupan en un único directorio. Para más información, consulte Descripción de un Windows PowerShell en la documentación del SDK.

Carga automática de módulos

A partir de PowerShell 3.0, PowerShell importa módulos automáticamente la primera vez que ejecuta cualquier comando en un módulo instalado. Ahora puede utilizar los comandos de un módulo sin realizar ninguna instalación o configuración de perfil, por lo que no es necesario administrar los módulos después de instalarlos en el equipo.

Además, los comandos de un módulo son más fáciles de encontrar. El Get-Command cmdlet ahora obtiene todos los comandos de todos los módulos instalados, incluso si aún no están en la sesión. Puede encontrar un comando y usarlo sin necesidad de importar primero el módulo.

Cada uno de los ejemplos siguientes hace que el módulo CimCmdlets, que contiene Get-CimInstance , se importe en la sesión.

Ejecución del comando
```
Get-CimInstance Win32_OperatingSystem
```
Obtener el comando
```
Get-Command Get-CimInstance
```
Obtener ayuda para el comando
```
Get-Help Get-CimInstance
```

Get-Command Los comandos que incluyen un carácter comodín ( ) se consideran para la detección, no se usan y no * importan ningún módulo.

Solo se importan automáticamente los módulos almacenados en la ubicación especificada por la variable de entorno PSModulePath. Los módulos de otras ubicaciones se deben importar mediante la ejecución del Import-Module cmdlet .

Además, los comandos que usan proveedores de PowerShell no importan automáticamente un módulo. Por ejemplo, si usa un comando que requiere la unidad WSMan:, como el cmdlet , es posible que tenga que ejecutar el cmdlet para importar el módulo Get-PSSessionConfiguration Import-Module Microsoft.WSMan.Management que incluye la WSMan: unidad.

Todavía puede ejecutar el comando para importar un módulo y usar la variable para habilitar, deshabilitar y configurar la Import-Module importación automática de $PSModuleAutoloadingPreference módulos. Para obtener más información, vea about_Preference_Variables.

Cómo usar un módulo

Para utilizar un módulo, realice las tareas siguientes:

Instale el módulo. (Esto a menudo se hace automáticamente).
Busque los comandos que agregó el módulo.
Utilice los comandos que agregó el módulo.

En este tema se explica cómo realizar estas tareas. También se incluye otra información útil acerca de la administración de módulos.

Cómo instalar un módulo

Si recibe un módulo como una carpeta con archivos en él, debe instalarlo en el equipo para poder usarlo en PowerShell.

La mayoría de los módulos se instalan automáticamente. PowerShell incluye varios módulos preinstalados, a veces denominados módulos principales. En equipos basados en Windows, si las características que se incluyen con el sistema operativo tienen cmdlets para administrarlos, esos módulos están preinstalados. Al instalar una característica de Windows mediante, por ejemplo, el Asistente para agregar roles y características en Administrador del servidor o el cuadro de diálogo Activar o desactivar características de Windows en Panel de control, se instalan los módulos de PowerShell que forman parte de la característica. Muchos otros módulos se presentan como un instalador o un programa de instalación que instala el módulo.

Use el siguiente comando para crear un directorio Modules para el usuario actual:

New-Item -Type Directory -Path $HOME\Documents\PowerShell\Modules

Copie la carpeta de módulo al completo en el directorio Modules. Puede usar cualquier método para copiar la carpeta, incluidos Explorador de Windows y Cmd.exe, así como PowerShell. En PowerShell, use el Copy-Item cmdlet . Por ejemplo, para copiar la carpeta MyModule del C:\ps-test\MyModule directorio Modules, escriba:

Copy-Item -Path C:\ps-test\MyModule -Destination `
    $HOME\Documents\PowerShell\Modules

Puede instalar un módulo en cualquier ubicación, pero es más fácil administrar los módulos si se instalan en una ubicación predeterminada. Para más información sobre las ubicaciones predeterminadas del módulo, consulte la sección Ubicaciones de recursos de MÓDULO y DSC y PSModulePath.

Cómo buscar módulos instalados

Para encontrar los módulos que están instalados en una ubicación de módulo predeterminada pero que aún no se han importado a la sesión, escriba:

Get-Module -ListAvailable

Para buscar los módulos que ya se han importado en la sesión, en el símbolo del sistema de PowerShell, escriba:

Get-Module

Para obtener más información sobre Get-Module el cmdlet , vea Get-Module.

Cómo buscar los comandos en un módulo

Use el Get-Command cmdlet para buscar todos los comandos disponibles. Puede usar los parámetros del cmdlet para filtrar comandos como Get-Command por módulo, nombre y nombre.

Para encontrar todos los comandos de un módulo, escriba:

Get-Command -Module <module-name>

Por ejemplo, para buscar los comandos en el módulo BitsTransfer, escriba:

Get-Command -Module BitsTransfer

Para obtener más información sobre el Get-Command cmdlet , vea Get-Command.

Cómo Obtener ayuda para los comandos de un módulo

Si el módulo contiene archivos de Ayuda para los comandos que exporta, el Get-Help cmdlet mostrará los temas de Ayuda. Use el mismo Get-Help formato de comando que usaría para obtener ayuda para cualquier comando de PowerShell.

A partir de PowerShell 3.0, puede descargar archivos de Ayuda para un módulo y descargar actualizaciones en los archivos de Ayuda para que nunca estén obsoletos.

Para obtener ayuda para un comando de un módulo, escriba:

Get-Help <command-name>

Para obtener ayuda en línea para el comando en un módulo, escriba:

Get-Help <command-name> -Online

Para descargar e instalar los archivos de ayuda de los comandos de un módulo, escriba:

Update-Help -Module <module-name>

Para obtener más información, vea Get-Help y Update-Help.

Cómo importar un módulo

Podría tener que importar un módulo o importar un archivo de módulo. La importación es necesaria cuando un módulo no está instalado en las ubicaciones especificadas por la variable de entorno PSModulePath, , o el módulo consta de un archivo , como un archivo .dll o .psm1, en lugar del módulo típico que se entrega como una $env:PSModulePath carpeta.

También puede optar por importar un módulo para poder usar los parámetros del comando, como el parámetro Prefix, que agrega un prefijo distintivo a los nombres de nombres de todos los comandos importados, o el parámetro Import-Module NoClobber, que impide que el módulo agregue comandos que oculten o reemplacen los comandos existentes en la sesión.

Para importar módulos, use el Import-Module cmdlet .

Para importar módulos en una ubicación PSModulePath en la sesión actual, utilice el formato de comando siguiente.

Import-Module <module-name>

Por ejemplo, el siguiente comando importa el módulo BitsTransfer en la sesión actual.

Import-Module BitsTransfer

Para importar un módulo que no está en una ubicación de módulo predeterminada, utilice la ruta de acceso completa a la carpeta del módulo en el comando.

Por ejemplo, para agregar el módulo TestCmdlets en el C:\ps-test directorio a la sesión, escriba:

Import-Module C:\ps-test\TestCmdlets

Para importar un archivo de módulo que no se encuentra en una carpeta de módulo, utilice la ruta de acceso completa al archivo de módulo en el comando.

Por ejemplo, para agregar el módulo TestCmdlets.dll en el C:\ps-test directorio a la sesión, escriba:

Import-Module C:\ps-test\TestCmdlets.dll

Para obtener más información sobre cómo agregar módulos a la sesión, vea Import-Module.

Cómo importar un módulo en cada sesión

El Import-Module comando importa módulos a la sesión actual de PowerShell. Para importar un módulo en cada sesión de PowerShell que inicie, agregue el Import-Module comando al perfil de PowerShell.

Para obtener más información sobre los perfiles, consulte about_Profiles.

Cómo quitar un módulo

Al quitar un módulo, se eliminan de la sesión los comandos que el módulo agregó.

Para quitar un módulo de la sesión, use el siguiente formato de comando.

Remove-Module <module-name>

Por ejemplo, el comando siguiente quita el módulo BitsTransfer de la sesión actual.

Remove-Module BitsTransfer

Si quita un módulo, se invierte la operación de importación de un módulo. Si quita un módulo, dicho módulo no se desinstala. Para obtener más información, vea Remove-Module.

Ubicaciones de recursos de DSC y módulo, y PSModulePath

La variable de entorno contiene una lista de ubicaciones de carpeta que se buscan $env:PSModulePath para buscar módulos y recursos.

De forma predeterminada, las ubicaciones efectivas $env:PSModulePath asignadas a son:

Ubicaciones de todo el sistema: $PSHOME\Modules

Estas carpetas contienen módulos que se incluyen con Windows y PowerShell.

Los recursos de DSC que se incluyen con PowerShell se almacenan en la $PSHOME\Modules\PSDesiredStateConfiguration\DSCResources carpeta .
Módulos específicos del usuario: son módulos instalados por el usuario en el ámbito del usuario. Install-Module tiene un parámetro Scope que permite especificar si el módulo está instalado para el usuario actual o para todos los usuarios. Para obtener más información, vea Install-Module.

La ubicación CurrentUser específica del usuario en Windows es la carpeta ubicada en PowerShell\Modules la ubicación Documentos del perfil de usuario. La ruta de acceso específica de esa ubicación varía según la versión de Windows y si usa o no el redireccionamiento de carpetas. Microsoft OneDrive también puede cambiar la ubicación de la carpeta Documentos.

De forma predeterminada, en Windows 10, esa ubicación es $HOME\Documents\PowerShell\Modules . En Linux o Mac, la ubicación CurrentUser es $HOME/.local/share/powershell/Modules .

Nota

Puede comprobar la ubicación de la carpeta Documentos mediante el siguiente comando: [Environment]::GetFolderPath('MyDocuments') .
La ubicación AllUsers está $env:PROGRAMFILES\PowerShell\Modules en Windows. En Linux o Mac, los módulos se almacenan en /usr/local/share/powershell/Modules .

Nota

Para agregar o cambiar archivos en el $env:Windir\System32 directorio, inicie PowerShell con la opción Ejecutar como administrador.

Puede cambiar las ubicaciones predeterminadas del módulo en el sistema cambiando el valor de la variable de entorno PSModulePath, $Env:PSModulePath . La variable de entorno PSModulePath se modela en la variable de entorno Path y tiene el mismo formato.

Para ver las ubicaciones de módulo predeterminadas, escriba:

$Env:PSModulePath

Para agregar una ubicación de módulo predeterminada, utilice el formato de comando siguiente.

$Env:PSModulePath = $Env:PSModulePath + ";<path>"

El punto y coma ( ) del comando separa la nueva ruta de acceso de la ruta de acceso ; que la precede en la lista.

Por ejemplo, para agregar el C:\ps-test\Modules directorio, escriba:

$Env:PSModulePath + ";C:\ps-test\Modules"

Para agregar una ubicación de módulo predeterminada en Linux o MacOS, use el siguiente formato de comando:

$Env:PSModulePath += ":<path>"

Por ejemplo, para agregar el directorio al valor de la variable de entorno /usr/local/Fabrikam/Modules PSModulePath, escriba:

$Env:PSModulePath += ":/usr/local/Fabrikam/Modules"

En Linux o MacOS, los dos puntos ( ) del comando separan la nueva ruta de acceso de la ruta de acceso : que la precede en la lista.

Al agregar una ruta de acceso a PSModulePath, los comandos incluyen Get-Module Import-Module módulos en esa ruta de acceso.

El valor que establezca afectará solo a la sesión actual. Para que el cambio sea persistente, agregue el comando al perfil de PowerShell o use System en Panel de control para cambiar el valor de la variable de entorno PSModulePath en el Registro.

Además, para que el cambio sea persistente, también puede usar el método SetEnvironmentVariable de la clase System.Environment para agregar una ruta de acceso a la variable de entorno PSModulePath.

Para obtener más información sobre la variable PSModulePath, vea about_Environment_Variables.

Módulos y conflictos de nombres

Cuando más de un comando en la sesión tiene el mismo nombre, se producen conflictos de nombre. La importación de un módulo provoca un conflicto de nombres si los comandos del módulo tienen los mismos nombres que los comandos o elementos de la sesión.

Los conflictos de nombres pueden ocultar o reemplazar los comandos.

Hidden

Se oculta un comando si no es el comando que se ejecuta cuando se escribe el nombre de comando, pero puede ejecutarlo mediante otro método, por ejemplo calificando el nombre de comando con el nombre del módulo o complemento en el que se originó.

Reemplazados

Se reemplaza un comando cuando no se puede ejecutar porque lo ha sobrescrito un comando con el mismo nombre. Incluso si se quita el módulo que provocó el conflicto, no se puede ejecutar un comando reemplazado a menos que se reinicie la sesión.

Import-Module podría agregar comandos que oculte y reemplace los comandos en la sesión actual. Además, los comandos de la sesión pueden ocultar comandos agregados por el módulo.

Para detectar conflictos de nombres, use el parámetro All del Get-Command cmdlet . A partir de PowerShell 3.0, obtiene solo los comandos que se Get-Command ejecutan al escribir el nombre del comando. El parámetro All obtiene todos los comandos con el nombre específico de la sesión.

Para evitar conflictos de nombres, use los parámetros NoClobber o Prefix del Import-Module cmdlet . El parámetro Prefix agrega un prefijo a los nombres de los comandos importados para que sean únicos en la sesión. El parámetro NoClobber no importa ningún comando que oculte o reemplace los comandos existentes en la sesión.

También puede usar los parámetros Alias, Cmdlet, Function y Variable de para seleccionar solo los comandos que desea importar y puede excluir comandos que causen conflictos de nombres en Import-Module la sesión.

Los autores de módulos pueden evitar conflictos de nombres mediante la propiedad DefaultCommandPrefix del manifiesto del módulo para agregar un prefijo predeterminado a todos los nombres de comando. El valor del parámetro Prefix tiene prioridad sobre el valor de DefaultCommandPrefix.

Incluso si un comando está oculto, puede ejecutarlo calificando el nombre de comando con el nombre del módulo o complemento en el que se originó.

Las reglas de precedencia de comandos de PowerShell determinan qué comando se ejecuta cuando la sesión incluye comandos con el mismo nombre.

Por ejemplo, cuando una sesión incluye una función y un cmdlet con el mismo nombre, PowerShell ejecuta la función de forma predeterminada. Cuando la sesión incluye comandos del mismo tipo con el mismo nombre, como dos cmdlets con el mismo nombre, de forma predeterminada ejecuta el comando agregado más recientemente.

Para obtener más información, incluida una explicación de las reglas de precedencia e instrucciones para ejecutar comandos ocultos, vea about_Command_Precedence.

Módulos y complementos

Puede agregar comandos a la sesión desde módulos y complementos. Los módulos pueden agregar todos los tipos de comandos, incluidos cmdlets, proveedores y funciones, y elementos, como variables, alias y unidades de PowerShell. Los complementos solo pueden agregar cmdlets y proveedores.

Antes de quitar un módulo o un complemento de la sesión, utilice los comandos siguientes para determinar qué comandos se quitarán.

Para buscar el origen de un cmdlet en la sesión, use el siguiente formato de comando:

Get-Command <cmdlet-name> | Format-List -Property verb,noun,pssnapin,module

Por ejemplo, para buscar el origen del Get-Date cmdlet, escriba:

Get-Command Get-Date | Format-List -Property verb,noun,module

Los comandos que exporta un módulo deben seguir las reglas de nomenclatura de comandos de PowerShell. Si el módulo que importa exporta cmdlets o funciones que tienen verbos no aprobados en sus nombres, el cmdlet muestra Import-Module el siguiente mensaje de advertencia.

ADVERTENCIA: Algunos nombres de comandos importados incluyen verbos no aprobados que podrían hacer que no se puedan detectar. Utilice el parámetro Verbose para obtener más detalles o escriba Get-Verb para ver la lista de verbos aprobados.

Este mensaje es sólo una advertencia. El módulo completo se importa de todos modos, incluidos los comandos que no cumplen las especificaciones. Aunque el mensaje se muestra a los usuarios del módulo, el autor del módulo debe corregir el problema de nomenclatura.

Para suprimir el mensaje de advertencia, use el parámetro DisableNameChecking del Import-Module cmdlet .

Módulos y complementos integrados

En PowerShell 2.0 y en programas host de estilo anterior en PowerShell 3.0 y versiones posteriores, los comandos principales que se instalan con PowerShell se empaquetan en complementos que se agregan automáticamente a cada sesión de PowerShell.

A partir de PowerShell 3.0, para los programas host que implementan la API de estado de sesión inicial, el complemento Microsoft.PowerShell.Core se agrega a cada sesión de InitialSessionState.CreateDefault2 forma predeterminada. Los módulos se cargan automáticamente en el primer uso.

Nota

Las sesiones remotas, incluidas las que se inician mediante el cmdlet , son sesiones de estilo anterior en las que los comandos integrados se empaquetan en New-PSSession complementos.

Los siguientes módulos (o complementos) se instalan con PowerShell.

CimCmdlets
Microsoft.PowerShell.Archive
Microsoft.PowerShell.Core
Microsoft.PowerShell.Diagnostics
Microsoft.PowerShell.Host
Microsoft.PowerShell.Management
Microsoft.PowerShell.Security
Microsoft.PowerShell.Utility
Microsoft.WSMan.Management
PackageManagement
PowerShellGet
PSDesiredStateConfiguration
PSDiagnostics
PSReadline

Registrar eventos del módulo

A partir de PowerShell 3.0, puede registrar eventos de ejecución para los cmdlets y funciones en módulos y complementos de PowerShell estableciendo la propiedad LogPipelineExecutionDetails de los módulos y complementos en $True . También puede usar una configuración de directiva de grupo, Activar registro de módulos, para habilitar el registro de módulos en todas las sesiones de PowerShell. Para más información, consulte los artículos sobre el registro y la directiva de grupo.