Importar um módulo do PowerShell

Depois de instalar um módulo em um sistema, você provavelmente desejará importar o módulo. Importar é 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 é chamada por um usuário. Observe que ambas as versões pressupõem que você instale seu módulo em um local onde o PowerShell é capaz de 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 usar parâmetros da chamada 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ê precisava registrar e usar snap-ins. No entanto, não é recomendável 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 Import-Module (PowerShell 2.0)

O PowerShell 2.0 usa o cmdlet import-module de apropriadamente nomeado para importar módulos. Quando esse cmdlet é executado, o Windows PowerShell pesquisa 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 estava 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 para fora do módulo e o que está sendo importado para a memória ativa. Exportações e importações restringem o que é exposto ao usuário: a diferença é quem está controlando a visibilidade. Essencialmente, as exportações são controladas por código dentro do módulo. Por outro lado, as importações são controladas pela chamada Import-Module. 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 é usada 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á-lo usando a opção importação/módulo explícita, descrita acima.

As ações a seguir disparam a importação automática de um módulo, também conhecido 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 como descoberta e não dispara 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 para o cmdlet get-command do.

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 todos os módulos aninhados). Os membros exportados do módulo raiz, incluindo todos os membros que foram exportados para o módulo raiz por quaisquer módulos aninhados, são importados para o estado de sessão do chamador.

Os metadados de membros exportados de um módulo têm uma propriedade ModuleName. Essa propriedade é preenchida com o nome do módulo que os exportou.

Aviso

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 Import-Module cmdlet for executado.

Por padrão, o cmdlet Import-Module não retorna nenhum objeto para o pipeline. No entanto, o cmdlet dá 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 de Host de Gravação.

Restringindo 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 todos os 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 exportados, use um manifesto do módulo . Para restringir os membros importados, use os seguintes parâmetros do cmdlet Import-Module.

• Function: esse parâmetro restringe as funções exportadas. (Se você estiver usando um manifesto de módulo, consulte a chave FunctionsToExport.)

• ` cmdlet: esse parâmetro restringe os cmdlets exportados (se você estiver usando um manifesto do módulo, consulte a chave CmdletsToExport).)

• Variável: esse parâmetro restringe as variáveis exportadas (se você estiver usando um manifesto de módulo, consulte a chave VariablesToExport).)

• alias: esse parâmetro restringe os aliases exportados (se você estiver usando um manifesto de módulo, consulte a chave AliasesToExport.)

Consulte Também

escrevendo um módulo do Windows PowerShell