Instalación de un módulo PowerShell
Una vez que haya creado su módulo de PowerShell, es probable que desee instalarlo en un sistema para que usted u otras personas puedan usarlo. En términos generales, esto consiste en copiar los archivos del módulo (es decir, el .psm1 o el ensamblado binario, el manifiesto del módulo y cualquier otro archivo asociado) en un directorio de esa computadora. Para un proyecto muy pequeño, esto puede ser tan sencillo como copiar y pegar los archivos con el Explorador de Windows en una única computadora remota; sin embargo, para soluciones más grandes es posible que desee utilizar un proceso de instalación más sofisticado. Independientemente de cómo introduzca su módulo en el sistema, PowerShell puede utilizar una serie de técnicas que permitirán a los usuarios encontrar y utilizar sus módulos. Por lo tanto, el principal problema para la instalación es garantizar que PowerShell pueda encontrar su módulo. Para obtener más información, consulte Importación de un módulo de PowerShell.
Reglas para instalar módulos
La siguiente información pertenece a todos los módulos, incluidos los módulos que usted crea para su propio uso, los módulos que obtiene de otras partes y los módulos que distribuye a otros.
Instalar módulos en PSModulePath
Siempre que sea posible, instale todos los módulos en una ruta que aparezca en la variable de entorno PSModulePath o agregue la ruta del módulo al valor de la variable de entorno PSModulePath.
La variable de entorno PSModulePath ($Env:PSModulePath) contiene las ubicaciones de los módulos de Windows PowerShell. Los cmdlets se basan en el valor de esta variable de entorno para buscar módulos.
De forma predeterminada, el valor de la variable de entorno PSModulePath contiene los siguientes directorios de módulos de sistema y de usuario, pero puede agregar y editar el valor.
$HOME\Documentos\WindowsPowerShell\Modules (%HOMEDRIVE%%HOMEPATH%\Documentos\WindowsPowerShell\Modules)
$Env:ProgramFiles\WindowsPowerShell\Modules (%ProgramFiles%\WindowsPowerShell\Modules)
Para obtener el valor de la variable de entorno PSModulePath, utilice cualquiera de los siguientes comandos.
$Env:PSModulePath
[Environment]::GetEnvironmentVariable("PSModulePath")
Para agregar una ruta de módulo al valor de la variable de entorno PSModulePath, utilice el siguiente formato de comando. Este formato utiliza el método SetEnvironmentVariable de la clase System.Environment para realizar un cambio independiente de la sesión en la variable de entorno PSModulePath.
#Save the current value in the $p variable.
$p = [Environment]::GetEnvironmentVariable("PSModulePath")
#Add the new path to the $p variable. Begin with a semi-colon separator.
$p += ";C:\Program Files (x86)\MyCompany\Modules\"
#Add the paths in $p to the PSModulePath value.
[Environment]::SetEnvironmentVariable("PSModulePath",$p)
es importante
Una vez que haya agregado la ruta a PSModulePath, debe transmitir un mensaje de entorno sobre el cambio. La transmisión del cambio permite que otras aplicaciones, como el shell, recojan el cambio. Para difundir el cambio, haga que el código de instalación de su producto envíe un mensaje WM_SETTINGCHANGE con lParam establecido en la cadena "Environment". Asegúrese de enviar el mensaje después de que el código de instalación de su módulo haya actualizado PSModulePath.
Utilice el nombre correcto del directorio del módulo
Un módulo bien formado es un módulo que se almacena en un directorio que tiene el mismo nombre que el nombre base de al menos un archivo en el directorio del módulo. Si un módulo no tiene el formato correcto, Windows PowerShell no lo reconoce como módulo.
El "nombre base" de un archivo es el nombre sin la extensión del nombre del archivo. En un módulo bien formado, el nombre del directorio que contiene los archivos del módulo debe coincidir con el nombre base de al menos un archivo del módulo.
Por ejemplo, en el módulo Fabrikam de ejemplo, el directorio que contiene los archivos del módulo se denomina "Fabrikam" y al menos un archivo tiene el nombre base "Fabrikam". En este caso, tanto Fabrikam.psd1 como Fabrikam.dll tienen el nombre base "Fabrikam".
C:\Program Files
Fabrikam Technologies
Fabrikam Manager
Modules
Fabrikam
Fabrikam.psd1 (module manifest)
Fabrikam.dll (module assembly)
Efecto de una instalación incorrecta
Si el módulo no está bien formado y su ubicación no está incluida en el valor de la variable de entorno PSModulePath, las funciones de descubrimiento básicas de Windows PowerShell, como las siguientes, no funcionan.
La función de carga automática del módulo no puede importar el módulo automáticamente.
El parámetro ListAvailable del cmdlet Get-Module no puede encontrar el módulo.
El cmdlet Import-Module no puede encontrar el módulo. Para importar el módulo, debe proporcionar la ruta completa al archivo del módulo raíz o al archivo de manifiesto del módulo.
Las funciones adicionales, como las siguientes, no funcionan a menos que el módulo se importe a la sesión. En módulos bien formados en la variable de entorno PSModulePath, estas características funcionan incluso cuando el módulo no se importa a la sesión.
El cmdlet Get-Command no puede encontrar comandos en el módulo.
Los cmdlets Update-Help y Save-Help no pueden actualizar ni guardar la ayuda para el módulo.
El cmdlet Show-Command no puede encontrar ni mostrar los comandos en el módulo.
Los comandos del módulo faltan en la ventana Show-Command del entorno de scripting integrado (ISE) de Windows PowerShell.
Dónde instalar los módulos
Esta sección explica en qué parte del sistema de archivos instalar los módulos de Windows PowerShell. La ubicación depende de cómo se utiliza el módulo.
Instalación de módulos para un usuario específico
Si crea su propio módulo u obtiene un módulo de otra parte, como un sitio web comunitario de Windows PowerShell, y desea que el módulo esté disponible solo para su cuenta de usuario, instálelo en su directorio de Módulos específico del usuario.
$HOME\Documents\WindowsPowerShell\Modules\<Module Folder>\<Module Files>
El directorio de módulos específico del usuario se agrega al valor de la variable de entorno PSModulePath de forma predeterminada.
Instalación de módulos para todos los usuarios en archivos de programa
Si desea que un módulo esté disponible para todas las cuentas de usuario en la computadora, instálelo en la ubicación de Archivos de programa.
$Env:ProgramFiles\WindowsPowerShell\Modules\<Module Folder>\<Module Files>
Nota
La ubicación de Archivos de programa se agrega al valor de la variable de entorno PSModulePath de forma predeterminada en Windows PowerShell 4.0 y versiones posteriores. Para versiones anteriores de Windows PowerShell, puede crear manualmente la ubicación de los Archivos de programa (%ProgramFiles%\WindowsPowerShell\Modules) y agregar esta ruta a su variable de entorno PSModulePath como se describe anteriormente.
Instalación de módulos en un directorio de productos
Si está distribuyendo el módulo a otras partes, utilice la ubicación predeterminada de Archivos de programa descrita anteriormente o cree su propio subdirectorio específico de la empresa o del producto del directorio %ProgramFiles%.
Por ejemplo, Fabrikam Technologies, una empresa ficticia, envía un módulo de Windows PowerShell para su producto Fabrikam Manager. Su instalador de módulos crea un subdirectorio Módulos en el subdirectorio del producto Fabrikam Manager.
C:\Program Files
Fabrikam Technologies
Fabrikam Manager
Modules
Fabrikam
Fabrikam.psd1 (module manifest)
Fabrikam.dll (module assembly)
Para habilitar las funciones de detección de módulos de Windows PowerShell para encontrar el módulo Fabrikam, el instalador del módulo Fabrikam agrega la ubicación del módulo al valor de la variable de entorno PSModulePath.
$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$p += ";C:\Program Files\Fabrikam Technologies\Fabrikam Manager\Modules\"
[Environment]::SetEnvironmentVariable("PSModulePath",$p)
Instalación de módulos en el directorio de archivos comunes
Si un módulo es utilizado por varios componentes de un producto o por varias versiones de un producto, instale el módulo en un subdirectorio específico del módulo del subdirectorio %ProgramFiles%\Common Files\Modules.
En el siguiente ejemplo, el módulo Fabrikam se instala en un subdirectorio Fabrikam del subdirectorio %ProgramFiles%\Common Files\Modules. Tenga en cuenta que cada módulo reside en su propio subdirectorio en el subdirectorio Módulos.
C:\Program Files
Common Files
Modules
Fabrikam
Fabrikam.psd1 (module manifest)
Fabrikam.dll (module assembly)
Luego, el instalador asegura que el valor de la variable de entorno PSModulePath incluye la ruta del subdirectorio de módulos de archivos comunes.
$m = $env:ProgramFiles + '\Common Files\Modules'
$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$q = $p -split ';'
if ($q -notContains $m) {
$q += ";$m"
}
$p = $q -join ';'
[Environment]::SetEnvironmentVariable("PSModulePath", $p)
Instalación de varias versiones de un módulo
Para instalar varias versiones del mismo módulo, utilice el siguiente procedimiento.
- Cree un directorio para cada versión del módulo. Incluya el número de versión en el nombre del directorio.
- Cree un manifiesto de módulo para cada versión del módulo. En el valor de la clave ModuleVersion en el manifiesto, ingrese el número de versión del módulo. Guarde el archivo de manifiesto (.psd1) en el directorio específico de la versión del módulo.
- Agregue la ruta de la carpeta raíz del módulo al valor de la variable de entorno PSModulePath, como se muestra en los siguientes ejemplos.
Para importar una versión particular del módulo, el usuario final puede usar los parámetros MinimumVersion o RequiredVersion del cmdlet Import-Module.
Por ejemplo, si el módulo Fabrikam está disponible en las versiones 8.0 y 9.0, la estructura del directorio del módulo Fabrikam podría parecerse a la siguiente.
C:\Program Files
Fabrikam Manager
Fabrikam8
Fabrikam
Fabrikam.psd1 (module manifest: ModuleVersion = "8.0")
Fabrikam.dll (module assembly)
Fabrikam9
Fabrikam
Fabrikam.psd1 (module manifest: ModuleVersion = "9.0")
Fabrikam.dll (module assembly)
El instalador agrega ambas rutas de módulo al valor de la variable de entorno PSModulePath.
$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$p += ";C:\Program Files\Fabrikam\Fabrikam8;C:\Program Files\Fabrikam\Fabrikam9"
[Environment]::SetEnvironmentVariable("PSModulePath",$p)
Cuando se completan estos pasos, el parámetro ListAvailable del cmdlet Get-Module obtiene ambos módulos de Fabrikam. Para importar un módulo en particular, use los parámetros MinimumVersion o RequiredVersion del cmdlet Import-Module.
Si ambos módulos se importan a la misma sesión y los módulos contienen cmdlets con los mismos nombres, los cmdlets que se importan en último lugar son efectivos en la sesión.
Manejo de conflictos de nombres de comandos
Pueden ocurrir conflictos de nombres de comandos cuando los comandos que exporta un módulo tienen el mismo nombre que los comandos en la sesión del usuario.
Cuando una sesión contiene dos comandos que tienen el mismo nombre, Windows PowerShell ejecuta el tipo de comando que tiene prioridad. Cuando una sesión contiene dos comandos que tienen el mismo nombre y el mismo tipo, Windows PowerShell ejecuta el comando que se agregó más recientemente a la sesión. Para ejecutar un comando que no se ejecuta de forma predeterminada, los usuarios pueden calificar el nombre del comando con el nombre del módulo.
Por ejemplo, si la sesión contiene una función Get-Date y el cmdlet Get-Date, Windows PowerShell ejecuta la función de forma predeterminada. Para ejecutar el cmdlet, anteponga el comando con el nombre del módulo, como por ejemplo:
Microsoft.PowerShell.Utility\Get-Date
Para evitar conflictos de nombres, los autores del módulo pueden usar la clave DefaultCommandPrefix en el manifiesto del módulo para especificar un prefijo de sustantivo para todos los comandos exportados desde el módulo.
Los usuarios pueden utilizar el parámetro Prefix del cmdlet Import-Module para utilizar un prefijo alternativo. El valor del parámetro Prefix tiene prioridad sobre el valor de la clave DefaultCommandPrefix.
Rutas de soporte en sistemas que no son Windows
Las plataformas que no son Windows utilizan el carácter de dos puntos (:) como separador de ruta y un carácter de barra diagonal (/) como separador de directorio. La clase [System.IO.Path] tiene miembros estáticos que pueden usarse para hacer que su código funcione en cualquier plataforma:
[System.IO.Path]::PathSeparator: devuelve el carácter utilizado para separar rutas en una variable de entorno PATH para la plataforma host[System.IO.Path]::DirectorySeparatorChar: devuelve el carácter utilizado para separar los nombres de directorio con una ruta para la plataforma host
Utilice estas propiedades estáticas en lugar de los caracteres ; y \ cuando esté construyendo cadenas de ruta.
Ver también
about_Command_Precedence
Escribir un módulo de Windows PowerShell