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 utilizar módulos para organizar sus comandos y compartirlos con otras personas. 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 Escritura de 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 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, por lo que puede encontrar un comando y usarlo sin importarlo.
Cada uno de los ejemplos siguientes hace que el módulo que contiene Get-Mailbox se importe en la sesión.
Ejecutar el comando
Get-Mailbox -Identity ChrisObtener el comando
Get-Command Get-MailboxObtener ayuda para el comando
Get-Help Get-Mailbox
Get-Command Los comandos que incluyen un carácter comodín (*) se consideran para la detección, no para usar 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 deben importarse 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 $PSModuleAutoloadingPreference variable para habilitar, deshabilitar y configurar la 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 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 los 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 todos los módulos de PowerShell que formen 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\WindowsPowerShell\Modules
Copie la carpeta de módulo al completo en el directorio Modules. Puede usar cualquier método para copiar la carpeta, incluido el 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\WindowsPowerShell\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 obtener 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 el Get-Module cmdlet, consulte 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 Get-Command cmdlet para filtrar comandos como 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, 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 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 , $env:PSModulePatho el módulo consta de archivo, como un archivo .dll o .psm1, en lugar de un módulo típico que se entrega como una carpeta.
También puede importar un módulo para que pueda usar los parámetros del Import-Module comando, como el parámetro Prefix, que agrega un prefijo distintivo a los nombres de todos los comandos importados o el parámetro NoClobber , lo 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 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 a 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 directorio a la C:\ps-test 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 directorio a la C:\ps-test 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 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 siguiente comando 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, consulte Remove-Module.
Ubicaciones de recursos de DSC y módulo 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\Moduleso ($env:windir\System32\WindowsPowerShell\v1.0\Modules) Los módulos del sistema son aquellos que se incluyen con Windows y PowerShell.A partir de PowerShell 4.0, cuando se introdujo PowerShell Desired State Configuration (DSC), los recursos de DSC que se incluyen con PowerShell también se almacenan en
$PSHOME\Modules, en la$PSHOME\Modules\PSDesiredStateConfiguration\DSCResourcescarpeta .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\Modules. Todos los usuarios del equipo pueden acceder a los módulos y los recursos de DSC en esta ubicación. Este cambio fue necesario porque el motor de DSC se ejecuta como sistema local y no pudo acceder a rutas de acceso 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 la comunidad y Microsoft, el Install-Module comando instala módulos y recursos de DSC en C:\Program Files\WindowsPowerShell\Modules de 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 de módulo predeterminadas del 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 (;) en el comando separa la nueva ruta de la ruta de acceso 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 PSModulePath y Get-ModuleImport-Module los comandos incluyen módulos en esa ruta de acceso.
El valor que establezca afectará solo a la sesión actual. Para realizar el cambio 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 hacer 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.
Conflictos de módulos y 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 ocultan y reemplazan 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, Get-Command solo obtiene 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 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 Import-Module para seleccionar solo los comandos que desea importar y puede excluir comandos que provocan conflictos de nombres en 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 y las 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 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
Para obtener más información sobre los complementos de PowerShell, consulte about_PSSnapins.
Advertencias y errores relacionados con módulos
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. 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 InitialSessionState.CreateDefault2 API de estado de 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 anterior 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
- PackageManagement
- 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 funciones de los módulos y complementos de PowerShell estableciendo la propiedad LogPipelineExecutionDetails de 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 obtener más información, consulte about_EventLogs y about_Group_Policy_Settings.
Consulte también
about_DesiredStateConfiguration