Import-Module
Adiciona módulos à sessão atual.
Sintaxe
Import-Module [-Name] <string[]> [-Alias <string[]>] [-ArgumentList <Object[]>] [-AsCustomObject] [-Cmdlet <string[]>] [-Force] [-Function <string[]>] [-Global] [-PassThru] [-Prefix <string>] [-Variable <string[]>] [-Version <Version>] [<CommonParameters>]
Import-Module [-Assembly] <Assembly[]> [-Alias <string[]>] [-ArgumentList <Object[]>] [-AsCustomObject] [-Cmdlet <string[]>] [-Force] [-Function <string[]>] [-Global] [-PassThru] [-Prefix <string>] [-Variable <string[]>] [-Version <Version>] [<CommonParameters>]
Import-Module [-ModuleInfo] <PSModuleInfo[]> [-Alias <string[]>] [-ArgumentList <Object[]>] [-AsCustomObject] [-Cmdlet <string[]>] [-Force] [-Function <string[]>] [-Global] [-PassThru] [-Prefix <string>] [-Variable <string[]>] [-Version <Version>] [<CommonParameters>]
Descrição
O cmdlet Import-Module adiciona um ou mais módulos à sessão atual.
Um módulo é um pacote que pode contém membros (cmdlets, provedores, scripts, funções, variáveis e outras ferramentas e arquivos) que podem ser usados no Windows PowerShell. Depois que um módulo é importado, você pode usar os membros do módulo em sua sessão.
Para importar um módulo, use o parâmetro Name, Assembly ou ModuleInfo para identificar o módulo a ser importado. 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 os membros que são importados.
Import-Module importa apenas um módulo para a sessão atual. Para importar o módulo para todas as sessões, adicione um comando Import-Module a seu perfil do Windows PowerShell. Para obter mais informações sobre perfis, consulte about_Profiles.
Para obter mais informações sobre módulos, consulte about_Modules.
Parâmetros
-Alias <string[]>
Importa somente os aliases especificados do módulo para a sessão atual. Digite uma lista de alias separados por vírgula. São permitidos caracteres curinga.
Alguns módulos exportam automaticamente aliases selecionados para sua sessão quando você importa o módulo. Esse parâmetro permite que você selecione entre os aliases exportados.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
true |
-ArgumentList <Object[]>
Especifica argumentos (valores de parâmetros) que são passados para um módulo de script durante o comando Import-Module. Esse parâmetro é válido apenas quando você está importando um módulo de script.
Você também pode se referir a ArgumentList pelo seu alias, "args". Para obter mais informações, consulte about_Aliases.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-AsCustomObject
Retorna um objeto personalizado com membros que representam os membros de módulo importados. Esse parâmetro só é válido para módulos de script.
Quando você usa o parâmetro AsCustomObject, Import-Module importa os membros do módulo para a sessão e retorna um objeto PSCustomObject, em vez de um objeto PSModuleInfo. Você pode salvar o objeto personalizado em uma variável e usar a notação de ponto para invocar os membros.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Assembly <Assembly[]>
Importa somente os cmdlets e provedores implementados nos objetos de assembly especificados. Insira uma variável que contenha os objetos de assembly ou um comando que crie objetos de assembly. Você também pode canalizar um objeto de assembly 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ê poderá estar perdendo membros importantes do módulo. Use esse parâmetro para depurar e testar o módulo, ou quando for instruído a usá-lo pelo autor do módulo.
Necessário? |
true |
Posição? |
1 |
Valor padrão |
|
Aceitar entrada do pipeline? |
true (ByValue) |
Aceitar caracteres curinga? |
false |
-Cmdlet <string[]>
Importa somente os cmdlets especificados do módulo para a sessão atual. Insira uma lista de cmdlets. São permitidos caracteres curinga.
Alguns módulos exportam automaticamente cmdlets selecionados para sua sessão quando você importa o módulo. Esse parâmetro permite que você selecione entre os cmdlets exportados.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
true |
-Force
Reimporta um módulo e seus membros, mesmo que o módulo ou seus membros tenham um modo de acesso somente leitura.
Necessário? |
false |
Posição? |
named |
Valor padrão |
False |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Function <string[]>
Importa somente as funções especificadas do módulo para a sessão atual. Insira uma lista de funções. São permitidos caracteres curinga.
Alguns módulos exportam automaticamente funções selecionadas para sua sessão quando você importa o módulo. Esse parâmetro permite que você selecione entre as funções exportadas.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
true |
-Global
Quando usado em um módulo de script (.psm1), esse parâmetro importa módulos para o estado de sessão global.
O parâmetro está em vigor apenas quando aparece em um módulo de script. Caso contrário, é ignorado.
Por padrão, os comandos em um módulo de script, inclusive comandos de módulos aninhados, são importados para o estado de sessão do chamador. Para restringir os comandos que um módulo exporta, use um comando Export-ModuleMember no módulo de script.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-ModuleInfo <PSModuleInfo[]>
Especifica objetos do módulo a serem importados. Insira uma variável que contenha os objetos do módulo ou um comando que obtenha os objetos do módulo, como um comando "Get-Module -listavailable". Você também pode canalizar objetos de módulo para Import-Module.
Necessário? |
true |
Posição? |
1 |
Valor padrão |
|
Aceitar entrada do pipeline? |
true (ByValue) |
Aceitar caracteres curinga? |
false |
-Name <string[]>
Especifica os nomes dos módulos a serem importados. Insira o nome do módulo ou o nome de um arquivo no módulo, como um arquivo .psd1, .psm1, .dll ou ps1. Os caminhos de arquivos são opcionais. Os caracteres curinga não são permitidos. Também é possível 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 variável de ambiente PSModulePath ($env:PSModulePath).
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ê poderá estar perdendo membros importantes do módulo.
Necessário? |
true |
Posição? |
1 |
Valor padrão |
|
Aceitar entrada do pipeline? |
true (ByValue) |
Aceitar caracteres curinga? |
false |
-PassThru
Retorna objetos que representam os módulos importados. Por padrão, este cmdlet não gera nenhuma saída.
Observações
-- Quando você canaliza a saída de um comando "Get-Module -listavailable" para um comando Import-Module com o parâmetro PassThru, Import-Module retorna o objeto que Get-Module passou para ele sem atualizar o objeto. Como resultado, as propriedades Exported e NestedModules ainda não são populadas.
-- Quando você usa o parâmetro Prefix para especificar um prefixo para o membro, o prefixo não aparece nos nomes de membros nas propriedades do objeto do módulo. O objeto registra o que foi exportado antes de o prefixo ser aplicado.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Prefix <string>
Adiciona o prefixo especificado aos substantivos nos nomes de membros de módulo importados.
Use esse parâmetro para evitar conflitos de nomes que podem ocorrer quando membros diferentes na sessão têm o mesmo nome. O parâmetro não altera o módulo e não afeta arquivos que o módulo importa para seu próprio uso (conhecido como "módulos aninhados"). Ele afeta apenas os nomes de membros na sessão atual.
Por exemplo, se você especificar o prefixo "UTC" e importar um cmdlet Get-Date, o cmdlet será conhecido na sessão como Get-UTCDate e não será confundido com o cmdlet Get-Date original.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Variable <string[]>
Importa somente as variáveis especificadas do módulo para a sessão atual. Insira uma lista de variáveis. São permitidos caracteres curinga.
Alguns módulos exportam automaticamente variáveis selecionadas para sua sessão quando você importa o módulo. Esse parâmetro permite que você selecione entre as variáveis exportadas.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
true |
-Version <Version>
Especifica a versão do módulo a ser importada. Use esse parâmetro quando você tiver versões diferentes do mesmo módulo em seu sistema.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
<CommonParameters>
Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.
Entradas e saídas
O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.
Entradas |
System.String, System.Management.Automation.PSModuleInfo, System.Reflection.Assembly Você pode canalizar um nome de módulo, objeto de módulo ou objeto de assembly para Import-Module. |
Saídas |
Nenhum, System.Management.Automation.PSModuleInfo ou System.Management.Automation.PSCustomObject Por padrão, Import-Module não gera saída. Se você usar o parâmetro PassThru, ele gerará um objeto System.Management.Automation.PSModuleInfo que representa o módulo. Se você usar o parâmetro AsCustomObject, ele gerará um objeto PSCustomObject. |
Observações
Também é possível fazer referência a Import-Module usando seu alias, "ipmo". Para obter mais informações, consulte about_Aliases.
Para que você possa importar um módulo, o diretório do módulo deve ser copiado para um diretório que seja acessível no computador local. Para obter mais informações, consulte about_Modules.
Membros de módulo são executados em seu próprio estado de sessão de módulo particular; portanto, os comandos que eles usam para processamento interno não afetam seu estado de sessão.
Se você importar membros com o mesmo nome e o mesmo tipo em sua sessão, o Windows PowerShell usará o membro importado por último por padrão. Variáveis e aliases são substituídos, e os originais não estão acessíveis. Funções, cmdlets e provedores são simplesmente "ocultados" pelos novos membros, e podem ser acessados por meio da qualificação do nome de comando com o nome de seu snap-in, módulo ou caminho de função.
Para atualizar os dados de formatação para comandos que foram importados de um módulo, use o cmdlet Update-FormatData. Update-FormatData também atualiza os dados de formatação para comandos da sessão que foram importados de módulos. Se o arquivo de formatação para um módulo for alterado, você poderá executar um Update-FormatData comando para atualizar os dados de formatação para comandos importados. Você não precisa importar o módulo novamente.
Para importar um módulo que é criado por Import-PSSession ou Export-PSSession, a diretiva de execução na sessão atual não pode ser Restricted ou AllSigned, pois os módulos que Import-PSSession e Export-PSSession criam contêm arquivos de script não assinados que são proibidos por essas diretivas. Para usar Import-Module sem alterar a diretiva de execução para o computador local, use o parâmetro Scope de Set-ExecutionPolicy para definir uma diretiva de execução menos restritiva para um único processo.
Exemplo 1
C:\PS>import-module -name BitsTransfer
Descrição
-----------
Esse comando importa os membros do módulo BitsTransfer para a sessão atual.
O nome do parâmetro Name (-Name) é opcional e pode ser omitido.
Por padrão, Import-Module não gera saída quando importa um módulo. Para solicitar a saída, use o parâmetro PassThru ou AsCustomObject, ou o parâmetro comum Verbose.
Exemplo 2
C:\PS>get-module -listAvailable | import-module
Descrição
-----------
Esse comando importa todos os módulos disponíveis no caminho especificado pela variável de ambiente PSModulePath ($env:psmodulepath) para a sessão atual.
Exemplo 3
C:\PS>$m = get-module -ListAvailable BitsTransfer, ServerBackup
C:\PS> import-module -moduleInfo $m
Descrição
-----------
Esses comandos importam os membros dos módulos BitsTransfer e ServerBackup para a sessão atual.
O primeiro comando usa o cmdlet Get-Module para obter objetos PSModuleInfo que representam os módulos BitsTransfer e ServerBackup. Ele salva os objetos na variável $m. O parâmetro ListAvailable é necessário quando você está obtendo módulos que ainda não foram importados para a sessão.
O segundo comando usa o parâmetro ModuleInfo de Import-Module para importar os módulos para a sessão atual.
Esses comandos são equivalentes a usar um operador de pipeline (|) para enviar a saída de um comando Get-Module para Import-Module.
Exemplo 4
C:\PS>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-parm'.
VERBOSE: Exporting function 'get-spec'.
VERBOSE: Exporting function 'get-specDetails'.
Descrição
-----------
Esse comando usa um caminho explícito para identificar o módulo a ser importado.
Também usa o parâmetro comum Verbose para obter uma lista de itens importados do módulo. Sem o parâmetro Verbose, PassThru ou AsCustomObject, Import-Module não gera saída quando importa um módulo.
Exemplo 5
C:\PS>import-module BitsTransfer -cmdlet Add-BitsTransferFile, Get-BitsTransfer
C:\PS> get-module BitsTransfer
Name : BitsTransfer
Path : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\BitsTransfer\BitsTransfer.psd1
Description :
Guid : 8fa5064b-8479-4c5c-86ea-0d311fe48875
Version : 1.0.0.0
ModuleBase : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\BitsTransfer
ModuleType : Manifest
PrivateData :
AccessMode : ReadWrite
ExportedAliases : {}
ExportedCmdlets : {[Add-BitsTransfer, Add-BitsTransfer], [Complete-BitsTransfer, Complete-BitsTransfer], [Get-BitsTransfer, Get-BitsTransfer], [Rem
ove-BitsTransfer, Remove-BitsTransfer]...}
ExportedFunctions : {}
ExportedVariables : {}
NestedModules : {Microsoft.BackgroundIntelligentTransfer.Management}
C:\PS> get-command -module BitsTransfer
CommandType Name Definition
----------- ---- ----------
Cmdlet Add-BitsTransfer Add-BitsTransfer [-BitsJob] <BitsJob[]> [-Source] <String[]> [[-Destination] <String[]>] [-Verbose] [-Debug] [-ErrorA...
Cmdlet Get-BitsTransfer Get-BitsTransfer [[-Name] <String[]>] [-AllUsers] [-Verbose] [-Debug] [-ErrorAction <ActionPreference>] [-WarningActi...
Descrição
-----------
Este exemplo mostra como restringir os membros de módulo que são importados para a sessão e o efeito desse comando na sessão.
O primeiro comando importa somente os cmdlets Add-BitsTransfer e Get-BitsTransfer do módulo BitsTransfer. O comando usa o parâmetro Cmdlet para restringir os cmdlets que o módulo importa. Você também pode usar os parâmetros Alias, Variable e Function para restringir outros membros que um módulo importa.
O segundo comando usa o cmdlet Get-Module para obter o objeto que representa o módulo BitsTransfer. A propriedade ExportedCmdlets lista todos os cmdlets que o módulo exporta, até quando eles não foram todos importados.
O terceiro comando usa o parâmetro Module do cmdlet Get-Command para obter os comandos que foram importados do módulo BitsTransfer. Os resultados confirmam que somente os cmdlets Add-BitsTransfer e Get-BitsTransfer foram importados.
Exemplo 6
C:\PS>import-module BitsTransfer -prefix PS -passthru
Name : bitstransfer
Path : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\bitstransfer\bitstransfer.psd1
Description :
Guid : 8fa5064b-8479-4c5c-86ea-0d311fe48875
Version : 1.0.0.0
ModuleBase : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\bitstransfer
ModuleType : Manifest
PrivateData :
AccessMode : ReadWrite
ExportedAliases : {}
ExportedCmdlets : {[Add-BitsTransfer, Add-BitsTransfer], [Remove-BitsTransfer, Remove-BitsTransfer], [Complete-BitsTransfer, Complete-BitsTransfer]
, [Get-BitsTransfer, Get-BitsTransfer]...}
ExportedFunctions : {}
ExportedVariables : {}
NestedModules : {Microsoft.BackgroundIntelligentTransfer.Management}
C:\PS> get-command -module bitstransfer
CommandType Name Definition
----------- ---- ----------
Cmdlet Add-PSBitsTransfer Add-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Source] <String[]> ...
Cmdlet Complete-PSBitsTransfer Complete-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Verbose] [-Deb...
Cmdlet Get-PSBitsTransfer Get-PSBitsTransfer [[-Name] <String[]>] [-AllUsers] [-Verbose] ...
Cmdlet Remove-PSBitsTransfer Remove-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Verbose] [-Debug...
Cmdlet Resume-PSBitsTransfer Resume-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Asynchronous] [-...
Cmdlet Set-PSBitsTransfer Set-PSBitsTransfer [-BitsJob] <BitsJob[]> [-DisplayName <String...
Cmdlet Start-PSBitsTransfer Start-PSBitsTransfer [[-Source] <String[]>] [[-Destination] <St...
Cmdlet Suspend-PSBitsTransfer Suspend-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Verbose] [-Debu...
Descrição
-----------
Esses comandos importam o módulo BitsTransfer para a sessão atual, adicionam um prefixo aos nomes de membros e exibem os nomes de membros com os prefixos.
O primeiro comando usa o cmdlet Import-Module para importar o módulo BitsTransfer. Ele usa o parâmetro Prefix para adicionar o prefixo PS a todos os membros importados do módulo e o parâmetro PassThru para retornar um objeto do módulo que represente o módulo importado.
O objeto do módulo que o comando retorna tem uma propriedade ExportedCmdlets que lista os membros exportados. O prefixo não aparece nos nomes de cmdlet, pois é aplicado depois que os membros são exportados (mas antes de serem importados).
O segundo comando usa o cmdlet Get-Command para obter os membros que foram importados do módulo. Ele usa o parâmetro Module para especificar o módulo. A saída mostra que os membros do módulo tiveram o prefixo colocado corretamente.
O prefixo que você usa se aplica apenas aos membros da sessão atual. Ele não é altera o módulo.
Exemplo 7
C:\PS>get-module -list | format-table -property name, moduletype -auto
Name ModuleType
---- ----------
Show-Calendar Script
BitsTransfer Manifest
PSDiagnostics Manifest
TestCmdlets Script
C:\PS> $a = import-module -name Show-Calendar -asCustomObject
C:\PS> $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();
C:\PS> $a."show-calendar"()
Descrição
-----------
Esses comandos demonstram como obter e usar o objeto personalizado que Import-Module retorna.
Objetos personalizados incluem membros sintéticos que representam cada um dos membros de módulo importados. Por exemplo, os cmdlets e as funções em um módulo são convertidos em métodos de script do objeto personalizado.
Objetos personalizados são muito úteis na elaboração de 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, inclusive seu nome de módulo.
O parâmetro AsCustomObject só pode ser usado com um módulo de script. Assim, a primeira tarefa é determinar qual dos módulos disponíveis é um módulo de script.
O primeiro comando usa o cmdlet Get-Module para obter os módulos disponíveis. O comando usa um operador de pipeline (|) para transmitir os objetos do módulo para o cmdlet Format-Table, que lista Name e ModuleType de cada módulo em uma tabela.
O segundo comando usa o cmdlet Import-Module para importar o módulo de script Show-Calendar. O comando usa o parâmetro AsCustomObject para solicitar um objeto personalizado. O comando salva o objeto personalizado resultante na variável $a.
O terceiro comando usa um operador de pipeline para enviar a variável $a para o cmdlet Get-Member, que obtém as propriedades e os métodos de PSCustomObject em $a. A saída mostra um método de script Show-Calendar.
O último comando usa o método de script Show-Calendar. O nome do método deve estar entre aspas, porque inclui um hífen.
Exemplo 8
C:\PS>import-module BitsTransfer
C:\PS> import-module BitsTransfer -force -prefix PS
Descriçã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 primeiro comando importa o módulo BitsTransfer. O segundo comando importa o módulo novamente, desta vez usando o parâmetro Prefix.
O segundo comando também inclui o parâmetro Force, que remove o módulo e, em seguida, importa-o novamente. Sem esse parâmetro, a sessão incluiria duas cópias de cada cmdlet de BitsTransfer, uma com o nome padrão e uma com o nome com o prefixo.
Exemplo 9
C:\PS>get-date
Saturday, September 12, 2009 6:47:04 PM
C:\PS> import-module TestModule
C:\PS> get-date
09255
C:\PS> get-command get-date | format-table -property commandtype, name, pssnapin, module -auto
CommandType Name pssnapin Module
----------- ---- -------- ------
Function Get-Date TestModule
Cmdlet Get-Date Microsoft.PowerShell.Utility
C:\PS> Microsoft.PowerShell.Utility\get-date
Saturday, September 12, 2009 6:33:23 PM
Descrição
-----------
Este exemplo mostra como executar comandos que foram ocultados por comandos importados.
O primeiro comando executa o cmdlet Get-Date que vem com o Windows PowerShell. Ele retorna um objeto DateTime com a data atual.
O segundo comando importa o módulo TestModule. Esse módulo inclui uma função denominada Get-Date, que retorna a data no calendário juliano.
O terceiro comando executa o comando Get-Date novamente. Como as funções têm precedência sobre os cmdlets, a função Get-Date do módulo TestModule é executada, em vez do cmdlet Get-Date.
O quarto comando mostra que há dois comandos Get-Date na sessão, uma função do módulo TestModule e um cmdlet do snap-in Microsoft.PowerShell.Utility.
O quinto comando executa o cmdlet oculto qualificando o nome do comando com o nome do snap-in.
Para obter mais informações a precedência de comandos no Windows PowerShell, consulte about_command_precedence.
Consulte também
Conceitos
Get-Module
New-Module
Remove-Module
Export-ModuleMember
about_Modules