about_Modules
Descripción breve
Explica cómo instalar, importar y usar módulos de PowerShell.
Descripción larga
PowerShell es un shell de comandos y un lenguaje de scripting. Los comandos de PowerShell se implementan como scripts, funciones o cmdlets. El lenguaje incluye palabras clave, que proporcionan la estructura y la lógica del procesamiento, y otros recursos, como variables, proveedores, alias.
Un módulo es una unidad autocontenida y reutilizable que puede incluir cmdlets, proveedores, funciones, variables y otros recursos. De forma predeterminada, PowerShell carga automáticamente un módulo instalado la primera vez que se usa un comando desde el módulo. Puede configurar el comportamiento de carga automática de módulos mediante la variable $PSModuleAutoloadingPreference. Para obtener más información, consulte about_Preference_Variables.
También puede cargar o descargar manualmente módulos durante una sesión de PowerShell. Para cargar o volver a cargar un módulo, use Import-Module. Para descargar un módulo, use el Remove-Module cmdlet .
PowerShell incluye un conjunto base de módulos. Cualquier persona puede crear nuevos módulos mediante C# o el propio lenguaje de scripting de PowerShell. Los módulos escritos en C# como ensamblados .NET compilados se conocen como módulos nativos. Los módulos escritos en PowerShell se conocen como módulos de script.
En este artículo se explica cómo usar módulos de PowerShell. Para obtener información sobre cómo crear módulos de PowerShell, consulte Escritura de un módulo de PowerShell.
Nota:
Antes de PowerShell 3.0, los cmdlets y los proveedores se empaquetaban en complementos de PowerShell. A partir de PowerShell 3.0, el complemento Microsoft.PowerShell.Core se agrega a cada sesión de forma predeterminada. Este es el único complemento restante en PowerShell. Todos los demás complementos se convirtieron en módulos. Ya no se admite la creación de nuevos complementos.
Ubicaciones de módulo predeterminadas
PowerShell almacena módulos en las siguientes ubicaciones predeterminadas:
- En Windows
- Ámbito de todos los usuarios:
$env:ProgramFiles\PowerShell\Modules - Ámbito de usuario actual:
$HOME\Documents\PowerShell\Modules - Módulos enviados con PowerShell:
$PSHOME\Modules
- Ámbito de todos los usuarios:
- En Linux y macOS
- Ámbito de todos los usuarios:
/usr/local/share/powershell/Modules - Ámbito de usuario actual:
$HOME/.local/share/powershell/Modules - Módulos enviados con PowerShell:
$PSHOME/Modules
- Ámbito de todos los usuarios:
De forma predeterminada, la Modules carpeta del usuario actual no existe. Si instaló un módulo en el CurrentUser ámbito mediante Install-Module o Install-PSResource, esos cmdlets crean la Modules carpeta para el usuario actual. Si la carpeta no existe, puede crearla manualmente.
Use el siguiente comando para crear una Modules carpeta para el usuario actual:
$folder = New-Item -Type Directory -Path $HOME\Documents\PowerShell\Modules
Estas ubicaciones se incluyen automáticamente en la variable de $env:PSModulePath entorno. Para obtener más información sobre las ubicaciones de módulo predeterminadas, consulte about_PSModulePath.
Carga automática de módulos
La primera vez que ejecute un comando desde un módulo instalado, PowerShell importa (carga) automáticamente ese módulo. El módulo debe almacenarse en las ubicaciones especificadas en la variable de $env:PSModulePath entorno.
La carga automática de módulos permite usar comandos en un módulo sin ninguna configuración de configuración o perfil. Cada uno de los ejemplos siguientes hace que el módulo CimCmdlets , que contiene Get-CimInstance, se importe en la sesión.
Ejecutar el comando
Get-CimInstance Win32_OperatingSystemObtener el comando
Get-Command Get-CimInstanceObtener ayuda para el comando
Get-Help Get-CimInstance
Cuando se usa Get-Command con un carácter comodín (*), PowerShell no importa ningún módulo. Puede usar caracteres comodín para la detección de comandos sin cargar módulos que es posible que no necesite en la sesión.
Importación manual de un módulo
La importación manual de un módulo es necesaria cuando un módulo no está instalado en las ubicaciones especificadas por la $env:PSModulePath variable de entorno, o cuando el módulo se proporciona como un .dll archivo o .psm1 independiente, en lugar de un módulo empaquetado.
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 WSMan: unidad, 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.
Es posible que también desee cambiar cómo se importa el módulo en la sesión. Por ejemplo, el parámetro Prefix de Import-Module agrega un prefijo distintivo a la parte de nombre de los cmdlets importados desde el módulo. El parámetro NoClobber impide que el módulo agregue comandos que ocultarían o reemplazarían los comandos existentes en la sesión. Para obtener más información, consulte Administración de conflictos de nombres.
En el ejemplo siguiente se importa el módulo BitsTransfer a la sesión actual.
Import-Module BitsTransfer
Para importar un módulo que no está en $env:PSModulePath, use la ruta de acceso completa a la carpeta del módulo. 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á incluido en una carpeta de módulos, use 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.
Importación de un módulo al principio de 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.
Instalación de un módulo publicado
Un módulo publicado es un módulo que está disponible en un repositorio registrado, como el Galería de PowerShell. Los módulos PowerShellGet y Microsoft.PowerShell.PSResourceGet proporcionan cmdlets para buscar, instalar y publicar módulos de PowerShell en un repositorio registrado.
El módulo PowerShellGet se incluye con PowerShell 5.0 y versiones posteriores. El módulo Microsoft.PowerShell.PSResourceGet se incluye con PowerShell 7.4 y versiones posteriores y es el administrador de paquetes preferido para PowerShell. Microsoft.PowerShell.PSResourceGet se puede instalar, en paralelo con PowerShellGet, en versiones anteriores de PowerShell. Use el Install-Module cmdlet o Install-PSResource para instalar módulos desde el Galería de PowerShell.
Get-Command Install-Module, Install-PSResource
CommandType Name Version Source
----------- ---- ------- ------
Function Install-Module 2.9.0 PowerShellGet
Cmdlet Install-PSResource 1.0.0 Microsoft.PowerShell.PSResourceGet
Para más información, consulte Introducción a PowerShellGet.
Instalación manual de un módulo
Puede instalar manualmente un módulo copiando el contenido del módulo desde otra carpeta. Esa carpeta puede estar en otra ubicación en el equipo local o instalarse en otra máquina. Para instalar un módulo manualmente, copie toda la carpeta del módulo en una nueva ubicación incluida en $env:PSModulePath.
En PowerShell, use el Copy-Item cmdlet . Por ejemplo, ejecute el siguiente comando para copiar la MyModule carpeta desde C:\PSTest:
$modulePath = $HOME\Documents\PowerShell\Modules\MyModule
Copy-Item -Path C:\PSTest\MyModule\* -Destination $modulePath -Recurse
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.
Búsqueda de módulos instalados
El Get-Module cmdlet obtiene los módulos de PowerShell que se cargan en la sesión actual de PowerShell.
Get-Module
Los módulos enumerados pueden incluir módulos importados desde cualquier ubicación, no solo desde $env:PSModulePath.
Use el siguiente comando para enumerar los módulos instalados en $env:PSModulePath:
Get-Module -ListAvailable
Este comando obtiene todos los módulos instalados en $env:PSModulePath, no solo los módulos que se importan en la sesión actual. Este comando no enumera los módulos instalados en otras ubicaciones.
Para obtener más información, consulte Get-Module.
Enumeración de los comandos de 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 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 Get-Command cmdlet, consulte Get-Command.
Quitar un módulo
Al quitar un módulo, se eliminan de la sesión los comandos que el módulo agregó. 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. Quitar un módulo no desinstala el módulo. Para obtener más información, consulte Remove-Module.
Los comandos se pueden agregar 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 de la sesión, use los siguientes comandos para determinar qué módulo desea quitar.
Por ejemplo, use el siguiente comando para buscar el origen de los Get-Date cmdlets y Get-Help :
Get-Command Get-Date, Get-Help -All |
Select-Object -Property Name, CommandType, Module ,PSSnapIn
La salida siguiente muestra que el Get-Help cmdlet está en el complemento Microsoft.PowerShell.Core . Este complemento no se puede quitar de la sesión.
Name CommandType Module PSSnapIn
---- ----------- ------ --------
Get-Date Function
Get-Date Cmdlet Microsoft.PowerShell.Utility
Get-Help Cmdlet Microsoft.PowerShell.Core
Hay dos orígenes para Get-Date. Una es una función y la otra es un cmdlet en el módulo Microsoft.PowerShell.Utility . Puede quitar el módulo mediante Remove-Module. Para quitar la función, puede eliminarla de la Function: unidad.
Remove-Item Function:Get-Date
Para obtener más información sobre la Function: unidad, consulte about_Function_Provider.
Administrar 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.
Import-Module puede agregar comandos que oculten y reemplacen comandos en la sesión actual. Los conflictos de nombres pueden ocultar o reemplazar los comandos. El reemplazo de comandos se produce cuando el módulo importado contiene un comando con el mismo nombre que un comando existente en la sesión. El comando recién importado tiene prioridad sobre el comando existente.
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.
Puede ejecutar un comando oculto o reemplazado si califica el nombre del comando. Para calificar el nombre del comando, agregue el nombre del módulo que contiene la versión del comando que desea. Por ejemplo:
Microsoft.PowerShell.Utility\Get-Date
La ejecución Get-Date con el prefijo del nombre del módulo garantiza que ejecute la versión desde el módulo Microsoft.PowerShell.Utility .
Para detectar conflictos de nombres, use el parámetro All del Get-Command cmdlet . De forma predeterminada, Get-Command obtiene solo 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 comandos. El valor del parámetro Prefix tiene prioridad sobre el valor de DefaultCommandPrefix.
