Caminho do Módulo PowerShell: Código Reutilizável Sem Copiar e Colar

Trabalhar com módulos do PowerShell é uma peça importante da automação no PowerShell. Quando você começa a aprender PowerShell, os primeiros passos geralmente envolvem o uso de comandos individuais. Isso leva à criação de scripts, que por sua vez leva à criação de funções.

Ao utilizar funções, você pode tornar seus scripts mais modulares. Isso permite que você use o mesmo código em muitos lugares sem copiar e colar o código por toda parte. O uso de funções permite que você gaste menos tempo fazendo a mesma edição no mesmo código onde quer que seja usado. Em vez disso, você pode trabalhar para melhorar seu código em um único lugar.

Para levar as funções para o próximo nível, você pode combinar essas funções em um módulo.

A module is a collection of functions in a text file with a psm1 extension. There are some optional additions, such as a module manifest and comment-based or external help that may also be included. These will be covered later on.

Pré-requisitos

I’ll be using Windows PowerShell 5.1 in this article. If you’re using an older version or PowerShell Core, your mileage may vary as to results you see.

Interagindo com Módulos

Ao abrir uma sessão do PowerShell pela primeira vez, você começará com dois módulos. O primeiro é Microsoft.PowerShell.Utility, que contém muitas funções básicas do PowerShell que você já utiliza. O outro módulo é PSReadline. Você pode ver esses módulos iniciais usando o comando Get-Module.

Dito isso, esta não é uma lista completa de todos os módulos disponíveis. Desde o PowerShell 3, os módulos instalados serão importados conforme necessário. Se estiver usando uma versão mais antiga do PowerShell, será necessário usar o comando Import-Module para primeiro importar o módulo antes de usar qualquer um dos comandos.

Existem momentos em que ainda será desejável usar o Import-Module mesmo em versões mais recentes. Se você quiser importar um módulo depois que ele já estiver instalado, você pode usar o Import-Module assim:

Enquanto Get-Module irá mostrar todos os módulos que estão importados, você não verá os módulos que ainda não foram importados. Você pode então usar o parâmetro ListAvailable para mostrar todos os outros módulos que estão disponíveis.

Nem todos os Comandos são Mostrados Por Padrão

A propriedade ExportedCommands contém uma lista de todos os comandos disponíveis que são exportados do módulo. Você pode ver algumas diferenças entre esta lista e o que está no arquivo do módulo. Comandos exportados são uma funcionalidade incorporada ao manifesto do módulo que permite ao autor deixar uma função como oculta. Os autores de módulos também podem usar o Export-ModuleMember cmdlet, mas isso está fora do escopo deste artigo.

Os autores de módulos podem querer ter uma função oculta porque ela é destinada a dar suporte a outras funções, não ser visível para o usuário. Para ter uma função oculta, o autor excluiria ela do FunctionsToExport array no manifesto. Aqui você pode ver uma visualização expandida da propriedade ExportedCommands.

Importando Módulos

Existem muitas maneiras de começar a usar módulos. Você pode importar manualmente o módulo usando o caminho para os arquivos do módulo. Isso permite que você teste e atualize o módulo sem ter que fazer muito trabalho. Mas isso não permite muita portabilidade, já que você teria que usar o caminho exato para o módulo. O PowerShell também não importará automaticamente módulos que não estão na variável $env:PSModulePath.

Importando Comandos Seletivamente

Você pode usar Import-Module para importar apenas funções específicas em vez do módulo inteiro, usando o parâmetro Function. Isso pode economizar tempo ao importar módulos de sistemas remotos, como os módulos do Office 365.

Todos os Módulos de Usuários

Os módulos instalados para todos os usuários são colocados em C:\Program Files\WindowsPowerShell\Modules. Este diretório contém muitos módulos pré-adicionados, incluindo quaisquer módulos instalados usando Install-Module com o escopo padrão AllUsers.

Módulos do Usuário Atual

Se você estiver instalando um módulo, mas deseja que apenas um usuário o use, há um escopo CurrentUser. Isso coloca os arquivos do módulo na sua pasta Documents em C:\Users\<username>\Documents\WindowsPowerShell\Modules. Isso pode ser útil em um ambiente onde você usa redirecionamento de pasta com a pasta Documents.

Neste caso, você pode instalar um módulo em um computador e usá-lo em outro, já que ambos estarão compartilhando a mesma pasta de documentos.

Módulos do Sistema

Para completação, há também um diretório de módulos em C:\Windows\System32\WindowsPowerShell\1.0\Modules. Embora tecnicamente um módulo colocado neste caminho seja importado como os outros, não é recomendado, pois é reservado para os módulos do sistema da Microsoft.

A Nomenclatura é Importante

Você pode colocar manualmente seu módulo em um desses caminhos para torná-lo disponível por padrão em uma nova sessão, mas deve garantir que siga a nomenclatura necessária para os módulos. A pasta em que os arquivos do módulo são colocados deve ter o mesmo nome do arquivo do módulo psm1 e do manifesto do módulo psd1, se houver.

Usar Get-Module -ListAvailable, como mencionamos antes, faz referência a esses caminhos. Você pode ver todos os caminhos do módulo usando $env:PSModulePath -Split ';'. Você pode notar outros caminhos na lista que não são mostrados aqui. Muitos programas adicionam seus próprios caminhos de módulo durante a instalação. Um exemplo disso é o SQL, que possui seus próprios módulos incluídos em seus próprios caminhos de módulo.

Há também alguns módulos que você instalaria com um processo diferente. Um dos exemplos mais significativos disso é o módulo ActiveDirectory. Do Windows 7 até o Windows 10 1803, você o instalava com o instalador das Ferramentas de Administração do Servidor Remoto (RSAT).

Nas versões mais recentes do Windows 10 (1809+), isso só está disponível por meio do recurso Features On Demand. A instalação do RSAT instala os módulos ActiveDirectory e muitos outros que você usaria para administrar outras funções do Windows. Nos sistemas operacionais Windows Server, esses módulos são instalados por meio do Gerenciador do Servidor.

Importação de Módulos Remotos (Remoting Implícito)

Existem alguns casos em que não é prático ter um módulo em execução localmente. Em vez disso, é melhor conectar-se a um dispositivo remoto e importar um módulo instalado nele. Quando você faz isso, os comandos são realmente executados na máquina remota. Isso é frequentemente usado com os módulos do Office 365 da Microsoft. Muitos deles se conectam a um servidor do Office 365 que então importa um módulo. Quando você executa qualquer um dos comandos, eles são executados no servidor remoto e depois a saída é enviada de volta para a sua sessão.

Outro uso da importação de módulos remotos é quando você não tem o módulo instalado localmente. Isso é o que aconteceria se você não tivesse o módulo ActiveDirectory instalado, mas tentasse importá-lo.

Para importar um módulo remoto, primeiro você precisa criar uma PSSession. Você pode usar New-PSSession para criar a sessão. Em seguida, você importaria o módulo disponível no dispositivo remoto usando o parâmetro PSSession com Import-Module.

PS51> $AdminServer = New-PSSession -ComputerName $AdminServerName -Credential (Get-Credential)
PS51> Import-Module -Name ActiveDirectory -PSSession $AdminServer -Prefix 'Rmt'

O uso desse método de importação de módulos remotos permite uma execução de código mais rápida em um ambiente distribuído. Por exemplo, se você estiver trabalhando do seu computador, mas os servidores nos quais você está trabalhando estiverem nos EUA, pode levar significativamente mais tempo para executar certos comandos localmente nos servidores. Enquanto executar os comandos em um servidor e enviar a saída de volta para a sua sessão local é muito mais rápido.

Adicionando um Prefixo de Módulo

Você também pode adicionar um prefixo nas funções importadas da máquina remota. Essa opção está disponível ao importar módulos locais, mas raramente é usada fora dos testes de diferentes versões de um módulo lado a lado.

Se você executar o comando de importação acima e isso é o que você verá ao examinar os comandos:

Nesse caso, você pode usar um prefixo para mostrar que não é um módulo local. Isso pode ser usado em casos em que você está importando um módulo que também está disponível localmente. Adicionar o prefixo reduz a confusão sobre onde o código está sendo executado.

Removendo Módulos

Você também pode remover um módulo da sessão atual sem usar Remove-Module. Isso remove um módulo da sessão local sem remover os arquivos do módulo. Você pode querer usar isso em um caso em que estava usando uma sessão remota para usar um módulo. Você poderia usar Remove-Module para limpar sua sessão e depois desconectar a sessão remota.

Outro uso de Remove-Module é se você estiver fazendo alterações em um módulo e não quiser iniciar uma nova sessão do PowerShell. Nesse caso, você usaria Remove-Module seguido por Import-Module para recarregá-lo em sua sessão. Alternativamente, você pode usar o parâmetro Force com Import-Module. Isso completará a descarga e recarga do módulo para você.

O Que Compõe um Módulo do PowerShell

A module can consist of one or more files. To meet the minimum requirements for a module, you must have a module file. This can be a PSM1 file or any other module file such as a binary module file. To build upon that, your psm1 should have functions defined in it, or it will not be much use to anyone.

Embora não haja requisitos sobre como devem ser as funções ou o que devem fazer, existem algumas diretrizes. Geralmente, é preferível ter todas as funções em um módulo construído em torno do mesmo conceito.

Os Módulos Contêm Funções Semelhantes

Por exemplo, o módulo ActiveDirectory inclui apenas funções que interagem de alguma forma com o Active Directory. Geralmente, os nomes das funções também contêm um prefixo. Voltando ao módulo ActiveDirectory como exemplo, todos os substantivos nos nomes das funções começam com AD.

O uso dessas diretrizes ajuda na descoberta das funções. Imagine que você acabou de importar este novo módulo e deseja navegar pelas funções. Isso é muito mais fácil de fazer se todas as funções tiverem uma estrutura de nome semelhante. Embora você frequentemente veja módulos começando com PS, este prefixo é oficialmente reservado apenas para os módulos da Microsoft. Provavelmente você não causará problemas se usar PS no início do seu módulo, mas pode criar um conflito com outro nome de módulo.

Usando essas diretrizes, se você tivesse um monte de funções que todas se relacionassem com a interação com o registro, você poderia ter algo como:

function Get-ATARegistryKey {...}

function Set-ATARegistryKey {...}

Manifestos de Módulos

Para complementar o arquivo de módulo de texto, você também pode incluir um manifesto de módulo. Esses arquivos têm uma extensão PSD1 e contêm metadados sobre o módulo. Aqui é onde você incluiria informações sobre o autor, descrição do módulo, outros módulos necessários e muitos outros atributos. Para publicar em um repositório, é necessário preencher os campos Author e Description.

Aqui está um exemplo de um manifesto que podemos ter para o nosso módulo de registro:

#Manifesto do módulo para o módulo 'ATARegistry'
#Gerado por: Tyler
#Gerado em: 11/08/2019
@{
	#Módulo de script ou arquivo binário associado a este manifesto.
	RootModule = 'ATARegistry'
	#Número da versão deste módulo.
	ModuleVersion = '1.0'
	#Edições do PowerShell suportadas
	#EdiçõesCompatíveis = @()
	#ID usado para identificar exclusivamente este módulo
	GUID = 'fef619fa-016d-4b11-a09d-b222e094de3e'
	#Autor deste módulo
	Author = 'Tyler Muir'
	#Empresa ou fornecedor deste módulo
	CompanyName = 'Adam the Automator'
	#Declaração de direitos autorais para este módulo
	Copyright = '(c) 2019 tyler. All rights reserved.'
	#Descrição da funcionalidade fornecida por este módulo
	Description = 'This is a test module.'
	#Versão mínima do mecanismo do Windows PowerShell necessária para este módulo
	#VersãoPowerShell = ''
	#Nome do host do Windows PowerShell necessário para este módulo
	#NomePowerShellHost = ''
	#Versão mínima do host do Windows PowerShell necessária para este módulo
	#VersãoHostPowerShell = ''
	#Versão mínima do Microsoft .NET Framework necessária para este módulo. Este pré-requisito é válido apenas para a edição PowerShell Desktop.
	#VersãoDotNetFramework = ''
	#Versão mínima do tempo de execução da linguagem comum (CLR) necessária para este módulo. Este pré-requisito é válido apenas para a edição PowerShell Desktop.
	#VersãoCLR = ''
	#Arquitetura do processador (None, X86, Amd64) necessária para este módulo
	#ArquiteturaProcessador = ''
	#Módulos que devem ser importados no ambiente global antes de importar este módulo
	#MódulosNecessários = @()
	#Assemblies que devem ser carregados antes de importar este módulo
	#AssembliesNecessárias = @()
	#Arquivos de script (.ps1) que são executados no ambiente do chamador antes de importar este módulo.
	#ScriptsParaProcessar = @()
	#Arquivos de tipo (.ps1xml) a serem carregados ao importar este módulo
	#TiposParaProcessar = @()
	#Arquivos de formato (.ps1xml) a serem carregados ao importar este módulo
	#FormatosParaProcessar = @()
	#Módulos para importar como módulos aninhados do módulo especificado em RootModule/ModuleToProcess
	#MódulosAninhados = @()
	#Funções para exportar deste módulo, para melhor desempenho, não use curingas e não exclua a entrada, use uma matriz vazia se não houver funções para exportar.
	FunctionsToExport = @('Get-RegistryKey','Set-RegistryKey')
	#Cmdlets para exportar deste módulo, para melhor desempenho, não use curingas e não exclua a entrada, use uma matriz vazia se não houver cmdlets para exportar.
	CmdletsToExport = @()
	#Variáveis para exportar deste móduloVariáveisParaExportar = '*'
	#Aliases para exportar deste módulo, para melhor desempenho, não use curingas e não exclua a entrada, use uma matriz vazia se não houver aliases para exportar.
	AliasesToExport = @()
	#Recursos DSC para exportar deste módulo
	#RecursosDscParaExportar = @()
	#Lista de todos os módulos empacotados com este módulo
	#ListaMódulos = @()
	#Lista de todos os arquivos empacotados com este módulo
	#ListaArquivos = @()
	#Dados privados para passar ao módulo especificado em RootModule/ModuleToProcess. Isso também pode conter um hashtable PSData com metadados adicionais do módulo usados pelo PowerShell.
	PrivateData = @{
		PSData = @{
			#Tags aplicadas a este módulo. Estas ajudam na descoberta do módulo em galerias online.
			#Tags = @()
			#URL para a licença deste módulo.
			#UriLicença = ''
			#URL principal para este projeto.
			#UriProjeto = ''
			#URL para um ícone representando este módulo.
			#UriÍcone = ''
			#Notas de lançamento deste módulo
			#NotasLançamento = ''
		} 
		#Fim do hashtable PSData
	} 
	#Fim do hashtable PrivateData
	#URI de informações de ajuda deste módulo
	#UriInformaçõesAjuda = ''
	#Prefixo padrão para comandos exportados deste módulo. Substitua o prefixo padrão usando Import-Module -Prefixo.
	#PrefixoComandoPadrão = ''
}

Embora isso possa parecer intimidante à primeira vista, a Microsoft possui um cmdlet útil que você pode usar para gerar um manifesto de módulo. O comando incluído é New-ModuleManifest. Para gerar o manifesto mostrado acima, você poderia usar:

PS51> New-ModuleManifest -Path .\Scripts\TestModule.psd1 -Author 'Tyler Muir' -CompanyName 'Adam the Automator' -RootModule 'TestModule.psm1' -FunctionsToExport @('Get-RegistryKey','Set-RegistryKey') -Description 'This is a test module.'

Arquivos de Ajuda Externos

Você também pode encontrar arquivos de ajuda externos em alguns módulos. Eles podem ser identificados pelo <ModuleName>-Help.xml no final do nome do arquivo. Esses arquivos de ajuda externos contêm as mesmas informações que normalmente seriam encontradas na ajuda baseada em comando que você pode encontrar em uma definição de função.

Isso também exigiria que você adicionasse # .ExternalHelp <ModulePath>-Help.xml à sua função para que ela funcione corretamente ao usar o comando Get-Help após importar o módulo. Normalmente, é comum ver arquivos de ajuda externos em módulos muito grandes e, devido a isso, eles estão fora do escopo.

Arquivos Relacionados

Embora esses sejam os tipos mais comuns de arquivos que você verá em um módulo, não são os únicos arquivos. Às vezes, você verá arquivos binários além de um módulo de texto, pois existem outras dependências. Ao explorar os caminhos do módulo, você pode encontrar muitos exemplos de tipos de arquivo adicionais em módulos.

Para publicar corretamente arquivos de módulo não padrão, você incluiria outros arquivos no parâmetro FileList em seu manifesto de módulo.

Dentro do manifesto do módulo, você notará muitos outros parâmetros que estão atualmente vazios. Você pode usar estes para definir outros requisitos para usar seu módulo. Por exemplo, você pode definir as versões do PowerShell com as quais o módulo pode funcionar. Se você tentar importar o módulo em uma versão não suportada do PowerShell, é isso que você veria:

PSRepositories

Uma das principais opções de distribuição para módulos é um PSRepository. Em uma visão geral, um PSRepository é um local onde várias pessoas ou vários dispositivos podem acessar os arquivos do módulo. Estes são frequentemente servidores web onde você pode publicar arquivos.

Você também pode usar um diretório para o repositório, mas isso limita a funcionalidade do seu repositório. Você pode hospedar um PSRepository você mesmo, ou pode utilizar uma das muitas opções disponíveis na internet como o PowerShell Gallery. Você pode ver seus PSRepositories usando o comando Get-PSRepository.

Por padrão, você terá apenas uma entrada e será para o PowerShell Gallery. Você pode notar que ela será marcada como não confiável. Isso ocorre porque o PowerShell faz você ciente de que ao usar o PowerShell Gallery você pode estar usando código não escrito e aprovado pela Microsoft. Isso significa que antes que quaisquer módulos sejam instalados dele, você terá que dar permissão explícita.

Adicionando PSRepositories

Você também pode adicionar seus próprios repositórios. Para confiar no PowerShell Gallery, você pode executar Get-PSRepository -Name PSGallery | Set-PSRepository -InstallationPolicy Trusted ou você pode aceitar o aviso na primeira vez que instalar um módulo do PowerShell Gallery.

Todos os comandos que você usaria para interagir com esses **PSRepositories** podem ser encontrados no módulo **PowerShellGet**. Você pode ver as funções aqui: **

**. O módulo PowerShellGet pode ser necessário ser atualizado antes de interagir com certos repositórios. **

**.

Encontrando Módulos **

**.

Outro recurso chave de usar um **PSRepository** é poder procurar por módulos. Isso é feito usando o comando **`Find-Module`**. Existem várias maneiras de filtrar para encontrar especificamente o que você está procurando, mas por enquanto você pode pesquisar pelos módulos da VMware assim: **

**.

Isso mostrará todos os módulos que começam com VMware. Embora a maioria deles seja da VMware, você precisa olhar para o atributo do autor para ver quem publicou o módulo. **

**.

Como qualquer pessoa pode fazer upload para o PowerShell Gallery, existem milhares de módulos disponíveis. Isso significa que você pode encontrar módulos que não funcionam corretamente para o seu caso de uso. Muitos dos módulos que você encontrará são de código aberto, então você pode contribuir para melhorar a funcionalidade do módulo. **

**.

Instalando Módulos **

**.

Para usar o comando **`Install-Module`**, você precisa ter um **PSRepository** confiável que esteja hospedando o módulo. Isso pode ser o PowerShell Gallery, outro **PSRepository** da internet, ou um site auto-hospedado. Você pode encadear a saída do comando **`Find-Module`** para confirmar facilmente o módulo antes de instalá-lo. **

**.

Você também pode definir a versão de um módulo usando os parâmetros **`MinimumVersion`**, **`MaximumVersion`**, ou **`RequiredVersion`**.

Para ver todos os módulos instalados usando Install-Module, você pode usar Get-InstalledModule. Isso listará todos os módulos instalados no escopo AllUsers ou no seu escopo CurrentUser.

Desinstalando Módulos

Assim como você pode instalar um módulo, também pode desinstalar um módulo. Se o módulo não foi instalado via comando Install-Module, você não pode desinstalá-lo com o comando Uninstall-Module.

Como você pode ver aqui, estamos tentando desinstalar o módulo ActiveDirectory. Como este módulo não foi instalado com Install-Module, você receberia um erro ao tentar usar Uninstall-Module. Para desinstalar este módulo, seria necessário fazer o processo reverso do que você usou para instalá-lo.

Para ver uma desinstalação bem-sucedida de um módulo, você pode desinstalar o módulo VMware.PowerCLI que você instalou anteriormente.

Mesmo que você tenha desinstalado VMware.PowerCLI, você pode ver que ainda existem muitas dependências instaladas. Se você quisesse desinstalar todos os módulos, poderíamos usar Get-InstalledModule VMware.* | Uninstall-Module -Force.

A razão pela qual você teria dificuldades em desinstalar completamente este módulo é porque ele tem muitas dependências. Além disso, alguns desses módulos são dependentes entre si, razão pela qual o parâmetro Force seria necessário.

Atualizando Módulos

Agora que você sabe como instalar e desinstalar um módulo, pode estar se perguntando como atualizar um módulo que você instalou.

Assim como outros processos, se o módulo não foi instalado usando Install-Module, não é possível atualizá-lo usando os comandos do PowerShell. Você pode usar Update-Module para atualizar um módulo para a versão mais recente ou para uma versão específica mais recente.

Também há uma opção AllowPreRelease que permite atualizar para uma versão que ainda não foi lançada oficialmente. Às vezes, isso pode ser útil, pois pode haver uma correção para um bug que você está enfrentando ou um novo recurso que foi adicionado e que você gostaria de usar.

Inspecionando/Salvando um Módulo

Um dos comandos menos usados, mas muito útil ao avaliar módulos antes de usá-los, é o Save-Module. Usando esse comando, você pode baixar um módulo para um caminho sem instalá-lo.

Em seguida, você pode inspecionar os arquivos e, se o módulo não for um módulo binário, pode abri-lo e examinar o código que o compõe. Isso pode ser útil não apenas para garantir que um módulo não esteja realizando nenhuma atividade maliciosa, mas também para aprender como outras pessoas estão estruturando seus módulos.

Neste exemplo, não apenas o módulo VMware.PowerCLI é baixado, mas também todas as dependências. Aqui está o que é exibido na pasta VMware.PowerCLI:

Isso é um bom exemplo de como às vezes existem arquivos de módulo não padrão incluídos no módulo, como o contrato de licença do usuário final.

Escrevendo seu próprio Módulo

Agora você viu como interagir com o módulo de outra pessoa. Agora você quer aprender como criar o seu próprio, para começar a otimizar o seu código para escalabilidade.

Criar Arquivos de Modelo

Primeiro, você precisa criar uma pasta para todos os arquivos do seu módulo. Após criar o contêiner, é necessário criar o arquivo do seu módulo. Certifique-se de que o nome do seu arquivo do módulo seja o mesmo que o da sua pasta, caso contrário, ao tentar publicar o módulo, o PowerShell não descobrirá o módulo corretamente.

PS51> New-Item -Path .\Scripts -Name ATARegistry -ItemType Directory
PS51> New-Item -Path .\Scripts\ATARegistry -Name ATARegistry.psm1

Agora você também deseja usar um manifesto, precisará nomeá-lo da mesma forma que o contêiner e o arquivo do módulo.

PS51> New-ModuleManifest -Path .\Scripts\ATARegistry\ATARegistry.psd1 -Author 'Tyler Muir' -CompanyName 'Adam the Automator' -RootModule ATARegistry.psm1 -Description 'Used for interacting with registry keys'

Com o contêiner, arquivo do módulo e arquivo de manifesto, você tem um módulo totalmente funcional. Você pode publicar este módulo em um PSRepository e começar a instalá-lo onde quiser. No entanto, como o arquivo do módulo está vazio, provavelmente não será muito útil. Ainda assim, você pode usar esses arquivos para testar a publicação e garantir que seu repositório funcione.

Registrando um PSRepository

Antes de poder publicar o seu módulo, será necessário adicionar outro PSRepository à sua sessão. Para testes, você pode usar um caminho local como seu PSRepository, pois será fácil de configurar e desmontar.

Normalemente, se você estivesse configurando um PSRepository com um diretório, gostaria de garantir que vários computadores pudessem acessá-lo. Você pode criar um repositório local assim:

PS51> New-Item -Path C:\ -Name Repo -ItemType Directory
PS51> Register-PSRepository -Name 'LocalRepo' -SourceLocation 'C:\Repo' -PublishLocation 'C:\Repo' -InstallationPolicy Trusted

Se você apenas estiver baixando do PSRepository e nunca publicando, poderia excluir o parâmetro PublishLocation.

Publicando seu Módulo

Uma vez que você já definiu a política de instalação como confiável, não receberá uma confirmação para permitir que um módulo seja instalado a partir do repositório. Agora que você tem um novo PSRepository disponível, você pode publicar seu módulo usando Publish-Module -Name .\Scripts\ATARegistry -Repository LocalRepo.

Após publicar seu módulo, você pode usar os comandos acima para encontrar o módulo e instalá-lo.

Agora que você instalou o módulo, pode usar Get-Module para ver o módulo importado em sua sessão local. Como você não adicionou nenhuma função à matriz FunctionsToExport no manifesto, a propriedade ExportedCommands está vazia.

Adicionando ao seu Módulo

Agora que você sabe que pode publicar e instalar seu módulo, pode começar a adicionar alguma funcionalidade a ele. Você poderia adicionar uma função para retornar uma chave de registro para que pareça com isso:

function Get-ATARegistryKey {
    param (
        [string]$Path
    )
    Get-Item $Path
}

Se você deixasse o manifesto como está e tentasse carregar seu novo módulo, encontraria dois problemas. O primeiro é que você receberia um erro afirmando que a versão do seu módulo já existe no seu repositório. Isso ocorre porque você não alterou a versão do módulo no arquivo manifesto.

Exportando Funções do Módulo

O outro problema seria que, após importar o módulo, você ainda não veria funções na propriedade ExportedCommands porque não adicionou sua nova função ao manifesto.

Embora sua função possa ser usada sem listá-la na lista FunctionsToExport, isso tornaria muito mais difícil localizá-la.

Desde que não defina um array vazio, @(), para o seu FunctionsToExport, todas as funções, variáveis e aliases são exportados por padrão.

Para corrigir esses dois problemas, você pode atualizar o arquivo do seu módulo assim:

ModuleVersion = '1.1'
FunctionsToExport = 'Get-RegistryKey'

Agora que você adicionou uma função ao seu módulo e atualizou seu manifesto para refletir essas mudanças, você pode publicar a nova versão do seu módulo usando o mesmo comando que antes.

PS51> Publish-Module -Name .\Scripts\ATARegistry -Repository LocalRepo.

Decidindo Entre FunctionsToExport e Export-ModuleMember

Há dois recursos semelhantes do PowerShell ao exportar membros do módulo. O desafio é decidir entre os dois. Ambos estão corretos, mas um pode funcionar melhor para você, dependendo de suas necessidades.

Quando você deseja controlar dinamicamente quais funções são exportadas, use Export-ModuleMember pois você pode passar uma lista de funções para exportar. Tipicamente, isso é usado ao incluir vários arquivos PS1 de função individual com dot-sourcing. Ao dividir as funções internas em uma pasta privada e as funções exportáveis em uma pasta pública, você pode facilmente exportá-las passando todas as funções públicas para a função Export-ModuleMember.

A few notes about Export-ModuleMember:

• Substitui o comportamento de FunctionsToExport, portanto, se um comando Export-ModuleMember for usado, FunctionsToExport não terá efeito.
• Export-ModuleMember não exporta variáveis e aliases sem definição explícita, ao contrário de FunctionsToExport, que exporta esses valores.
• Múltiplos comandos Export-ModuleMember podem ser usados e eles são acumulativos em vez de ter precedência.

Se você não espera ter alterações na sua lista de funções, usar a configuração FunctionsToExport no manifesto do módulo funciona bem e não requer que você exporte explicitamente variáveis e aliases.

Atualizando seu Módulo

O último passo seria você atualizar o seu módulo na sua sessão para poder usar os arquivos atualizados. Usando Update-Module ATARegistry você baixa a atualização que acabou de publicar no repositório.

Agora você pode ver que tem a nova versão do módulo e pode ver a função que definiu no manifesto.

Construindo Conteúdo de Ajuda

Uma das opções que foi mencionada anteriormente é o sistema de ajuda integrado ao PowerShell. Você provavelmente em algum momento usou Get-Help em uma função. Essas informações podem ser adicionadas de duas formas principais.

A primeira é adicionar ajuda baseada em comentários na definição da função. Esta é geralmente a maneira que muitos escritores de módulos implementam. A outra maneira é usar um arquivo de ajuda externo. Você pode usar o parâmetro Full para mostrar tudo que a ajuda tem a oferecer.

Como você pode ver, realmente não há muitas informações e as poucas informações que você obtém provavelmente não seriam úteis para ninguém.

Você pode adicionar alguma ajuda baseada em comentários ao arquivo do seu módulo para preencher esses campos no sistema de ajuda. Você pode ler sobre todas as opções para ajuda baseada em comentários usando Get-Help about_Comment_Based_Help.

Por agora, você pode atualizar sua função para ficar assim. Esta é uma lista dos parâmetros de ajuda mais comumente usados, mas todos eles ainda são opcionais e existem outros que podem ser adicionados no lugar.

Agora sua função fica assim:

 function Get-RegistryKey {
	<#
	    .SYNOPSIS
	    Retorna a chave do registro usando o caminho fornecido.
	    .DESCRIPTION
	    A função usa o comando Get-Item para retornar as informações de uma chave do registro fornecida.
	    .PARAMETER Path
	    O caminho que será pesquisado para uma chave do registro.
	    .EXAMPLE
	    Get-RegistryKey -Path 'HKLM:\HARDWARE\DESCRIPTION\System'
	    .INPUTS
	    System.String
	    .OUTPUTS
	    Microsoft.Win32.RegistryKey
	    .NOTES
	    Este módulo é um exemplo de como uma função bem documentada poderia ser.
	    .LINK
	
ATA Learning

	#>
	param(
		[string]$Path
	)
	Get-Item $Path
}

Existem alguns parâmetros de ajuda especiais, como .FORWARDHELPTARGETNAME. Essa opção encaminha todas as solicitações de ajuda recebidas para um comando diferente. Isso pode ser usado no caso em que a ajuda deve mostrar as mesmas informações para vários comandos.

Agora que você adicionou a ajuda, você pode atualizar a versão no manifesto do módulo, publicar a nova versão e atualizar a versão instalada para sua sessão, como fez anteriormente.

Se você olhar agora a ajuda para a função, verá que há muito mais informações disponíveis. Essa é uma ótima maneira de incluir documentação sobre como usar as funções, especialmente para alguém que tem menos experiência e pode não ser capaz de entender rapidamente o que o módulo está fazendo ao olhar o código.

No caso de um arquivo de ajuda externa, as informações adicionadas são as mesmas, mas as informações são colocadas em um arquivo separado e vinculadas dentro da função.

Se você olhar no caminho do módulo AllUsers, você pode ver a versão do módulo e todos os arquivos do módulo que você instalou.

Se você voltar para o seu caminho PSRepository C:\Repo que você criou anteriormente, você pode ver um monte de arquivos NUPKG. Haverá um para cada versão que foi publicada. Estes são versões compactadas do que você publicou ao usar Publish-Module.

Resumo

Depois de se familiarizar com o console do PowerShell, PowerShell como linguagem e escrever scripts, construir seus próprios módulos é o último passo. Os módulos permitem que você comece a desenvolver ferramentas úteis no PowerShell. Se projetados e construídos corretamente, criando módulos para um único propósito, inevitavelmente você se encontrará escrevendo menos e menos código ao longo do tempo. Você começará a referenciar suas funções de módulo em mais código e construir a partir daí.

As funções do módulo permitem que você abstraia o código que você se vê repetindo em scripts. Elas representam “rótulos” para referenciar posteriormente no código que podem ser chamados a qualquer momento, em vez de reinventar a roda e tentar descobrir como você já tinha alcançado seu objetivo anteriormente. Os módulos são o “empacotamento” final do código do PowerShell que agrupa código semelhante para evitar desperdiçar tempo em problemas que você já resolveu.