Partilhar via

Import-Module

  • Referência
Módulo:
Microsoft.PowerShell.Core

Adiciona módulos à sessão atual.

Sintaxe

Import-Module
      [-Global]
      [-Prefix <String>]
      [-Name] <String[]>
      [-Function <String[]>]
      [-Cmdlet <String[]>]
      [-Variable <String[]>]
      [-Alias <String[]>]
      [-Force]
      [-SkipEditionCheck]
      [-PassThru]
      [-AsCustomObject]
      [-MinimumVersion <Version>]
      [-MaximumVersion <String>]
      [-RequiredVersion <Version>]
      [-ArgumentList <Object[]>]
      [-DisableNameChecking]
      [-NoClobber]
      [-Scope <String>] 
      [<CommonParameters>]
Import-Module
      [-Global]
      [-Prefix <String>]
      [-Name] <String[]>
      [-Function <String[]>]
      [-Cmdlet <String[]>]
      [-Variable <String[]>]
      [-Alias <String[]>]
      [-Force]
      [-SkipEditionCheck]
      [-PassThru]
      [-AsCustomObject]
      [-MinimumVersion <Version>]
      [-MaximumVersion <String>]
      [-RequiredVersion <Version>]
      [-ArgumentList <Object[]>]
      [-DisableNameChecking]
      [-NoClobber]
      [-Scope <String>]
      -PSSession <PSSession> 
      [<CommonParameters>]
Import-Module
      [-Global]
      [-Prefix <String>]
      [-Name] <String[]>
      [-Function <String[]>]
      [-Cmdlet <String[]>]
      [-Variable <String[]>]
      [-Alias <String[]>]
      [-Force]
      [-SkipEditionCheck]
      [-PassThru]
      [-AsCustomObject]
      [-MinimumVersion <Version>]
      [-MaximumVersion <String>]
      [-RequiredVersion <Version>]
      [-ArgumentList <Object[]>]
      [-DisableNameChecking]
      [-NoClobber]
      [-Scope <String>]
      -CimSession <CimSession>
      [-CimResourceUri <Uri>]
      [-CimNamespace <String>]
      [<CommonParameters>]
Import-Module
      [-Name] <string[]>
      -UseWindowsPowerShell
      [-Global]
      [-Prefix <string>]
      [-Function <string[]>]
      [-Cmdlet <string[]>]
      [-Variable <string[]>]
      [-Alias <string[]>]
      [-Force]
      [-PassThru]
      [-AsCustomObject]
      [-MinimumVersion <version>]
      [-MaximumVersion <string>]
      [-RequiredVersion <version>]
      [-ArgumentList <Object[]>]
      [-DisableNameChecking]
      [-NoClobber]
      [-Scope <string>]
      [<CommonParameters>]
Import-Module
      [-Global]
      [-Prefix <String>]
      [-FullyQualifiedName] <ModuleSpecification[]>
      [-Function <String[]>]
      [-Cmdlet <String[]>]
      [-Variable <String[]>]
      [-Alias <String[]>]
      [-Force]
      [-SkipEditionCheck]
      [-PassThru]
      [-AsCustomObject]
      [-ArgumentList <Object[]>]
      [-DisableNameChecking]
      [-NoClobber]
      [-Scope <String>] 
      [<CommonParameters>]
Import-Module
      [-Global]
      [-Prefix <String>]
      [-FullyQualifiedName] <ModuleSpecification[]>
      [-Function <String[]>]
      [-Cmdlet <String[]>]
      [-Variable <String[]>]
      [-Alias <String[]>]
      [-Force]
      [-SkipEditionCheck]
      [-PassThru]
      [-AsCustomObject]
      [-ArgumentList <Object[]>]
      [-DisableNameChecking]
      [-NoClobber]
      [-Scope <String>]
      -PSSession <PSSession> 
      [<CommonParameters>]
Import-Module
      [-FullyQualifiedName] <ModuleSpecification[]>
      -UseWindowsPowerShell
      [-Global]
      [-Prefix <string>]
      [-Function <string[]>]
      [-Cmdlet <string[]>]
      [-Variable <string[]>]
      [-Alias <string[]>]
      [-Force]
      [-PassThru]
      [-AsCustomObject]
      [-ArgumentList <Object[]>]
      [-DisableNameChecking]
      [-NoClobber]
      [-Scope <string>]
      [<CommonParameters>]
Import-Module
      [-Global]
      [-Prefix <String>]
      [-Assembly] <Assembly[]>
      [-Function <String[]>]
      [-Cmdlet <String[]>]
      [-Variable <String[]>]
      [-Alias <String[]>]
      [-Force]
      [-SkipEditionCheck]
      [-PassThru]
      [-AsCustomObject]
      [-ArgumentList <Object[]>]
      [-DisableNameChecking]
      [-NoClobber]
      [-Scope <String>] 
      [<CommonParameters>]
Import-Module
      [-Global]
      [-Prefix <String>]
      [-Function <String[]>]
      [-Cmdlet <String[]>]
      [-Variable <String[]>]
      [-Alias <String[]>]
      [-Force]
      [-SkipEditionCheck]
      [-PassThru]
      [-AsCustomObject]
      [-ModuleInfo] <PSModuleInfo[]>
      [-ArgumentList <Object[]>]
      [-DisableNameChecking]
      [-NoClobber]
      [-Scope <String>] 
      [<CommonParameters>]

Description

O Import-Module cmdlet adiciona um ou mais módulos à sessão atual. A partir do PowerShell 3.0, os módulos instalados são importados automaticamente para a sessão quando você usa quaisquer comandos ou provedores no módulo. No entanto, você ainda pode usar o Import-Module comando para importar um módulo. Você pode desativar a importação automática de módulos usando a variável de $PSModuleAutoloadingPreference preferência. Para obter mais informações sobre a $PSModuleAutoloadingPreference variável, consulte about_Preference_Variables.

Um módulo é um pacote que contém membros que podem ser usados no PowerShell. Os membros incluem cmdlets, provedores, scripts, funções, variáveis e outras ferramentas e arquivos. Depois que um módulo é importado, você pode usar os membros do módulo em sua sessão. Para obter mais informações sobre módulos, consulte about_Modules.

Por padrão, Import-Module importa todos os membros que o módulo exporta, mas você pode usar os parâmetros Alias, Function, Cmdlet e Variable para restringir quais membros são importados. O parâmetro NoClobber impede Import-Module a importação de membros que tenham os mesmos nomes que os membros na sessão atual.

Import-Module Importa um módulo apenas para a sessão atual. Para importar o módulo para cada nova sessão, adicione um Import-Module comando ao seu perfil do PowerShell. Para obter mais informações sobre perfis, consulte about_Profiles.

Você pode gerenciar computadores remotos do Windows que tenham a comunicação remota do PowerShell habilitada criando uma PSSession no computador remoto. Em seguida, use o parâmetro PSSession de Import-Module para importar os módulos instalados no computador remoto. Quando você usa os comandos importados na sessão atual, os comandos são executados implicitamente no computador remoto.

A partir do Windows PowerShell 3.0, você pode usar Import-Module para importar módulos CIM (Common Information Model). Os módulos CIM definem cmdlets em arquivos CDXML (Cmdlet Definition XML). Esse recurso permite que você use cmdlets que são implementados em assemblies de código não gerenciados, como aqueles escritos em C++.

Para computadores remotos que não têm a comunicação remota do PowerShell habilitada, incluindo computadores que não estão executando o sistema operacional Windows, você pode usar o parâmetro CIMSession de Import-Module para importar módulos CIM do computador remoto. Os comandos importados são executados implicitamente no computador remoto. Um CIMSession é uma conexão com a Instrumentação de Gerenciamento do Windows (WMI) no computador remoto.

Exemplos

Exemplo 1: Importar os membros de um módulo para a sessão atual

Este exemplo importa os membros do módulo PSDiagnostics para a sessão atual.

Import-Module -Name PSDiagnostics

Exemplo 2: Importar todos os módulos especificados pelo caminho do módulo

Este exemplo importa todos os módulos disponíveis no caminho especificado pela $env:PSModulePath variável de ambiente para a sessão atual.

Get-Module -ListAvailable | Import-Module

Exemplo 3: Importar os membros de vários módulos para a sessão atual

Este exemplo importa os membros dos módulos PSDiagnostics e Dism para a sessão atual.

$m = Get-Module -ListAvailable PSDiagnostics, Dism
Import-Module -ModuleInfo $m

O Get-Module cmdlet obtém os módulos PSDiagnostics e Dism e salva os objetos na $m variável. O parâmetro ListAvailable é necessário quando você está recebendo módulos que ainda não foram importados para a sessão.

O parâmetro ModuleInfo de Import-Module é usado para importar os módulos para a sessão atual.

Exemplo 4: Importar todos os módulos especificados por um caminho

Este exemplo usa um caminho explícito para identificar o módulo a ser importado.

Import-Module -Name c:\ps-test\modules\test -Verbose

VERBOSE: Loading module from path 'C:\ps-test\modules\Test\Test.psm1'.
VERBOSE: Exporting function 'my-parm'.
VERBOSE: Exporting function 'Get-Parameter'.
VERBOSE: Exporting function 'Get-Specification'.
VERBOSE: Exporting function 'Get-SpecDetails'.

O uso do parâmetro Verbose faz com que Import-Module o progresso seja relatado à medida que carrega o módulo. Sem o parâmetro Verbose, PassThru ou AsCustomObject , Import-Module não gera nenhuma saída quando importa um módulo.

Exemplo 5: Restringir membros do módulo importados para uma sessão

Este exemplo mostra como restringir quais membros do módulo são importados para a sessão e o efeito desse comando na sessão. O parâmetro Function limita os membros que são importados do módulo. Você também pode usar os parâmetros Alias, Variable e Cmdlet para restringir outros membros importados por um módulo.

O Get-Module cmdlet obtém o objeto que representa o módulo PSDiagnostics . A propriedade ExportedCmdlets lista todos os cmdlets que o módulo exporta, mesmo que nem todos tenham sido importados.

Import-Module PSDiagnostics -Function Disable-PSTrace, Enable-PSTrace
(Get-Module PSDiagnostics).ExportedCommands

Key                          Value
---                          -----
Disable-PSTrace              Disable-PSTrace
Disable-PSWSManCombinedTrace Disable-PSWSManCombinedTrace
Disable-WSManTrace           Disable-WSManTrace
Enable-PSTrace               Enable-PSTrace
Enable-PSWSManCombinedTrace  Enable-PSWSManCombinedTrace
Enable-WSManTrace            Enable-WSManTrace
Get-LogProperties            Get-LogProperties
Set-LogProperties            Set-LogProperties
Start-Trace                  Start-Trace
Stop-Trace                   Stop-Trace

Get-Command -Module PSDiagnostics

CommandType     Name                 Version    Source
-----------     ----                 -------    ------
Function        Disable-PSTrace      6.1.0.0    PSDiagnostics
Function        Enable-PSTrace       6.1.0.0    PSDiagnostics

O uso do parâmetro Module do Get-Command cmdlet mostra os comandos que foram importados do módulo PSDiagnostics . Os resultados confirmam que apenas os Disable-PSTrace cmdlets e Enable-PSTrace foram importados.

Exemplo 6: Importar os membros de um módulo e adicionar um prefixo

Este exemplo importa o módulo PSDiagnostics para a sessão atual, adiciona um prefixo aos nomes de membros e exibe os nomes de membros prefixados. O parâmetro Prefix de Import-Module adiciona o prefixo x a todos os membros que são importados do módulo. O prefixo aplica-se apenas aos membros na sessão atual. Não altera o módulo. O parâmetro PassThru retorna um objeto module que representa o módulo importado.

Import-Module PSDiagnostics -Prefix x -PassThru

ModuleType Version    Name               ExportedCommands
---------- -------    ----               ----------------
Script     6.1.0.0    PSDiagnostics      {Disable-xPSTrace, Disable-xPSWSManCombinedTrace, Disable-xW...

Get-Command -Module PSDiagnostics

CommandType     Name                                   Version    Source
-----------     ----                                   -------    ------
Function        Disable-xPSTrace                       6.1.0.0    PSDiagnostics
Function        Disable-xPSWSManCombinedTrace          6.1.0.0    PSDiagnostics
Function        Disable-xWSManTrace                    6.1.0.0    PSDiagnostics
Function        Enable-xPSTrace                        6.1.0.0    PSDiagnostics
Function        Enable-xPSWSManCombinedTrace           6.1.0.0    PSDiagnostics
Function        Enable-xWSManTrace                     6.1.0.0    PSDiagnostics
Function        Get-xLogProperties                     6.1.0.0    PSDiagnostics
Function        Set-xLogProperties                     6.1.0.0    PSDiagnostics
Function        Start-xTrace                           6.1.0.0    PSDiagnostics
Function        Stop-xTrace                            6.1.0.0    PSDiagnostics

Get-Command Obtém os membros que foram importados do módulo. A saída mostra que os membros do módulo foram prefixados corretamente.

Exemplo 7: Obter e usar um objeto personalizado

Este exemplo demonstra como obter e usar o objeto personalizado retornado pelo Import-Module.

Os objetos personalizados incluem membros sintéticos que representam cada um dos membros do módulo importados. Por exemplo, os cmdlets e funções em um módulo são convertidos em métodos de script do objeto personalizado.

Os objetos personalizados são úteis em scripts. Eles também são úteis quando vários objetos importados têm os mesmos nomes. Usar o método de script de um objeto é equivalente a especificar o nome totalmente qualificado de um membro importado, incluindo seu nome de módulo.

O parâmetro AsCustomObject só é utilizável ao importar um módulo de script. Use Get-Module para determinar qual dos módulos disponíveis é um módulo de script.

Get-Module -List | Format-Table -Property Name, ModuleType -AutoSize

Name          ModuleType
----          ----------
Show-Calendar     Script
BitsTransfer    Manifest
PSDiagnostics   Manifest
TestCmdlets       Script
...

$a = Import-Module -Name Show-Calendar -AsCustomObject -PassThru
$a | Get-Member

TypeName: System.Management.Automation.PSCustomObject
Name          MemberType   Definition
----          ----------   ----------
Equals        Method       bool Equals(System.Object obj)
GetHashCode   Method       int GetHashCode()
GetType       Method       type GetType()
ToString      Method       string ToString()
Show-Calendar ScriptMethod System.Object Show-Calendar();

$a."Show-Calendar"()

O Show-Calendar módulo de script é importado usando o parâmetro AsCustomObject para solicitar um objeto personalizado e o parâmetro PassThru para retornar o objeto. O objeto personalizado resultante é salvo na $a variável.

A $a variável é canalizada para o Get-Member cmdlet para mostrar as propriedades e os métodos do objeto salvo. A saída mostra um método de Show-Calendar script.

Para chamar o Show-Calendar método de script, o nome do método deve ser colocado entre aspas porque o nome inclui um hífen.

Exemplo 8: Reimportar um módulo para a mesma sessão

Este exemplo mostra como usar o parâmetro Force de Import-Module quando você está reimportando um módulo para a mesma sessão. O parâmetro Force remove o módulo carregado e, em seguida, importa-o novamente.

Import-Module PSDiagnostics
Import-Module PSDiagnostics -Force -Prefix PS

O primeiro comando importa o módulo PSDiagnostics . O segundo comando importa o módulo novamente, desta vez usando o parâmetro Prefix .

Sem o parâmetro Force , a sessão incluiria duas cópias de cada cmdlet PSDiagnostics , uma com o nome padrão e outra com o nome prefixado.

Exemplo 9: Executar comandos que foram ocultos por comandos importados

Este exemplo mostra como executar comandos que foram ocultos por comandos importados. O módulo TestModule inclui uma função chamada Get-Date que retorna o ano e o dia do ano.

Get-Date

Thursday, August 15, 2019 2:26:12 PM

Import-Module TestModule
Get-Date

19227

Get-Command Get-Date -All | Format-Table -Property CommandType, Name, ModuleName -AutoSize

CommandType     Name         ModuleName
-----------     ----         ----------
Function        Get-Date     TestModule
Cmdlet          Get-Date     Microsoft.PowerShell.Utility

Microsoft.PowerShell.Utility\Get-Date

Thursday, August 15, 2019 2:28:31 PM

O primeiro Get-Date cmdlet retorna um objeto DateTime com a data atual. Depois de importar o módulo TestModule , Get-Date retorna o ano e o dia do ano.

Usando o parâmetro All de Get-Command show todos os Get-Date comandos na sessão. Os resultados mostram que há dois Get-Date comandos na sessão, uma função do módulo TestModule e um cmdlet do módulo Microsoft.PowerShell.Utility .

Como as funções têm precedência sobre cmdlets, a Get-Date função do módulo TestModule é executada, em vez do Get-Date cmdlet. Para executar a versão original do , você deve qualificar o nome do Get-Datecomando com o nome do módulo.

Para obter mais informações sobre a precedência de comandos no PowerShell, consulte about_Command_Precedence.

Exemplo 10: Importar uma versão mínima de um módulo

Este exemplo importa o módulo PowerShellGet . Ele usa o parâmetro MinimumVersion de Import-Module para importar apenas a versão 2.0.0 ou superior do módulo.

Import-Module -Name PowerShellGet -MinimumVersion 2.0.0

Você também pode usar o parâmetro RequiredVersion para importar uma versão específica de um módulo ou usar os #Requires parâmetros Module e Version da palavra-chave para exigir uma versão específica de um módulo em um script.

Exemplo 11: Importar usando um nome totalmente qualificado

Este exemplo importa uma versão específica de um módulo usando o FullyQualifiedName.

PS> Get-Module -ListAvailable PowerShellGet | Select-Object Name, Version

Name          Version
----          -------
PowerShellGet 2.2.1
PowerShellGet 2.1.3
PowerShellGet 2.1.2
PowerShellGet 1.0.0.1

PS> Import-Module -FullyQualifiedName @{ModuleName = 'PowerShellGet'; ModuleVersion = '2.1.3' }

Exemplo 12: Importar usando um caminho totalmente qualificado

Este exemplo importa uma versão específica de um módulo usando o caminho totalmente qualificado.

PS> Get-Module -ListAvailable PowerShellGet | Select-Object Path

Path
----
C:\Program Files\PowerShell\Modules\PowerShellGet\2.2.1\PowerShellGet.psd1
C:\program files\powershell\6\Modules\PowerShellGet\PowerShellGet.psd1
C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\2.1.2\PowerShellGet.psd1
C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.0.0.1\PowerShellGet.psd1

PS> Import-Module -Name 'C:\Program Files\PowerShell\Modules\PowerShellGet\2.2.1\PowerShellGet.psd1'

Exemplo 13: Importar um módulo de um computador remoto

Este exemplo mostra como usar o Import-Module cmdlet para importar um módulo de um computador remoto. Este comando usa o recurso de comunicação remota implícita do PowerShell.

Ao importar módulos de outra sessão, você pode usar os cmdlets na sessão atual. No entanto, os comandos que usam os cmdlets são executados na sessão remota.

$s = New-PSSession -ComputerName Server01
Get-Module -PSSession $s -ListAvailable -Name NetSecurity

ModuleType Name             ExportedCommands
---------- ----             ----------------
Manifest   NetSecurity      {New-NetIPsecAuthProposal, New-NetIPsecMainModeCryptoProposal, New-Ne...

Import-Module -PSSession $s -Name NetSecurity
Get-Command -Module NetSecurity -Name Get-*Firewall*

CommandType     Name                                               ModuleName
-----------     ----                                               ----------
Function        Get-NetFirewallAddressFilter                       NetSecurity
Function        Get-NetFirewallApplicationFilter                   NetSecurity
Function        Get-NetFirewallInterfaceFilter                     NetSecurity
Function        Get-NetFirewallInterfaceTypeFilter                 NetSecurity
Function        Get-NetFirewallPortFilter                          NetSecurity
Function        Get-NetFirewallProfile                             NetSecurity
Function        Get-NetFirewallRule                                NetSecurity
Function        Get-NetFirewallSecurityFilter                      NetSecurity
Function        Get-NetFirewallServiceFilter                       NetSecurity
Function        Get-NetFirewallSetting                             NetSecurity

Get-NetFirewallRule -DisplayName "Windows Remote Management*" |
  Format-Table -Property DisplayName, Name -AutoSize

DisplayName                                              Name
-----------                                              ----
Windows Remote Management (HTTP-In)                      WINRM-HTTP-In-TCP
Windows Remote Management (HTTP-In)                      WINRM-HTTP-In-TCP-PUBLIC
Windows Remote Management - Compatibility Mode (HTTP-In) WINRM-HTTP-Compat-In-TCP

New-PSSession cria uma sessão remota (PSSession) para o Server01 computador. O PSSession é salvo na $s variável.

A execução Get-Module com o parâmetro PSSession mostra que o módulo NetSecurity está instalado e disponível no computador remoto. Esse comando é equivalente a usar o cmdlet para executar Get-Module o Invoke-Command comando na sessão remota. Por exemplo:

Invoke-Command $s {Get-Module -ListAvailable -Name NetSecurity

A execução Import-Module com o parâmetro PSSession importa o módulo NetSecurity do computador remoto para a sessão atual. O Get-Command cmdlet recupera comandos que começam com Get e incluem Firewall do módulo NetSecurity . A saída confirma que o módulo e seus cmdlets foram importados para a sessão atual.

Em seguida, o Get-NetFirewallRule cmdlet obtém regras de firewall de Gerenciamento Remoto do Server01 Windows no computador. Isso equivale a usar o Invoke-Command cmdlet para ser executado Get-NetFirewallRule na sessão remota.

Exemplo 14: Gerenciar armazenamento em um computador remoto sem o sistema operacional Windows

Neste exemplo, o administrador do computador instalou o provedor WMI de descoberta de módulo, que permite que você use comandos CIM projetados para o provedor.

O New-CimSession cmdlet cria uma sessão no computador remoto chamado RSDGF03. A sessão se conecta ao serviço WMI no computador remoto. A sessão CIM é salva na $cs variável. Import-Module usa o CimSession in $cs para importar o módulo CIM de armazenamento do RSDGF03 computador.

O Get-Command cmdlet mostra o Get-Disk comando no módulo Armazenamento . Quando você importa um módulo CIM para a sessão local, o PowerShell converte os arquivos CDXML de cada comando em scripts do PowerShell, que aparecem como funções na sessão local.

Embora Get-Disk seja digitado na sessão local, o cmdlet é executado implicitamente no computador remoto do qual foi importado. O comando retorna objetos do computador remoto para a sessão local.

$cs = New-CimSession -ComputerName RSDGF03
Import-Module -CimSession $cs -Name Storage
# Importing a CIM module, converts the CDXML files for each command into
# PowerShell scripts. These appear as functions in the local session.
Get-Command Get-Disk

CommandType     Name                  ModuleName
-----------     ----                  ----------
Function        Get-Disk              Storage

# Use implicit remoting to query disks on the remote computer from which the
# module was imported.
Get-Disk

Number Friendly Name           OperationalStatus  Total Size Partition Style
------ -------------           -----------------  ---------- ---------------
0      Virtual HD ATA Device   Online                  40 GB MBR

Parâmetros

-Alias

Especifica os aliases que esse cmdlet importa do módulo para a sessão atual. Insira uma lista de aliases separada por vírgula. Caracteres curinga são permitidos.

Alguns módulos exportam automaticamente aliases selecionados para sua sessão quando você importa o módulo. Este parâmetro permite selecionar entre os aliases exportados.

Tipo:String[]
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:True

-ArgumentList

Especifica uma matriz de argumentos, ou valores de parâmetro, que são passados para um módulo de script durante o Import-Module comando. Esse parâmetro é válido somente quando você está importando um módulo de script.

Você também pode se referir ao parâmetro ArgumentList por seu alias, args. Para obter mais informações sobre o comportamento de ArgumentList, consulte about_Splatting.

Tipo:Object[]
Aliases:Args
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-AsCustomObject

Indica que esse cmdlet retorna um objeto personalizado com membros que representam os membros do módulo importados. Este parâmetro é válido apenas para módulos de script.

Quando você usa o parâmetro AsCustomObject , importa os membros do módulo para a sessão e, em seguida, Import-Module retorna um objeto PSCustomObject em vez de um objeto PSModuleInfo . Você pode salvar o objeto personalizado em uma variável e usar a enumeração de acesso de membro para invocar os membros.

Tipo:SwitchParameter
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Assembly

Especifica uma matriz de objetos de montagem. Este cmdlet importa os cmdlets e provedores implementados nos objetos de assembly especificados. Insira uma variável que contenha objetos assembly ou um comando que crie objetos assembly. Você também pode canalizar um objeto de montagem para Import-Module.

Quando você usa esse parâmetro, somente os cmdlets e provedores implementados pelos assemblies especificados são importados. Se o módulo contiver outros arquivos, eles não serão importados e você pode estar faltando membros importantes do módulo. Use este parâmetro para depurar e testar o módulo ou quando for instruído a usá-lo pelo autor do módulo.

Tipo:Assembly[]
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-CimNamespace

Especifica o namespace de um provedor CIM alternativo que expõe módulos CIM. O valor padrão é o namespace do provedor WMI de Descoberta de Módulo.

Use este parâmetro para importar módulos CIM de computadores e dispositivos que não estejam executando um sistema operacional Windows.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:String
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-CimResourceUri

Especifica um local alternativo para módulos CIM. O valor padrão é o URI do recurso do provedor WMI de Descoberta de Módulo no computador remoto.

Use este parâmetro para importar módulos CIM de computadores e dispositivos que não estejam executando um sistema operacional Windows.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:Uri
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-CimSession

Especifica uma sessão CIM no computador remoto. Insira uma variável que contenha a sessão CIM ou um comando que obtenha a sessão CIM, como um comando Get-CimSession .

Import-Module usa a conexão de sessão CIM para importar módulos do computador remoto para a sessão atual. Quando você usa os comandos do módulo importado na sessão atual, os comandos são executados no computador remoto.

Você pode usar esse parâmetro para importar módulos de computadores e dispositivos que não estejam executando o sistema operacional Windows e computadores Windows que tenham PowerShell, mas não tenham a comunicação remota do PowerShell habilitada.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:CimSession
Position:Named
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Cmdlet

Especifica uma matriz de cmdlets que esse cmdlet importa do módulo para a sessão atual. Caracteres curinga são permitidos.

Alguns módulos exportam automaticamente cmdlets selecionados para sua sessão quando você importa o módulo. Esse parâmetro permite selecionar entre os cmdlets exportados.

Tipo:String[]
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:True

-DisableNameChecking

Indica que esse cmdlet suprime a mensagem que avisa quando você importa um cmdlet ou função cujo nome inclui um verbo não aprovado ou um caractere proibido.

Por padrão, quando um módulo importado exporta cmdlets ou funções que têm verbos não aprovados em seus nomes, o PowerShell exibe a seguinte mensagem de aviso:

AVISO: Alguns nomes de comandos importados incluem verbos não aprovados que podem torná-los menos detetáveis. Use o parâmetro Verbose para obter mais detalhes ou digite Get-Verb para ver a lista de verbos aprovados.

Esta mensagem é apenas um aviso. O módulo completo ainda é importado, incluindo os comandos não conformes. Embora a mensagem seja exibida para os usuários do módulo, o problema de nomenclatura deve ser corrigido pelo autor do módulo.

Tipo:SwitchParameter
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Force

Esse parâmetro faz com que um módulo seja carregado, ou recarregado, sobre o atual. Alguns módulos carregam montagens externas. A importação falhará se você estiver importando um módulo que carrega uma versão mais recente de um assembly. O parâmetro Force não pode substituir o erro. Você deve iniciar uma nova sessão para carregar a nova versão.

Tipo:SwitchParameter
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-FullyQualifiedName

O valor pode ser um nome de módulo, uma especificação de módulo completo ou um caminho para um arquivo de módulo.

Quando o valor é um caminho, o caminho pode ser totalmente qualificado ou relativo. Um caminho relativo é resolvido em relação ao script que contém a instrução using.

Quando o valor é um nome ou especificação de módulo, o PowerShell procura o módulo especificado no PSModulePath .

Uma especificação de módulo é uma hashtable que tem as seguintes chaves.

  • ModuleName - Obrigatório Especifica o nome do módulo.
  • GUID - Opcional Especifica o GUID do módulo.
  • Também é necessário especificar pelo menos uma das três chaves abaixo.
    • ModuleVersion - Especifica uma versão mínima aceitável do módulo.
    • MaximumVersion - Especifica a versão máxima aceitável do módulo.
    • RequiredVersion - Especifica uma versão exata e obrigatória do módulo. Isso não pode ser usado com as outras chaves de versão.
Tipo:ModuleSpecification[]
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Function

Especifica uma matriz de funções que esse cmdlet importa do módulo para a sessão atual. Caracteres curinga são permitidos. Alguns módulos exportam automaticamente as funções selecionadas para a sua sessão quando você importa o módulo. Este parâmetro permite selecionar entre as funções exportadas.

Tipo:String[]
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:True

-Global

Indica que esse cmdlet importa módulos para o estado da sessão global para que estejam disponíveis para todos os comandos na sessão.

Por padrão, quando Import-Module o cmdlet é chamado do prompt de comando, do arquivo de script ou do bloco de script, todos os comandos são importados para o estado da sessão global.

Quando invocado de outro módulo, Import-Module o cmdlet importa os comandos em um módulo, incluindo comandos de módulos aninhados, para o estado de sessão do módulo chamador.

Gorjeta

Você deve evitar ligar Import-Module de dentro de um módulo. Em vez disso, declare o módulo de destino como um módulo aninhado no manifesto do módulo pai. A declaração de módulos aninhados melhora a capacidade de descoberta das dependências.

O parâmetro Global é equivalente ao parâmetro Scope com um valor Global.

Para restringir os comandos que um módulo exporta, use um Export-ModuleMember comando no módulo de script.

Tipo:SwitchParameter
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-MaximumVersion

Especifica uma versão máxima. Este cmdlet importa apenas uma versão do módulo que é menor ou igual ao valor especificado. Se nenhuma versão se qualificar, Import-Module retornará um erro.

Tipo:String
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-MinimumVersion

Especifica uma versão mínima. Este cmdlet importa apenas uma versão do módulo que é maior ou igual ao valor especificado. Use o nome do parâmetro MinimumVersion ou seu alias, Version. Se nenhuma versão se qualificar, Import-Module gerará um erro.

Para especificar uma versão exata, use o parâmetro RequiredVersion . Você também pode usar os parâmetros Module e Version da palavra-chave #Requires para exigir uma versão específica de um módulo em um script.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:Version
Aliases:Version
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-ModuleInfo

Especifica uma matriz de objetos de módulo a serem importados. Insira uma variável que contenha os objetos module ou um comando que obtenha os objetos module, como o seguinte comando: Get-Module -ListAvailable. Você também pode canalizar objetos de módulo para Import-Module.

Tipo:PSModuleInfo[]
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Name

Especifica os nomes dos módulos a serem importados. Digite o nome do módulo ou o nome de um arquivo no módulo, como um .psd1, .psm1, .dll, ou .ps1 arquivo. Os caminhos de arquivo são opcionais. Caracteres curinga não são permitidos. Você também pode canalizar nomes de módulos e nomes de arquivos para Import-Module.

Se você omitir um caminho, Import-Module procurará o módulo nos caminhos salvos na $env:PSModulePath variável de ambiente.

Especifique apenas o nome do módulo sempre que possível. Quando você especifica um nome de arquivo, somente os membros implementados nesse arquivo são importados. Se o módulo contiver outros arquivos, eles não serão importados e você pode estar faltando membros importantes do módulo.

Nota

Embora seja possível importar um arquivo de script (.ps1) como um módulo, os arquivos de script geralmente não são estruturados como o arquivo de módulos de script (.psm1). Importar um arquivo de script não garante que ele seja utilizável como um módulo. Para obter mais informações, consulte about_Modules.

Tipo:String[]
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:True

-NoClobber

Impede a importação de comandos com os mesmos nomes dos comandos existentes na sessão atual. Por padrão, Import-Module importa todos os comandos de módulo exportados.

Os comandos com os mesmos nomes podem ocultar ou substituir comandos na sessão. Para evitar conflitos de nome de comando em uma sessão, use os parâmetros Prefix ou NoClobber . Para obter mais informações sobre conflitos de nome e precedência de comando, consulte "Módulos e conflitos de nome" em about_Modules e about_Command_Precedence.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:SwitchParameter
Aliases:NoOverwrite
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-PassThru

Retorna um objeto que representa o módulo importado. Por padrão, esse cmdlet não gera nenhuma saída.

Tipo:SwitchParameter
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Prefix

Especifica um prefixo que esse cmdlet adiciona aos substantivos nos nomes dos membros do módulo importados.

Use esse parâmetro para evitar conflitos de nome que podem ocorrer quando membros diferentes na sessão têm o mesmo nome. Esse parâmetro não altera o módulo e não afeta os arquivos que o módulo importa para seu próprio uso. Estes são conhecidos como módulos aninhados. Este cmdlet afeta apenas os nomes dos membros na sessão atual.

Por exemplo, se você especificar o prefixo UTC e, em seguida, importar um Get-Date cmdlet, o cmdlet será conhecido na sessão como Get-UTCDate, e não será confundido com o cmdlet original Get-Date .

O valor desse parâmetro tem precedência sobre a propriedade DefaultCommandPrefix do módulo, que especifica o prefixo padrão.

Tipo:String
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-PSSession

Especifica uma sessão gerenciada pelo usuário do PowerShell (PSSession) da qual esse cmdlet importa módulos para a sessão atual. Insira uma variável que contenha um PSSession ou um comando que obtenha um PSSession, como um Get-PSSession comando.

Ao importar um módulo de uma sessão diferente para a sessão atual, você pode usar os cmdlets do módulo na sessão atual, assim como usaria cmdlets de um módulo local. Os comandos que usam os cmdlets remotos são executados na sessão remota, mas os detalhes da comunicação remota são gerenciados em segundo plano pelo PowerShell.

Este parâmetro usa o recurso de comunicação remota implícita do PowerShell. É equivalente a usar o Import-PSSession cmdlet para importar módulos específicos de uma sessão.

Import-Module não é possível importar módulos principais do PowerShell de outra sessão. Os módulos principais do PowerShell têm nomes que começam com Microsoft.PowerShell.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:PSSession
Position:Named
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-RequiredVersion

Especifica uma versão do módulo que este cmdlet importa. Se a versão não estiver instalada, Import-Module gera um erro.

Por padrão, Import-Module importa o módulo sem verificar o número da versão.

Para especificar uma versão mínima, use o parâmetro MinimumVersion . Você também pode usar os parâmetros Module e Version da palavra-chave #Requires para exigir uma versão específica de um módulo em um script.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Os scripts que usam RequiredVersion para importar módulos incluídos em versões existentes do sistema operacional Windows não são executados automaticamente em versões futuras do sistema operacional Windows. Isso ocorre porque os números de versão do módulo PowerShell em versões futuras do sistema operacional Windows são maiores do que os números de versão do módulo em versões existentes do sistema operacional Windows.

Tipo:Version
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Scope

Especifica um escopo para importar o módulo.

Os valores aceitáveis para este parâmetro são:

  • Global. Disponível para todos os comandos da sessão. Equivalente ao parâmetro Global .
  • Local. Disponível apenas no âmbito atual.

Por padrão, quando Import-Module o cmdlet é chamado do prompt de comando, do arquivo de script ou do bloco de script, todos os comandos são importados para o estado da sessão global. Você pode usar o parâmetro para importar o conteúdo do -Scope Local módulo para o escopo do script ou scriptblock.

Quando invocado de outro módulo, Import-Module o cmdlet importa os comandos em um módulo, incluindo comandos de módulos aninhados, para o estado da sessão do chamador. Especificando -Scope Global ou -Global indicando que esse cmdlet importa módulos para o estado da sessão global para que eles estejam disponíveis para todos os comandos na sessão.

O parâmetro Global é equivalente ao parâmetro Scope com um valor Global.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:String
Valores aceites:Local, Global
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-SkipEditionCheck

Ignora a CompatiblePSEditions verificação no campo.

Permite carregar um módulo do "$($env:windir)\System32\WindowsPowerShell\v1.0\Modules" diretório do módulo no PowerShell Core quando esse módulo não especifica Core no campo de manifesto CompatiblePSEditions .

Ao importar um módulo de outro caminho, essa opção não faz nada, já que a verificação não é executada. No Linux e macOS, este switch não faz nada.

Para obter mais informações, consulte about_PowerShell_Editions.

Aviso

Import-Module -SkipEditionCheck ainda é provável que não consiga importar um módulo. Mesmo que seja bem-sucedido, invocar um comando do módulo pode falhar mais tarde quando ele tenta usar uma API incompatível.

Tipo:SwitchParameter
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-UseWindowsPowerShell

Carrega o módulo usando a funcionalidade de compatibilidade do Windows PowerShell. Consulte about_Windows_PowerShell_Compatibility para obter mais informações.

Tipo:SwitchParameter
Aliases:UseWinPS
Position:Named
Default value:False
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Variable

Especifica uma matriz de variáveis que este cmdlet importa do módulo para a sessão atual. Insira uma lista de variáveis. Caracteres curinga são permitidos.

Alguns módulos exportam automaticamente as variáveis selecionadas para sua sessão quando você importa o módulo. Este parâmetro permite selecionar entre as variáveis exportadas.

Tipo:String[]
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:True

Entradas

String

Você pode canalizar um nome de módulo para esse cmdlet.

PSModuleInfo

Você pode canalizar um objeto de módulo para este cmdlet.

Assembly

Você pode canalizar um objeto assembly para este cmdlet.

Saídas

None

Por padrão, esse cmdlet não retorna nenhuma saída.

PSModuleInfo

Se você especificar o parâmetro PassThru , o cmdlet gerará um objeto System.Management.Automation.PSModuleInfo que representa o módulo importado.

PSCustomObject

Se você especificar os parâmetros AsCustomObject e PassThru juntos, o cmdlet gerará um objeto PSCustomObject que representa o módulo.

Notas

O PowerShell inclui os seguintes aliases para Import-Module:

  • Todas as plataformas:

    • ipmo

  • Antes de importar um módulo, o módulo deve estar acessível ao computador local e incluído na PSModulePath variável ambiental. Para obter mais informações, consulte about_Modules.

    Você também pode usar os parâmetros PSSession e CIMSession para importar módulos instalados em computadores remotos. No entanto, os comandos que usam os cmdlets nesses módulos são executados na sessão remota no computador remoto.

  • Se você importar membros com o mesmo nome e o mesmo tipo para sua sessão, o PowerShell usará o membro importado por último por padrão. Variáveis e aliases são substituídos e os originais não são acessíveis. Funções, cmdlets e provedores são meramente sombreados pelos novos membros. Eles podem ser acessados qualificando o nome do comando com o nome de seu snap-in, módulo ou caminho de função.

  • Para atualizar os dados de formatação dos comandos importados de um módulo, use o Update-FormatData cmdlet. Se o arquivo de formatação de um módulo for alterado, use o Update-FormatData cmdlet para atualizar os dados de formatação dos comandos importados. Não é necessário importar o módulo novamente.

  • A partir do Windows PowerShell 3.0, os comandos principais instalados com o PowerShell são empacotados em módulos. No Windows PowerShell 2.0 e em programas host que criam sessões de estilo mais antigo em versões posteriores do PowerShell, os comandos principais são empacotados em snap-ins (PSSnapins). A exceção é Microsoft.PowerShell.Core, que é sempre um snap-in. Além disso, as sessões remotas, como as iniciadas New-PSSession pelo cmdlet, são sessões de estilo mais antigo que incluem snap-ins principais.

    Para obter informações sobre o método CreateDefault2 que cria sessões de estilo mais recente com módulos principais, consulte o Método CreateDefault2.

  • No Windows PowerShell 2.0, alguns valores de propriedade do objeto module, como os valores das propriedades ExportedCmdlets e NestedModules , não foram preenchidos até que o módulo fosse importado.

  • Se você tentar importar um módulo que contenha assemblies de modo misto que não são compatíveis com o Windows PowerShell 3.0+, Import-Module retornará uma mensagem de erro como a seguinte.

    Import-Module : O assembly de modo misto é construído com base na versão 'v2.0.50727' do tempo de execução e não pode ser carregado no tempo de execução 4.0 sem informações de configuração adicionais.

    Este erro ocorre quando um módulo projetado para o Windows PowerShell 2.0 contém pelo menos um assembly de módulo misto. Um assembly de módulo misto que inclui código gerenciado e não gerenciado, como C++ e C#.

    Para importar um módulo que contém assemblies de modo misto, inicie o Windows PowerShell 2.0 usando o seguinte comando e tente o Import-Module comando novamente.

    PowerShell.exe -Version 2.0

  • Para usar o recurso de sessão CIM, o computador remoto deve ter comunicação remota WS-Management e WMI (Instrumentação de Gerenciamento do Windows), que é a implementação da Microsoft do padrão CIM (Common Information Model). O computador também deve ter o provedor WMI de descoberta de módulo ou um provedor CIM alternativo que tenha os mesmos recursos básicos.

    Você pode usar o recurso de sessão CIM em computadores que não executam um sistema operacional Windows e em computadores Windows que têm PowerShell, mas não têm a comunicação remota do PowerShell habilitada.

    Você também pode usar os parâmetros CIM para obter módulos CIM de computadores que têm a comunicação remota do PowerShell habilitada, incluindo o computador local. Quando você cria uma sessão CIM no computador local, o PowerShell usa DCOM, em vez de WMI, para criar a sessão.

  • Por padrão, importa módulos no escopo global, Import-Module mesmo quando chamados de um escopo descendente. O escopo de nível superior e todos os escopos descendentes têm acesso aos elementos exportados do módulo.

    Em um escopo descendente, -Scope Local limita a importação a esse escopo e a todos os seus escopos descendentes. Os escopos pai não veem os membros importados.

    Nota

    Get-Module mostra todos os módulos carregados na sessão atual. Isso inclui módulos carregados localmente em um escopo descendente. Use Get-Command -Module modulename para ver quais membros são carregados no escopo atual.

  • Import-Module não carrega definições de classe e enumeração no módulo. Use a using module instrução no início do script. Isso importa o módulo, incluindo as definições de classe e enumeração. Para obter mais informações, consulte about_Using.

  • Durante o desenvolvimento de um módulo de script, é comum fazer alterações no código e, em seguida, carregar a nova versão do módulo usando Import-Module com o parâmetro Force . Isso funciona apenas para alterações de funções no módulo raiz. Import-Module não recarrega nenhum módulo aninhado. Além disso, não há como carregar classes ou enumerações atualizadas.

    Para obter membros de módulo atualizados definidos em módulos aninhados, remova o módulo com Remove-Modulee, em seguida, importe o módulo novamente.

    Se o módulo foi carregado com uma using instrução, você deve iniciar uma nova sessão para importar definições atualizadas para as classes e enumerações. As classes e enumerações definidas no PowerShell e importadas com uma using instrução não podem ser descarregadas.