Compartir a través de

Instalación de un módulo de PowerShell

  • Artículo

Después de crear el módulo de PowerShell, es probable que quiera instalar el módulo en un sistema para que usted u otros usuarios puedan usarlo. Por lo general, esto consiste en copiar los archivos del módulo (es decir, el .psm1o el ensamblado binario, el manifiesto del módulo y cualquier otro archivo asociado) en un directorio de ese equipo. Para un proyecto muy pequeño, esto puede ser tan sencillo como copiar y pegar los archivos con el Explorador de Windows en un solo equipo remoto; sin embargo, en el caso de soluciones más grandes, es posible que desee usar un proceso de instalación más sofisticado. Independientemente de cómo obtenga el módulo en el sistema, PowerShell puede usar una serie de técnicas que permitirán a los usuarios encontrar y usar los módulos. Por lo tanto, el problema principal para la instalación es asegurarse de que PowerShell podrá encontrar el 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 cree para su propio uso, los módulos que obtenga de otras partes y los módulos que distribuya a otros usuarios.

Instalación de módulos en PSModulePath

Siempre que sea posible, instale todos los módulos en una ruta de acceso que aparece en la variable de entorno PSModulePath o agregue la ruta de acceso del módulo al valor de la variable de entorno de 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 de contiene los siguientes directorios del módulo de usuario y del sistema, pero puede agregar al valor y editarlo.

  • $PSHOME\Modules (%windir%\System32\WindowsPowerShell\v1.0\Modules)

    Advertencia

    Esta ubicación está reservada para los módulos que se envían con Windows. No instale módulos en esta ubicación.

  • $HOME\Documents\WindowsPowerShell\Modules (%HOMEDRIVE%%HOMEPATH%\Documents\WindowsPowerShell\Modules)

  • $Env:ProgramFiles\WindowsPowerShell\Modules (%ProgramFiles%\WindowsPowerShell\Modules)

    Para obtener el valor de la variable de entorno PSModulePath , use cualquiera de los siguientes comandos.

    $Env:PSModulePath
[Environment]::GetEnvironmentVariable("PSModulePath")

    Para agregar una ruta de acceso de módulo al valor de la PSModulePath valor de la variable de entorno, use el siguiente formato de comando. Este formato usa el método setEnvironmentVariable de la clase System.Environment para realizar un cambio independiente de sesión en la variable de entorno de 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)

    Importante

    Una vez que haya agregado la ruta de acceso a PSModulePath, debe difundir un mensaje de entorno sobre el cambio. La difusió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 del producto envíe un mensaje de WM_SETTINGCHANGE con lParam establecido en la cadena "Entorno". Asegúrese de enviar el mensaje después de que el código de instalación del módulo se haya actualizado PSModulePath.

Usar 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 un formato correcto, Windows PowerShell no lo reconoce como módulo.

El "nombre base" de un archivo es el nombre sin la extensión de nombre de 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 de 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 la instalación incorrecta

Si el módulo no está bien formado y su ubicación no se incluye en el valor de la PSModulePath variable de entorno, las características de detección básicas de Windows PowerShell, como las siguientes, no funcionan.

  • La característica Carga automática del módulo no puede importar el módulo automáticamente.

  • El parámetro ListAvailable del cmdlet Get-Module no encuentra el módulo.

  • El cmdlet import-Module no encuentra el módulo. Para importar el módulo, debe proporcionar la ruta de acceso completa al archivo del módulo raíz o al archivo de manifiesto del módulo.

    Las características adicionales, como las siguientes, no funcionan a menos que el módulo se importe en la sesión. En los módulos bien formados de la variable de entorno PSModulePath, estas características funcionan incluso cuando el módulo no se importa en la sesión.

  • El cmdlet Get-Command no encuentra comandos en el módulo.

  • Los cmdlets y Save-Help Update-Help no pueden actualizar ni guardar ayuda para el módulo.

  • El cmdlet Show-Command no puede encontrar y mostrar los comandos en el módulo.

    Faltan los comandos del módulo en la ventana Show-Command del entorno de scripting integrado (ISE) de Windows PowerShell.

Dónde instalar módulos

En esta sección se explica dónde se encuentra en el sistema de archivos para instalar módulos de Windows PowerShell. La ubicación depende de cómo se use el módulo.

Instalación de módulos para un usuario específico

Si crea su propio módulo o obtiene un módulo de otra entidad, como un sitio web de la comunidad de Windows PowerShell, y desea que el módulo esté disponible solo para su cuenta de usuario, instale el módulo en el directorio Módulos específicos del usuario.

$HOME\Documents\WindowsPowerShell\Modules\<Module Folder>\<Module Files>

El directorio Modules 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 del equipo, instale el módulo en la ubicación Archivos de programa.

$Env:ProgramFiles\WindowsPowerShell\Modules\<Module Folder>\<Module Files>

Nota:

La ubicación 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 archivos de programa (%ProgramFiles%\WindowsPowerShell\Modules) y agregar esta ruta de acceso a la variable de entorno PSModulePath, como se ha descrito anteriormente.

Instalación de módulos en un directorio de productos

Si va a distribuir el módulo a otras partes, use la ubicación predeterminada Archivos de programa descrita anteriormente o cree su propio subdirectorio específico de la empresa o específico del producto del directorio %ProgramFiles%.

Por ejemplo, Fabrikam Technologies, una empresa ficticia, está enviando un módulo de Windows PowerShell para su producto fabrikam Manager. Su instalador de módulo crea un subdirectorio Modules 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 características de detección de módulos de Windows PowerShell para buscar 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 Common Files

Si varios componentes de un producto o varias versiones de un producto usan un módulo, instale el módulo en un subdirectorio específico del módulo del subdirectorio %ProgramFiles%subdirectorio \Common Files\Modules.

En el ejemplo siguiente, 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 Modules.

C:\Program Files
  Common Files
    Modules
      Fabrikam
        Fabrikam.psd1 (module manifest)
        Fabrikam.dll (module assembly)

A continuación, el instalador garantiza que el valor de la variable de entorno de PSModulePath incluye la ruta de acceso del subdirectorio Common Files\Modules.

$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, use el procedimiento siguiente.

  1. Cree un directorio para cada versión del módulo. Incluya el número de versión en el nombre del directorio.
  2. Cree un manifiesto de módulo para cada versión del módulo. En el valor de la clave ModuleVersion en el manifiesto, escriba 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.
  3. Agregue la ruta de acceso de la carpeta raíz del módulo al valor de la variable de entorno de PSModulePath, como se muestra en los ejemplos siguientes.

Para importar una versión determinada 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 de directorios 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 las dos rutas de acceso del 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)

Una vez completados estos pasos, el parámetro ListAvailable del cmdlet Get-Module obtiene ambos módulos de Fabrikam. Para importar un módulo determinado, use los parámetros MinimumVersion o RequiredVersion del cmdlet Import-Module.

Si ambos módulos se importan en la misma sesión y los módulos contienen cmdlets con los mismos nombres, los cmdlets que se importan por última vez son efectivos en la sesión.

Control de conflictos de nombres de comando

Los conflictos de nombres de comando pueden producirse cuando los comandos que exporta un módulo tienen el mismo nombre que los comandos de 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ó a la sesión más recientemente. 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, escriba el comando con el nombre del módulo, como:

Microsoft.PowerShell.Utility\Get-Date

Para evitar conflictos de nombres, los autores de módulos pueden usar la clave DefaultCommandPrefix del manifiesto del módulo para especificar un prefijo de nombre para todos los comandos exportados desde el módulo.

Los usuarios pueden usar el parámetro prefijo del cmdlet Import-Module para usar un prefijo alternativo. El valor del parámetro prefijo tiene prioridad sobre el valor de la clave DefaultCommandPrefix.

Compatibilidad con rutas de acceso en sistemas que no son windows

Las plataformas que no son Windows usan el carácter de dos puntos (:) como separador de ruta de acceso y un carácter de barra diagonal (/) como separador de directorios. La clase [System.IO.Path] tiene miembros estáticos que se pueden usar para que el código funcione en cualquier plataforma:

  • [System.IO.Path]::PathSeparator: devuelve el carácter usado para separar las rutas de acceso de una variable de entorno PATH para la plataforma host.
  • [System.IO.Path]::DirectorySeparatorChar: devuelve el carácter usado para separar los nombres de directorio con una ruta de acceso para la plataforma host.

Use estas propiedades estáticas para colocar los caracteres ; y \ al construir cadenas de ruta de acceso.

Véase también

about_Command_Precedence

escribir un módulo de Windows PowerShell