about_Modules

Se aplica a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

TEMA

about_Modules

DESCRIPCIÓN BREVE

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

DESCRIPCIÓN LARGA

Un módulo es un paquete que contiene comandos de Windows 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 Windows PowerShell y usarlos como los comandos integrados.

Este tema explica cómo usar módulos de Windows PowerShell. Para obtener información sobre cómo escribir módulos de Windows PowerShell, vea "Escribir un módulo de Windows PowerShell" en el vínculo https://go.microsoft.com/fwlink/?LinkId=144916 de MSDN Library (Microsoft Developer Network).

¿QUÉ ES UN MÓDULO?

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

NOVEDADES EN LOS MÓDULOS: CARGA AUTOMÁTICA DE MÓDULOS

A partir de Windows PowerShell 3.0, Windows PowerShell importa módulos automáticamente la primera vez que se ejecuta un comando de un módulo instalado. Ahora puede ejecutar 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 cmdlet Get-Command ahora obtiene todos los comandos de todos los módulos instalados, incluso si todavía no están en la sesión, para que pueda encontrar un comando y ejecutarlo sin importarlo.

Cualquiera de los siguientes comandos importará un módulo en la sesión.

        #Run the command
        Get-Mailbox –Identity Chris  

        #Get the command
        Get-Command Get-Mailbox

        #Get help for the command
        Get-Help Get-Mailbox

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

Solo se importan automáticamente los módulos que están almacenados en la ubicación especificada por la variable de entorno PSModulePath. Los módulos de otras ubicaciones deben importarse ejecutando el cmdlet Import-Module.

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

También puede ejecutar el comando Import-Module para importar un módulo y usar la variable $PSModuleAutoloadingPreference 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 UTILIZAR UN MÓDULO

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

1. Instale el módulo. (Esto a menudo se hace automáticamente).

2. Busque los comandos que agregó el módulo.

3. 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, deberá instalarlo en el equipo para poder usarlo en Windows PowerShell.

La mayoría de los módulos se instalan automáticamente. Windows PowerShell incluye varios módulos preinstalados, en ocasiones denominados módulos "principales". En equipos basados en Windows, si las características incluidas con el sistema operativo tienen cmdlets para administrarlas, esos módulos están preinstalados. Al instalar una característica de Windows, por ejemplo mediante el Asistente para agregar roles y características en el Administrador del servidor o mediante el cuadro de diálogo Activar o desactivar las características de Windows del Panel de control, se instalan todos los módulos de Windows 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.

Para instalar una carpeta de módulo:

1. Cree un directorio Modules para el usuario actual si no existe uno.

Para crear un directorio Modules, escriba:

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

2. 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 Windows PowerShell.

En Windows PowerShell, use el cmdlet Copy-Item. Por ejemplo, para copiar la carpeta MyModule desde C:\ps-test\MyModule en 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 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 de módulo, consulte la sección "UBICACIONES DE LOS MÓDULOS Y DE LOS RECURSOS DE DSC Y PSMODULEPATH".

CÓMO ENCONTRAR LOS 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 encontrar los módulos que ya se importaron a la sesión, escriba en el símbolo del sistema de Windows PowerShell:

         Get-Module

Para obtener más información acerca del cmdlet Get-Module, vea Get-Module.

CÓMO ENCONTRAR LOS COMANDOS DE UN MÓDULO

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

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

        Get-Command -Module <module-name>

Por ejemplo, para encontrar los comandos del módulo BitsTransfer, escriba:

        Get-Command -Module BitsTransfer

Para obtener más información acerca del cmdlet Get-Command, 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 cmdlet Get-Help mostrará los temas de ayuda. Use el mismo formato de comando Get-Help que usaría para obtener ayuda de cualquier comando de Windows PowerShell.

A partir de Windows PowerShell 3.0, puede descargar archivos de ayuda para un módulo y actualizaciones de dichos archivos, de modo 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 los comandos de un módulo, escriba:

        Get-Help <command-name> -Online 

Para descargar e instalar los archivos de ayuda para 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:PSModulePath), o cuando el módulo es un archivo, como un archivo .dll o .psm1, en lugar de un módulo típico entregado como una carpeta.

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

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

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 comando siguiente 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 del directorio C:\ps-test 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 del 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, vea Import-Module.

CÓMO IMPORTAR UN MÓDULO EN CADA SESIÓN

El comando Import-Module importa los módulos en la sesión actual de Windows PowerShell. Este comando afecta solo a la sesión actual.

Para importar un módulo en cada sesión de Windows PowerShell que inicie, agregue el comando Import-Module a su perfil de Windows PowerShell.

Para obtener más información acerca de 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 formato de comando siguiente.

        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 acerca del cmdlet Remove-Module, vea Remove-Module.

UBICACIONES DE LOS MÓDULOS Y DE LOS RECURSOS DE DSC Y PSMODULEPATH

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

Sistema:

Los módulos del sistema $pshome\Modules (%windir%\System32\WindowsPowerShell\v1.0\Modules) son los que se incluyen con Windows y Windows PowerShell.

A partir de Windows PowerShell 4.0, cuando se introdujo Configuración de estado deseado (DSC) de Windows PowerShell, los recursos de DSC que se incluyen con Windows PowerShell también se almacenan en $pshome\Modules, en la carpeta $pshome\Modules\PSDesiredStateConfiguration\DSCResources.

Usuario actual:

$home\Documents\WindowsPowerShell\Modules (%UserProfile%\Documents\WindowsPowerShell\Modules)

O bien,

$home\My Documents\WindowsPowerShell\Modules (%UserProfile%\My Documents\WindowsPowerShell\Modules) Esta es la ubicación de los módulos agregados por el usuario antes de Windows PowerShell 4.0.

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

Nota:

Para agregar o cambiar archivos en el directorio %Windir%\System32, inicie Windows PowerShell con la opción "Ejecutar como administrador".

Puede cambiar las ubicaciones de módulo predeterminadas en el sistema cambiando el valor de la variable de entorno PSModulePath ($Env:PSModulePath). La variable de entorno PSModulePath se basa 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 directorio "C:\ps-test\Modules", escriba:

        $env:psmodulepath + ";c:\ps-test\Modules"

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

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

Asimismo, para conservar el cambio, puede utilizar 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, consulte 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.

-- Ocultar. 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ó.

-- Reemplazar. 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 puede 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, utilice el parámetro All del cmdlet Get-Command. A partir de Windows PowerShell 3.0, Get-Command solo obtiene los comandos que se ejecutan cuando se escribe el nombre de comando. El parámetro All obtiene todos los comandos con el nombre específico en 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.

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

Los autores de módulos pueden evitar los conflictos de nombres con 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 prioridad de comandos de Windows 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, Windows 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 prioridad e instrucciones para ejecutar comandos ocultos, vea about_Command_Precedence.

MÓDULOS Y COMPLEMENTOS

Puede agregar comandos a la sesión a partir de módulos y complementos. Los módulos pueden agregar todos los tipos de comandos, incluidos cmdlets, proveedores, funciones y elementos como variables, alias y unidades de Windows 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 formato de comando siguiente:

        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, pssnapin, module

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

ERRORES Y ADVERTENCIAS RELACIONADOS CON EL MÓDULO

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

ADVERTENCIA: Algunos nombres de comando importados incluyen verbos no aprobados que podrían dificultar su reconocimiento. 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. Aun así se importa el módulo completo, incluyendo los comandos disconformes. 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, utilice el parámetro DisableNameChecking del cmdlet Import-Module.

MÓDULOS Y COMPLEMENTOS INTEGRADOS

En Windows PowerShell 2.0 y en programas de host de estilo antiguo de Windows PowerShell 3.0 y versiones posteriores, los comandos principales que vienen instalados con Windows PowerShell están empaquetados en complementos que se agregan automáticamente a cada sesión de Windows PowerShell.

A partir de Windows PowerShell 3.0, en programas de host de estilo más reciente (los que implementan la API de estado de sesión inicial InitialSessionState.CreateDefault2), los comandos principales están empaquetados en módulos. El valor predeterminado es Microsoft.PowerShell.Core, que siempre es un complemento.

El complemento Microsoft.PowerShell.Core se agrega a todas las sesiones 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 cmdlet New-PSSession, son sesiones de estilo antiguo en las que los comandos integrados están empaquetados en complementos.

Los siguientes módulos (o complementos) vienen instalados con Windows PowerShell.

        Microsoft.PowerShell.Core
        Microsoft.PowerShell.Diagnostics
        Microsoft.PowerShell.Host
        Microsoft.PowerShell.Management
        Microsoft.PowerShell.ScheduledJob
        Microsoft.PowerShell.Security
        Microsoft.PowerShell.Utility
        Microsoft.WSMan.Management
        PSDesiredStateConfiguration
        PSWorkflow
        PSWorkflowUtility
        ISE

EVENTOS DEL MÓDULO DE REGISTRO

A partir de Windows PowerShell 3.0, puede registrar eventos de ejecución para los cmdlets y las funciones en módulos y complementos de Windows PowerShell estableciendo en $True la propiedad LogPipelineExecutionDetails de los módulos y los complementos. 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 Windows PowerShell. Para obtener más información, vea about_EventLogs (https://go.microsoft.com/fwlink/?LinkID=113224) y about_Group_Policy_Settings (https://go.microsoft.com/fwlink/?LinkID=251696).

VEA TAMBIÉN

about_Command_Precedence

about_DesiredStateConfiguration

about_EventLogs

about_Group_Policy_Settings

about_PSSnapins

Get-Command

Get-Help

Get-Module

Import-Module

Remove-Module