about_Modules

Artículo
03/18/2024

Descripción breve

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

Descripción larga

PowerShell es un lenguaje de scripting y un shell de comandos. El lenguaje se compone de palabras clave, que proporcionan la estructura y la lógica del procesamiento, y los comandos que realizan el trabajo. Los comandos de PowerShell se implementan como scripts, funciones o cmdlets.

Un módulo es una unidad reutilizable independiente que puede contener cmdlets, proveedores, funciones, variables y otros tipos de recursos que se pueden importar como una sola unidad.

PowerShell incluye un conjunto base de módulos. También puede instalar más módulos según sea necesario. De forma predeterminada, los módulos instalados se cargan automáticamente la primera vez que se usa un comando desde un módulo. Use la $PSModuleAutoloadingPreference variable para habilitar, deshabilitar y configurar la carga automática de módulos. Para obtener más información, consulte about_Preference_Variables.

Puede descargar o volver a cargar durante una sesión. Use el Remove-Module cmdlet para descargar un módulo de la sesión. Use el Import-Module cmdlet para cargar un módulo.

Los módulos se pueden crear como ensamblados de .NET compilados escritos en C#, o módulos basados en scripts escritos en PowerShell. 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.

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.

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. Microsoft.PowerShell.PSResourceGet es el nuevo administrador de paquetes preferido para PowerShell y se puede instalar 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

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

PowerShell incluye varios módulos preinstalados. En los equipos basados en Windows, muchas características de Windows incluyen módulos para administrar la característica. Esos módulos se instalan cuando se instala la característica. Otros módulos pueden aparecer en un programa de instalación o instalador que instala el módulo.

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

Copie toda la carpeta del módulo en la nueva carpeta creada. En PowerShell, use el Copy-Item cmdlet . Por ejemplo, ejecute el siguiente comando para copiar la MyModule carpeta de C:\PSTest a la carpeta que acaba de crear:

Copy-Item -Path C:\PSTest\MyModule -Destination $folder

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 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. Los módulos de otras ubicaciones deben importarse mediante el Import-Module cmdlet .

La carga automática de módulos permite usar comandos en un módulo sin ninguna configuración de configuración o perfil. No es necesario administrar módulos después de instalarlos en el equipo.

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_OperatingSystem
```
Obtener el comando
```
Get-Command Get-CimInstance
```
Obtener ayuda para el comando
```
Get-Help Get-CimInstance
```

Puede usar la lista de Get-Command cmdlets de los comandos de todos los módulos instalados, incluso si aún no están en la sesión. 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.

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.

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.

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.

Puede importar un módulo que esté instalado en $env:PSModulePath si especifica el nombre del módulo. 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 $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.

Búsqueda de módulos instalados

El Get-Module cmdlet obtiene los módulos de PowerShell que se han importado en la sesión.

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 reemplaza 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 que se haya ocultado 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.