Importing a PowerShell Module (Importar um Módulo do PowerShell)

Depois de instalar um módulo em um sistema, você provavelmente desejará importar o módulo. A importação é o processo que carrega o módulo na memória ativa, para que um usuário possa acessar esse módulo em sua sessão do PowerShell. No PowerShell 2.0, você pode importar um módulo do PowerShell recém-instalado com uma chamada para cmdlet Import-Module. No PowerShell 3.0, o PowerShell é capaz de importar implicitamente um módulo quando uma das funções ou cmdlets no módulo é chamado por um usuário. Observe que ambas as versões pressupõem que você instale o módulo em um local onde o PowerShell possa encontrá-lo; para obter mais informações, consulte Instalando um módulo do PowerShell. Você pode usar um manifesto de módulo para restringir quais partes do módulo são exportadas e pode usar parâmetros da chamada de Import-Module para restringir quais partes são importadas.

Importando um Snap-In (PowerShell 1.0)

Os módulos não existiam no PowerShell 1.0: em vez disso, você tinha que registrar e usar snap-ins. No entanto, não é recomendado que você use essa tecnologia neste momento, pois os módulos geralmente são mais fáceis de instalar e importar. Para obter mais informações, consulte Como criar um snap-in do Windows PowerShell.

Importando um módulo com o Import-Module (PowerShell 2.0)

O PowerShell 2.0 usa o cmdlet Import-Module de nome apropriado para importar módulos. Quando esse cmdlet é executado, o Windows PowerShell procura o módulo especificado nos diretórios especificados na variável PSModulePath. Quando o diretório especificado é encontrado, o Windows PowerShell procura arquivos na seguinte ordem: arquivos de manifesto do módulo (.psd1), arquivos de módulo de script (.psm1), arquivos de módulo binário (.dll). Para obter mais informações sobre como adicionar diretórios à pesquisa, consulte about_PSModulePath. O código a seguir descreve como importar um módulo:

Import-Module myModule

Supondo que myModule estivesse localizado no PSModulePath, o PowerShell carregaria myModule na memória ativa. Se myModule não estiver localizado em um caminho PSModulePath, você ainda poderá dizer explicitamente ao PowerShell onde encontrá-lo:

Import-Module -Name C:\myRandomDirectory\myModule -Verbose

Você também pode usar o parâmetro -Verbose para identificar o que está sendo exportado do módulo e o que está sendo importado para a memória ativa. Tanto as exportações quanto as importações restringem o que é exposto ao usuário: a diferença é quem controla a visibilidade. Essencialmente, as exportações são controladas por código dentro do módulo. Em contrapartida, as importações são controladas pelo Import-Module call. Para obter mais informações, consulte restringindo membros importados, abaixo.

Importando implicitamente um módulo (PowerShell 3.0)

A partir do Windows PowerShell 3.0, os módulos são importados automaticamente quando qualquer cmdlet ou função no módulo é usado em um comando. Esse recurso funciona em qualquer módulo em um diretório incluído no valor da variável de ambiente PSModulePath. No entanto, se você não salvar o módulo em um caminho válido, ainda poderá carregá-los usando a opção explícita Import-Module, descrita acima.

As ações a seguir acionam a importação automática de um módulo, também conhecida como "carregamento automático do módulo".

• Usando um cmdlet em um comando. Por exemplo, digitar Get-ExecutionPolicy importa o módulo Microsoft.PowerShell.Security que contém o cmdlet Get-ExecutionPolicy.

• Usando o cmdlet Get-Command para obter o comando. Por exemplo, digitar Get-Command Get-JobTrigger importa o módulo PSScheduledJob que contém o cmdlet Get-JobTrigger. Um comando Get-Command que inclui caracteres curinga é considerado descoberta e não aciona a importação de um módulo.

• Usando o cmdlet Get-Help para obter ajuda para um cmdlet. Por exemplo, digitar Get-Help Get-WinEvent importa o módulo Microsoft.PowerShell.Diagnostics que contém o cmdlet Get-WinEvent.

Para dar suporte à importação automática de módulos, o cmdlet Get-Command obtém todos os cmdlets e funções em todos os módulos instalados, mesmo que o módulo não seja importado para a sessão. Para obter mais informações, consulte o tópico de ajuda do cmdlet Get-Command.

O processo de importação

Quando um módulo é importado, um novo estado de sessão é criado para o módulo e um objeto System.Management.Automation.PSModuleInfo é criado na memória. Um estado de sessão é criado para cada módulo importado (isso inclui o módulo raiz e quaisquer módulos aninhados). Os membros que são exportados do módulo raiz, incluindo quaisquer membros que foram exportados para o módulo raiz por qualquer módulo aninhado, são então importados para o estado de sessão do chamador.

Os metadados dos membros que são exportados de um módulo têm uma propriedade ModuleName. Esta propriedade é preenchida com o nome do módulo que as exportou.

Advertência

Se o nome de um membro exportado usar um verbo não aprovado ou se o nome do membro usar caracteres restritos, um aviso será exibido quando o cmdlet Import-Module for executado.

Por padrão, o cmdlet Import-Module não retorna nenhum objeto ao pipeline. No entanto, o cmdlet oferece suporte a um parâmetro PassThru que pode ser usado para retornar um objeto System.Management.Automation.PSModuleInfo para cada módulo importado. Para enviar a saída para o host, os usuários devem executar o cmdlet Write-Host.

Restringir os membros importados

Quando um módulo é importado usando o cmdlet Import-Module, por padrão, todos os membros do módulo exportados são importados para a sessão, incluindo quaisquer comandos exportados para o módulo por um módulo aninhado. Por padrão, variáveis e aliases não são exportados. Para restringir os membros que são exportados, use um manifesto de módulo . Para restringir os membros importados, use os seguintes parâmetros do cmdlet Import-Module.

• Função: Este parâmetro restringe as funções que são exportadas. (Se você estiver usando um manifesto de módulo, consulte a chave FunctionsToExport.)

• ` Cmdlet: Este parâmetro restringe os cmdlets que são exportados (Se você estiver usando um manifesto de módulo, consulte a chave CmdletsToExport.)

• Variável: Este parâmetro restringe as variáveis que são exportadas (Se você estiver usando um manifesto de módulo, consulte a chave VariablesToExport.)

• Alias: Este parâmetro restringe os aliases que são exportados (Se você estiver usando um manifesto de módulo, consulte a chave AliasesToExport.)

Ver também

Escrevendo um módulo do Windows PowerShell