Acerca de los módulos

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 comandos de PowerShell, como cmdlets, proveedores, funciones, flujos de trabajo, variables y alias.

Las personas que escriben comandos pueden usar módulos para organizar sus comandos y compartirlos con otros. 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, consulte Escribir un módulo de PowerShell.

¿Qué es un módulo?

Un módulo es un paquete de comandos. Todos los cmdlets y proveedores de la sesión se agregan mediante un módulo o un complemento.

Carga automática de módulos

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

Los comandos de un módulo también 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, por lo que puede buscar un comando y usarlo sin importarlo.

Cada uno de los siguientes ejemplos hace que el módulo que contiene Get-Mailbox se importe a la sesión.

Ejecutar el comando
```
Get-Mailbox -Identity Chris
```
Obtener el comando
```
Get-Command Get-Mailbox
```
Obtener ayuda para el comando
```
Get-Help Get-Mailbox
```

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

Solo los módulos que se almacenan en la ubicación especificada por la variable de entorno PSModulePath se importan automáticamente. 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 Get-PSSessionConfiguration cmdlet, es posible que tenga que ejecutar el Import-Module cmdlet para importar el módulo Microsoft.WSMan.Management que incluye la WSMan: unidad.

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

Cómo usar un módulo

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

Instale el módulo. (Esto a menudo se hace por usted).
Encuentre 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 incluye otra información útil sobre la gestión de módulos.

Cómo instalar un módulo

Si recibe un módulo como una carpeta con archivos, debe instalarlo en su computadora antes de poder usarlo en PowerShell.

La mayoría de los módulos se instalan automáticamente. PowerShell viene con varios módulos preinstalados, a veces llamados módulos "principales". En los equipos basados en Windows, si las características que se incluyen con el sistema operativo tienen cmdlets para administrarlas, 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 el Administrador del servidor o el cuadro de diálogo Activar o desactivar características de Windows en el Panel de control, se instalan todos los módulos de PowerShell que forman parte de la característica. Muchos otros módulos vienen en un instalador o programa de instalación que instala el módulo.

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

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

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

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

Puede instalar un módulo en cualquier ubicación, pero instalar los módulos en una ubicación de módulo predeterminada facilita su administración. Para obtener más información sobre las ubicaciones predeterminadas de los módulos, consulte la sección Ubicaciones de recursos de módulos y DSC y PSModulePath .

Cómo encontrar módulos instalados

Para buscar 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 a la sesión, en el símbolo del sistema de PowerShell, escriba:

Get-Module

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

Cómo encontrar los comandos en un módulo

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

Para buscar 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 cmdlet Get-Command, consulte 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 de los archivos de ayuda para que nunca queden obsoletos.

Para obtener ayuda para los comandos 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

Es posible que tenga 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 , $env:PSModulePatho el módulo consta de un archivo, como un archivo .dll o .psm1, en lugar de un módulo típico que se entrega como una carpeta.

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

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

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

Import-Module <module-name>

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

Import-Module BitsTransfer

Para importar un módulo que no se encuentra 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 directorio a la C:\ps-test sesión, escriba:

Import-Module C:\ps-test\TestCmdlets

Para importar un archivo de módulo que no está contenido 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 directorio C:\ps-test 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, consulte Import-Module.

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

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

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

Cómo eliminar un módulo

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

Para eliminar un módulo de la sesión, utilice el siguiente formato de comando.

Remove-Module <module-name>

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

Remove-Module BitsTransfer

Al quitar un módulo, se invierte el funcionamiento de la importación de un módulo. La eliminación de un módulo no desinstala el módulo. Para obtener más información, consulte Remove-Module.

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

A continuación se muestran las ubicaciones predeterminadas de los módulos de PowerShell. A partir de PowerShell 4.0, con la introducción de DSC, se introdujo un nuevo módulo predeterminado y una carpeta de recursos de DSC. Para obtener más información sobre DSC, consulte about_DesiredStateConfiguration.

Sistema: $PSHOME\Modules o ($env:windir\System32\WindowsPowerShell\v1.0\Modules) Los módulos del sistema son los que se envían con Windows y PowerShell.

A partir de PowerShell 4.0, cuando se introdujo la configuración de estado deseado (DSC) de PowerShell, los recursos de DSC que se incluyen con PowerShell también se almacenan en $PSHOME\Modules, en la $PSHOME\Modules\PSDesiredStateConfiguration\DSCResources carpeta.
Usuario actual: $HOME\Documents\WindowsPowerShell\Modules ($env:UserProfile\Documents\WindowsPowerShell\Modules)

o

$HOME\My Documents\WindowsPowerShell\Modules ($env:UserProfile\My Documents\WindowsPowerShell\Modules)

Esta es la ubicación de los módulos agregados por el usuario antes de PowerShell 4.0.

En PowerShell 4.0 y versiones posteriores de PowerShell, los módulos agregados por el usuario y los recursos de DSC se almacenan en C:\Program Files\WindowsPowerShell\Modulesarchivos . Todos los usuarios del equipo pueden acceder a los módulos y recursos DSC de esta ubicación. Este cambio era necesario porque el motor de DSC se ejecuta como sistema local y no podía acceder a rutas específicas del usuario, como $home\Documents\WindowsPowerShell\Modules.

A partir de PowerShell 5.0, con la adición del módulo PowerShellGet y la Galería de PowerShell de recursos creados por Microsoft y de la comunidad, el Install-Module comando instala módulos y recursos de DSC de C:\Program Files\WindowsPowerShell\Modules forma predeterminada.

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 de los módulos 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 predeterminadas de los módulos, escriba:

$Env:PSModulePath

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

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

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

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

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

Al agregar una ruta de acceso a PSModulePathGet-Module y Import-Module los comandos incluyen módulos en esa ruta de acceso.

El valor que establezca solo afecta a la sesión actual. Para que el cambio sea persistente, agregue el comando al perfil de PowerShell o use Sistema en el 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

Los conflictos de nombres se producen cuando más de un comando de la sesión tiene el mismo nombre. La importación de un módulo produce un conflicto de nombres cuando los comandos del módulo tienen los mismos nombres que los comandos o elementos de la sesión.

Los conflictos de nombres pueden dar lugar a que los comandos estén ocultos o reemplazados.

Oculto

Un comando se oculta cuando no es el comando que se ejecuta al escribir el nombre del comando, pero puede ejecutarlo mediante otro método, por ejemplo, calificando el nombre del comando con el nombre del módulo o complemento en el que se originó.

Reemplazado

Un comando se reemplaza cuando no se puede ejecutar porque se ha sobrescrito con un comando con el mismo nombre. Incluso cuando elimina el módulo que causó el conflicto, no puede ejecutar un comando reemplazado a menos que reinicie la sesión.

Import-Module puede agregar comandos que ocultan y reemplazan comandos en la sesión actual. Además, los comandos de la sesión pueden ocultar los comandos que ha añadido el módulo.

Para detectar conflictos de nombres, use el parámetro All del cmdlet Get-Command. A partir de PowerShell 3.0, Get-Command solo se obtienen los comandos que se 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 cmdlet Import-Module. 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.

Puede usar también el alias , el cmdlet , la función y los parámetros de variable de Import-Module para seleccionar solo los comandos que desea importar, y puede excluir los comandos que provocan conflictos de nombre en la sesión.

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

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

Las reglas de prioridad 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, consulte 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 complemento de la sesión, use los siguientes comandos para determinar qué comandos se quitarán.

Para encontrar 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 cmdlet Get-Date, escriba:

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

Para obtener más información sobre los complementos de PowerShell, consulte about_PSSnapins.

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 Import-Module cmdlet muestra el siguiente mensaje de advertencia.

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

Este mensaje es solo una advertencia. El módulo completo se sigue importando, incluidos los comandos no conformes. 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 incorporados y complementos

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 InitialSessionState.CreateDefault2 sesión inicial, el complemento Microsoft.PowerShell.Core se agrega a cada sesión de forma predeterminada. Los módulos se cargan automáticamente en el primer uso.

Nota:

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

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

Microsoft.PowerShell.Archive
Microsoft.PowerShell.Core
Microsoft.PowerShell.Diagnostics
Microsoft.PowerShell.Host
Microsoft.PowerShell.Management
Microsoft.PowerShell.ODataUtils
Microsoft.PowerShell.Security
Microsoft.PowerShell.Utility
Microsoft.WSMan.Management
Gestión de paquetes
PowerShellGet
PSDesiredStateConfiguration
PSReadline
PSScheduledJob
PSWorkflow
PSWorkflowUtility
ISE

Eventos del módulo de registro

A partir de PowerShell 3.0, puede registrar eventos de ejecución para los cmdlets y las funciones de los 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 el registro de módulos, para habilitar el registro de módulos en todas las sesiones de PowerShell. Para obtener más información, consulte about_EventLogs y about_Group_Policy_Settings.