Adam o Automador

Trabalhar com módulos PowerShell é uma peça importante da automação PowerShell. Quando você começa a aprender o PowerShell, os primeiros passos normalmente são usando comandos simples. Isto leva a construir scripts que depois levam à construção de funções.

Usando funções, você pode tornar os seus scripts mais modulares. Isto permite que você seja capaz de usar o mesmo código em muitos lugares sem copiar e colar em código por todo o lugar. O uso de funções permite que você passe menos tempo fazendo a mesma edição para o mesmo código em todos os lugares em que ele é usado. Em vez disso você pode trabalhar para melhorar o seu código em um único lugar.

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

Um módulo é uma coleção de funções em um arquivo de texto com uma extensão psm1. Existem algumas adições opcionais, tais como um manifesto de módulo e ajuda baseada em comentários ou ajuda externa que também pode ser incluída. Estes serão abordados mais tarde em.

Pré-requisitos

Estarei usando o Windows PowerShell 5.1 neste artigo. Se estiver a usar uma versão mais antiga ou o PowerShell Core, a sua quilometragem pode variar quanto aos resultados que vê.

Interagindo com Módulos

Após abrir primeiro uma sessão PowerShell, irá começar com dois módulos. O primeiro é o Microsoft.PowerShell.Utility que contém muitas funções PowerShell básicas que você já usa. O outro módulo é o PSReadline. Você pode ver estes módulos iniciais usando o comando Get-Module>

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

Há alturas em que ainda gostaria de usar Import-Module mesmo em versões posteriores. Se quiser importar um módulo depois de já estar instalado, pode utilizar Import-Module assim:

Embora Get-Module mostre todos os módulos que são importados, não verá módulos que ainda não tenham sido 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 defeito

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 é uma característica incorporada no manifesto do módulo que permite ao escritor deixar uma função como oculta. Os autores de módulos também podem usar a Export-ModuleMember cmdlet mas isso está fora do escopo deste artigo.

Os autores de módulos podem querer ter uma função escondida porque ela é destinada a suportar outras funções, não a ser voltada para o usuário. Para ter uma função escondida o autor a excluiria da matriz FunctionsToExport no manifesto. Aqui você pode ver uma vista expandida da ExportedCommands propriedade.

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. Isto permite que você possa testar e atualizar 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. PowerShell também não importará automaticamente módulos que não estejam no parâmetro $env:PSModulePath variável.

Importar Comandos Selectivamente

Pode usar Import-Modulepara importar apenas funções específicas em vez de todo o módulo usando o parâmetro Function. Isto pode poupar tempo ao importar módulos de sistemas remotos, como os módulos do Office 365.

Todos os módulos do utilizador

Módulos instalados para todos os utilizadores 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 usando o escopo padrão AllUsers.

Módulos do usuário atual

Se você estiver instalando um módulo mas quiser apenas um único usuário para usá-lo, há um escopo CurrentUser. Isto coloca os ficheiros do módulo na sua pasta Documentos em C:\Users\<username>\Documents\WindowsPowerShell\Modules. Isto pode ser útil em um ambiente onde você usa redirecionamento de pastas com a pasta Documents.

Neste caso, você pode instalar um módulo em um computador e usá-lo em outro pois ambos estariam compartilhando a mesma pasta de documentos.

System Modules

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

Naming is Important

Você pode colocar manualmente seu módulo em um desses caminhos para torná-lo disponível por padrão com uma nova sessão, mas você tem que ter certeza de que você segue a nomenclatura necessária para os módulos. A pasta onde os ficheiros dos módulos são colocados, deve ter o mesmo nome que o ficheiro do módulo psm1 e o módulo psd1 manifestar-se se existir um.

Utilizar Get-Module -ListAvailable que já mencionámos anteriormente estes caminhos. Você pode ver todos os caminhos dos módulos usando $env:PSModulePath -Split ';'. Você pode notar outros caminhos na lista além do que é mostrado aqui. Muitos programas adicionam seus próprios caminhos de módulo quando eles são instalados. Um dos exemplos disto é o SQL, que tem os seus próprios módulos incluídos nos 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 disto é o módulo ActiveDirectory. Desde o Windows 7 até ao Windows 10 1803, instalá-lo-ia com o instalador Remote Server Administration Tools (RSAT).

Em versões mais recentes do Windows 10 (1809+), este só está disponível através das Features On Demand. Instalando o RSAT instala os módulos ActiveDirectory e muitos outros que você usaria para administrar outras funções do Windows. Nos sistemas operacionais Windows server, estes módulos são instalados através do Server Manager.

Importar módulos remotos (Implicit Remoting)

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

Uma outra utilização da importação de módulos remotos é quando você não tem o módulo instalado localmente. Isto é o que você obteria se não tivesse o módulo ActiveDirectory instalado, mas você tentou importá-lo.

Para importar um módulo remoto, você primeiro tem que criar uma PSSession. Você pode usar New-PSSession para criar a sessão. Então 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'

Usar este método de importação de módulos remotos permite a execução mais rápida do código em um ambiente distribuído. Por exemplo, se você está trabalhando a partir do seu computador, mas os servidores em que você está trabalhando estão em todos os EUA, pode levar muito mais tempo para executar determinados comandos localmente contra os servidores. Enquanto executar os comandos em um servidor e alimentar a saída de volta para 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. Esta opção está disponível enquanto importa módulos locais, mas raramente é usada fora dos testes de versões diferentes de um módulo lado a lado.

Se você executasse o comando de importação acima e isto é o que você veria quando olhasse os comandos:

Neste caso, você pode usar um prefixo para mostrar que não é um módulo local. Isto pode ser usado nos 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. Isto remove um módulo da sessão local sem remover os arquivos do módulo. Você pode querer usar isto em um caso em que você estava usando uma sessão remota para usar um módulo. Pode usar Remove-Module para limpar a sua sessão e depois desligar a sessão remota.

Outro uso de Remove-Module é se estiver a fazer alterações a um módulo e não quiser lançar uma nova sessão PowerShell. Neste caso, você usaria Remove-Module seguido de Import-Module para recarregá-la em sua sessão. Alternativamente, pode usar o parâmetro Force com Import-Module. Isto irá completar a descarga e recarga do módulo para si.

O que constitui um Módulo PowerShell

Um módulo pode ser constituído por um ou mais ficheiros. Para satisfazer os requisitos mínimos para um módulo, é necessário ter um ficheiro de módulo. Este pode ser um ficheiro PSM1 ou qualquer outro ficheiro de módulo, tal como um ficheiro de módulo binário. Para construir sobre isso, o seu psm1 deve ter funções definidas nele, ou não será muito útil para ninguém.

Embora não haja requisitos para a aparência das funções ou para o que elas devem fazer, existem algumas directrizes. Normalmente é preferível ter todas as funções em um módulo construído em torno do mesmo conceito.

Módulos Contêm Funções com a mesma Idéia

Por exemplo, o módulo ActiveDirectory inclui apenas funções que interagem com o Active Directory de alguma forma. Normalmente 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.

Utilizar estas diretrizes ajuda na descoberta das funções. Imagine que você acabou de importar este novo módulo e quer tabular através das funções. Isto é muito mais fácil de fazer se todas as funções tiverem uma estrutura de nomes semelhante. Embora você possa ver frequentemente os módulos começarem com PS, este prefixo é oficialmente reservado apenas para os módulos Microsoft. Você provavelmente não causará um problema se você usar PS no início do seu módulo, você pode criar um conflito com outro nome de módulo.

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

function Get-ATARegistryKey {...}function Set-ATARegistryKey {...}

Manifestações do módulo

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

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

#Module manifest for module 'ATARegistry'#Generated by: Tyler#Generated on: 8/11/2019@{#Script module or binary module file associated with this manifest.RootModule = 'ATARegistry'#Version number of this module.ModuleVersion = '1.0'#Supported PSEditions#CompatiblePSEditions = @()#ID used to uniquely identify this moduleGUID = 'fef619fa-016d-4b11-a09d-b222e094de3e'#Author of this moduleAuthor = 'Tyler Muir'#Company or vendor of this moduleCompanyName = 'Adam the Automator'#Copyright statement for this moduleCopyright = '(c) 2019 tyler. All rights reserved.'#Description of the functionality provided by this moduleDescription = 'This is a test module.'#Minimum version of the Windows PowerShell engine required by this module#PowerShellVersion = ''#Name of the Windows PowerShell host required by this module#PowerShellHostName = ''#Minimum version of the Windows PowerShell host required by this module#PowerShellHostVersion = ''#Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.#DotNetFrameworkVersion = ''#Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.#CLRVersion = ''#Processor architecture (None, X86, Amd64) required by this module#ProcessorArchitecture = ''#Modules that must be imported into the global environment prior to importing this module#RequiredModules = @()#Assemblies that must be loaded prior to importing this module#RequiredAssemblies = @()#Script files (.ps1) that are run in the caller's environment prior to importing this module.#ScriptsToProcess = @()#Type files (.ps1xml) to be loaded when importing this module#TypesToProcess = @()#Format files (.ps1xml) to be loaded when importing this module#FormatsToProcess = @()#Modules to import as nested modules of the module specified in RootModule/ModuleToProcess#NestedModules = @()#Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.FunctionsToExport = @('Get-RegistryKey','Set-RegistryKey')#Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.CmdletsToExport = @()#Variables to export from this moduleVariablesToExport = '*'#Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.AliasesToExport = @()#DSC resources to export from this module#DscResourcesToExport = @()#List of all modules packaged with this module#ModuleList = @()#List of all files packaged with this module#FileList = @()#Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.PrivateData = @{PSData = @{#Tags applied to this module. These help with module discovery in online galleries.#Tags = @()#A URL to the license for this module.#LicenseUri = ''#A URL to the main website for this project.#ProjectUri = ''#A URL to an icon representing this module.#IconUri = ''#ReleaseNotes of this module#ReleaseNotes = ''} #End of PSData hashtable} #End of PrivateData hashtable#HelpInfo URI of this module#HelpInfoURI = ''#Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.#DefaultCommandPrefix = ''}

Embora isto possa parecer intimidante no início, a Microsoft tem uma útil cmdlet que pode usar para gerar um manifesto de módulo. O comando incluído é New-ModuleManifest. Para gerar o manifesto mostrado acima você pode 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 externa

Você também pode ver arquivos de ajuda externa em alguns módulos. Eles podem ser identificados pelo arquivo <ModuleName>-Help.xml no final do nome do arquivo. Estes ficheiros de ajuda externa contêm a mesma informação que normalmente estaria contida na ajuda baseada em comandos que pode encontrar numa definição de função.

Isto também requer que adicione # .ExternalHelp <ModulePath>-Help.xml à sua função para que esta funcione correctamente quando utilizar o comando Get-Help depois de importar o módulo. Normalmente só é comum ver arquivos de ajuda externa com módulos muito grandes e devido a isso eles estão fora do escopo.

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

Para ter arquivos de módulos não-padrão publicados corretamente você incluiria outros arquivos no parâmetro FileList no seu manifesto de módulos.

No manifesto de módulos, você notará muitos outros parâmetros que estão atualmente vazios. Você pode usá-los para definir outros requisitos para o uso do seu módulo. Por exemplo, você pode definir as versões do PowerShell com as quais o módulo pode trabalhar. Se tentar importar o módulo numa versão não suportada do PowerShell, isto é o que verá:

PSRepositories

Uma das principais opções de distribuição dos módulos é um PSRepository. Em uma visualização 1000′, um PSRepositório é um local onde múltiplas pessoas ou múltiplos dispositivos podem acessar os arquivos dos módulos. 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ê mesmo pode hospedar um PSRepository, ou você pode utilizar uma das muitas opções disponíveis na internet como a Galeria PowerShell. Você pode ver os seus PSRepositórios usando o comando Get-PSRepository>

Por padrão, você terá apenas uma entrada e será para a PowerShell Gallery. Você pode notar que ela dirá “não confiável”. Isto porque o PowerShell o faz saber que ao usar a Galeria PowerShell pode estar a usar código não escrito e aprovado pela Microsoft. Isto significa que antes de qualquer módulo ser instalado a partir dele, terá de dar permissão explícita.

Adicionando PSRepositories

Pode também adicionar os seus próprios repositórios. Para confiar na PowerShell Gallery, pode correr Get-PSRepository -Name PSGallery | Set-PSRepository -InstallationPolicy Trusted ou pode aceitar o aviso na primeira vez que instalar um módulo da PowerShell Gallery.

Todos os comandos que usaria para interagir com estes PSRepositories podem ser encontrados no módulo PowerShellGet. Pode ver as funções aqui:

O módulo PowerShellGet pode ter de ser actualizado antes de interagir com certos repositórios.

Encontrar Módulos

Outra característica chave do uso de um PSRepository é a possibilidade de procurar módulos. Isto é 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 procurar por módulos VMware como este:

Isso mostrará todos os módulos que começam com VMware. Enquanto a maioria destes são do VMware, você precisa olhar para o atributo autor para ver quem publicou o módulo.

Desde que qualquer um pode fazer upload para a Galeria PowerShell, há milhares de módulos disponíveis. Isto significa que você pode encontrar módulos que não funcionam corretamente para o seu caso de uso. Muitos módulos que você vai encontrar são de código aberto para que você possa contribuir com eles para melhorar a funcionalidade do módulo.

Instalando Módulos

Para usar o comando Install-Module, você tem que ter um PSRepository confiável que está hospedando o módulo. Este pode ser a Galeria PowerShell, outro PSRepositório de Internet, ou um site auto-hospedado. Você pode pipear do comando Find-Module para estar disponível para confirmar facilmente o módulo antes de o instalar.

Você também pode definir a versão de um módulo usando o comando MinimumVersion, MaximumVersion, ou RequiredVersion parameters.

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

Desinstalando Módulos

Apenas como você pode instalar um módulo, você também pode desinstalar um módulo. Se o módulo não foi instalado através do 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 é instalado com Install-Module, você receberá um erro ao tentar usar Uninstall-Module. Para desinstalar este módulo, teríamos de o desinstalar invertendo o que utilizou para instalar o módulo.

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

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

O motivo pelo qual teria tantas dificuldades em desinstalar completamente este módulo é porque ele tem tantas dependências. Além disso, alguns destes módulos são dependências uns dos outros, e é por isso que o parâmetro Force seria necessário.

Actualizar Módulos

Agora que sabe como instalar e desinstalar um módulo, pode estar a perguntar-se como actualiza um módulo que tem instalado.

Apenas como outros processos, se o módulo não foi instalado usando Install-Module, não pode actualizar o usando os comandos PowerShell. Pode utilizar Update-Module para actualizar um módulo para o mais recente lançamento, ou para uma versão específica mais recente.

Tambem existe uma mudança para AllowPreRelease que lhe permitiria actualizar para uma versão que não tenha sido oficialmente lançada. Às vezes isso pode ajudar, pois pode ter havido uma correção para um bug que você está passando ou um novo recurso que foi adicionado que você gostaria de usar.

Inspecionando/Salvando um Módulo

Um dos comandos muito menos usados que é muito útil ao vetar módulos antes de usar é Save-Module. Usando este comando, você pode baixar um módulo para um caminho sem instalá-lo.

Você pode então inspecionar os arquivos e se o módulo não for um módulo binário você pode abrir e olhar para o código que compõe o módulo. Isto pode ser bom não só para garantir que um módulo não está fazendo nada malicioso, mas também para aprender como outros estão estruturando seus módulos.

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

Este é um bom exemplo de como às vezes há arquivos de módulo não-padrão incluídos no módulo, como o contrato de licenciamento do usuário final.

Escrevendo seu próprio módulo

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

Crie Arquivos Template

Primeiro você precisa criar uma pasta para todos os seus arquivos de módulo. Depois de ter o container, você precisa criar o seu arquivo de módulo. Você tem de se certificar que o ficheiro do seu módulo tem o mesmo nome da sua pasta ou então quando tentar publicar o seu módulo, o PowerShell não vai descobrir o módulo correctamente.

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

Agora você também quer usar um manifesto, você também precisa de lhe dar o mesmo nome que o contentor e o ficheiro 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 contentor, ficheiro do módulo e ficheiro do manifesto, você tem um módulo funcional completo. Você pode publicar este módulo em um PSRepository e começar a instalá-lo onde você quiser. Embora, como o arquivo do módulo está vazio, ele provavelmente não lhe servirá de muito. Você ainda pode usar esses arquivos para testar a publicação para ter certeza que seu repositório funciona.

Registrando um PSRepository

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

Normalmente, se você fosse configurar um PSRepository com um diretório, você iria querer ter certeza de que vários computadores podem acessá-lo. Você pode criar um repositório local como este:

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

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

Publicando seu Módulo

Desde que você já tenha definido a política de instalação como confiável, você não obterá 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ê tenha instalado o módulo, você pode usar Get-Module para ver o módulo importado para sua sessão local. Como você não adicionou nenhuma função ao array FunctionsToExport no manifesto, a propriedade ExportedCommands está vazia.

Adicionando ao seu módulo

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

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

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

Exporting Module Functions

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

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

Para corrigir estes dois problemas, pode actualizar o ficheiro do seu módulo desta forma:

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

Agora que tenha adicionado uma função ao seu módulo e tenha actualizado o seu manifesto para reflectir estas alterações, pode publicar a nova versão do seu módulo usando o mesmo comando que antes.

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

Actualizar o seu módulo

O último passo seria actualizar o seu módulo na sua sessão para poder usar os ficheiros actualizados. Usando Update-Module ATARegistry você baixa a actualização que acabou de publicar para o 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.

Construir Conteúdo de Ajuda

Uma das opções que foi passada anteriormente é o sistema de ajuda que está incorporado no PowerShell. Em algum momento você provavelmente usou Get-Help em uma função. Esta informação pode ser adicionada de duas formas principais.

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

Como você pode ver, não há realmente muita informação e a pouca informação que você obtém muito provavelmente não seria útil para ninguém.

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

Por enquanto, você pode atualizar sua função para se parecer com abaixo. Esta é uma lista dos parâmetros de ajuda mais usados, mas todos eles ainda são opcionais e há outros que poderiam ser adicionados em seu lugar.

Agora a sua função se parece com isto:

 function Get-RegistryKey {<# .SYNOPSIS Returns registry key using provided path. .DESCRIPTION The function uses the Get-Item command to return the information for a provided registry key. .PARAMETER Path The path that will be searched for a registry key. .EXAMPLE Get-RegistryKey -Path 'HKLM:\HARDWARE\DESCRIPTION\System' .INPUTS System.String .OUTPUTS Microsoft.Win32.RegistryKey .NOTES This module is an example of what a well documented function could look. .LINKhttps://adamtheautomator.com#>param($Path)Get-Item $Path}

Existem alguns parâmetros especiais de ajuda, como .FORWARDHELPTARGETNAME. Esta opção encaminha todos os pedidos de ajuda de entrada para um comando diferente. Isto pode ser usado em um caso onde a ajuda deve mostrar a mesma informação 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 você fez anteriormente.

Se você agora olhar para a ajuda para a função, você pode ver que há muito mais informações disponíveis. Esta é 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 olhando para o código.

No caso de um arquivo de ajuda externa, a informação adicionada é a mesma, mas a informação é colocada em um arquivo separado e ligada 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ê tem instalado.

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

Resumo

Após você ter um handle no console PowerShell, PowerShell como uma linguagem e escrever scripts, construir seus próprios módulos é o último passo. Os módulos permitem-lhe começar a desenvolver ferramentas úteis no PowerShell. Se for desenhado e construído correctamente ao criar módulos com um único propósito, irá inevitavelmente encontrar-se a escrever cada vez menos código ao longo do tempo. Você vai começar a referenciar suas funções de módulo em mais código e construir a partir daí.

Funções de módulo permitem que você abstraia o código que você se encontra repetindo em scripts. Elas representam “etiquetas” para referenciar mais tarde em código que pode ser chamado a qualquer momento ao invés de reinventar a roda e tentar descobrir como você já tinha atingido seu objetivo anteriormente. Os módulos são o “empacotamento” final do código PowerShell que agrupa o código da mesma forma para evitar perder tempo com problemas que você já resolveu.