Adam the Automator

Lavorare con moduli PowerShell è un pezzo importante dell’automazione PowerShell. Quando si inizia ad imparare PowerShell, i primi passi di solito sono l’utilizzo di singoli comandi. Questo porta alla costruzione di script che poi porta alla costruzione di funzioni.

Utilizzando le funzioni, puoi rendere i tuoi script più modulari. Questo vi permette di essere in grado di usare lo stesso codice in molti posti senza copiare e incollare il codice dappertutto. Usare le funzioni vi permette di passare meno tempo a fare la stessa modifica allo stesso codice ovunque venga usato. Invece potete lavorare per migliorare il vostro codice in un unico posto.

Per portare le funzioni al livello successivo, potete combinare queste funzioni insieme in un modulo.

Un modulo è una collezione di funzioni in un file di testo con estensione psm1. Ci sono alcune aggiunte opzionali, come un manifesto del modulo e un aiuto esterno o basato su commenti che possono essere inclusi. Questi saranno trattati più avanti.

Prerequisiti

In questo articolo userò Windows PowerShell 5.1. Se stai usando una versione precedente o PowerShell Core, il tuo chilometraggio può variare per quanto riguarda i risultati che vedrai.

Interagire con i moduli

Una volta aperta una sessione PowerShell, inizierai con due moduli. Il primo è Microsoft.PowerShell.Utility che contiene molte funzioni PowerShell di base che già usi. L’altro modulo è PSReadline. Puoi vedere questi moduli di partenza usando il comando Get-Module.

Detto questo, questa non è una lista completa di tutti i moduli disponibili. A partire da PowerShell 3, i moduli che sono installati saranno importati come necessario. Se stai eseguendo una vecchia versione di PowerShell ti sarà richiesto di usare il comando Import-Module per importare il modulo prima di usare qualsiasi comando.

Ci sono momenti in cui vorresti ancora usare Import-Module anche nelle versioni successive. Se vuoi importare un modulo dopo che è già installato, puoi usare Import-Module in questo modo:

Mentre Get-Module mostrerà tutti i moduli che sono importati, non vedrai i moduli che non sono ancora stati importati. Puoi quindi usare il parametro ListAvailable per mostrare tutti gli altri moduli che sono disponibili.

Non tutti i comandi sono mostrati per default

La proprietà ExportedCommands contiene una lista di tutti i comandi disponibili che sono esportati dal modulo. Potresti vedere alcune differenze tra questo elenco e quello che c’è nel file del modulo. I comandi esportati sono una caratteristica incorporata nel manifesto del modulo che permette all’autore di lasciare una funzione come nascosta. Gli autori dei moduli possono anche usare il cmdlet Export-ModuleMember, ma questo è al di fuori dello scopo di questo articolo.

Gli autori dei moduli possono voler avere una funzione nascosta perché è destinata a supportare altre funzioni, non ad essere rivolta all’utente. Per avere una funzione nascosta l’autore dovrebbe escluderla dall’array FunctionsToExport nel manifesto. Qui puoi vedere una vista estesa della proprietà ExportedCommands.

Importazione dei moduli

Ci sono molti modi per iniziare ad usare i moduli. Puoi importare manualmente il modulo usando il percorso dei file del modulo. Questo ti permette di essere in grado di testare e aggiornare il modulo senza dover fare molto lavoro. Ma questo non permette molta portabilità, poiché dovresti usare il percorso esatto del modulo. PowerShell inoltre non importerà automaticamente i moduli che non sono nella variabile $env:PSModulePath.

Importazione selettiva dei comandi

Puoi usare Import-Module per importare solo funzioni specifiche invece che l’intero modulo usando il parametro Function. Questo può far risparmiare tempo quando si importano moduli da sistemi remoti, come i moduli di Office 365.

Tutti i moduli utente

I moduli installati per tutti gli utenti vengono messi in C:\Program Files\WindowsPowerShell\Modules. Questa directory contiene molti moduli pre-aggiunti, incluso qualsiasi modulo installato usando Install-Module usando l’ambito predefinito AllUsers.

Moduli utente corrente

Se stai installando un modulo ma vuoi che solo un singolo utente lo usi, c’è un ambito CurrentUser. Questo mette i file del modulo nella tua cartella Documenti in C:\Users\<username>\Documents\WindowsPowerShell\Modules. Questo può essere utile in un ambiente dove usi il reindirizzamento delle cartelle con la cartella Documenti.

In questo caso, puoi installare un modulo su un computer e usarlo su un altro poiché entrambi condivideranno la stessa cartella Documenti.

Moduli di sistema

Per completezza, c’è anche una directory di moduli in C:\Windows\System32\WindowsPowerShell\1.0\Modules. Anche se tecnicamente, un modulo collocato in questo percorso verrebbe importato come uno degli altri percorsi, ma non è raccomandato in quanto è riservato ai moduli di sistema di Microsoft.

La denominazione è importante

Puoi mettere manualmente il tuo modulo in uno di questi percorsi per renderlo disponibile di default con una nuova sessione, ma devi essere sicuro di seguire la denominazione richiesta per i moduli. La cartella in cui sono collocati i file del modulo deve avere lo stesso nome del file del modulo psm1 e del manifesto del modulo psd1, se ce n’è uno.

Usando Get-Module -ListAvailable che avevamo menzionato prima si fa riferimento a questi percorsi. Puoi vedere tutti i percorsi dei moduli usando $env:PSModulePath -Split ';'. Potreste notare altri percorsi nella lista oltre a quello mostrato qui. Molti programmi aggiungono i propri percorsi dei moduli quando vengono installati. Uno degli esempi di questo è SQL, che ha i propri moduli inclusi nei propri percorsi dei moduli.

Ci sono anche alcuni moduli che si installano con un processo diverso. Uno degli esempi più significativi è il modulo ActiveDirectory. Da Windows 7 fino a Windows 10 1803, lo installereste con il programma di installazione Remote Server Administration Tools (RSAT).

Nelle versioni più recenti di Windows 10 (1809+) questo è disponibile solo attraverso le funzionalità su richiesta. L’installazione di RSAT installa i moduli ActiveDirectory e molti altri che useresti per amministrare altri ruoli di Windows. Sui sistemi operativi server di Windows, questi moduli sono installati attraverso il Server Manager.

Importazione di moduli remoti (Remoting implicito)

Ci sono alcuni casi in cui non è pratico avere un modulo in esecuzione localmente. Invece è meglio connettersi a un dispositivo remoto e importare un modulo installato su di esso. Quando si fa questo, i comandi vengono effettivamente eseguiti sulla macchina remota. Questo è usato frequentemente con i moduli Office 365 di Microsoft. Molti di essi si connettono a un server Office 365 che poi importa un modulo. Quando si esegue uno qualsiasi dei comandi, questi vengono eseguiti sul server remoto e poi l’output viene rimandato alla propria sessione.

Un altro uso dell’importazione di moduli remoti è quando non si ha il modulo installato localmente. Questo è ciò che otterresti se non avessi il modulo ActiveDirectory installato, ma provassi a importarlo.

Per importare un modulo remoto, devi prima creare una PSSession. Puoi usare New-PSSession per creare la sessione. Poi importerete il modulo disponibile sul dispositivo remoto usando il parametro PSSession con Import-Module.

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

L’utilizzo di questo metodo di importazione dei moduli remoti permette un’esecuzione più veloce del codice in un ambiente distribuito. Per esempio, se state lavorando dal vostro computer, ma i server su cui state lavorando sono dall’altra parte degli Stati Uniti, potrebbe essere necessario molto più tempo per eseguire certi comandi localmente contro i server. Mentre eseguire i comandi su un server e riportare l’output alla tua sessione locale è molto più veloce.

Aggiungere un prefisso al modulo

Puoi anche aggiungere un prefisso alle funzioni importate dalla macchina remota. Questa opzione è disponibile durante l’importazione di moduli locali, ma è raramente usata al di fuori dei test di diverse versioni di un modulo fianco a fianco.

Se hai eseguito il comando di importazione sopra e questo è ciò che vedresti quando guardi i comandi:

In questo caso, puoi usare un prefisso per mostrare che non è un modulo locale. Questo può essere usato nei casi in cui si sta importando un modulo che è anche disponibile localmente. Aggiungere il prefisso riduce la confusione su dove il codice viene eseguito.

Rimozione di moduli

Puoi anche rimuovere un modulo dalla sessione corrente senza usare Remove-Module. Questo rimuove un modulo dalla sessione locale senza rimuovere i file del modulo. Potreste volerlo usare in un caso in cui state usando una sessione remota per usare un modulo. Potresti usare Remove-Module per pulire la tua sessione e poi disconnettere la sessione remota.

Un altro uso di Remove-Module è se stai facendo delle modifiche a un modulo e non vuoi lanciare una nuova sessione PowerShell. In questo caso, useresti Remove-Module seguito da Import-Module per ricaricarlo nella tua sessione. In alternativa, puoi usare il parametro Force con Import-Module. Questo completerà lo scarico e il ricaricamento del modulo per te.

Cosa fa un modulo PowerShell

Un modulo può essere composto da uno o più file. Per soddisfare i requisiti minimi di un modulo, devi avere un file di modulo. Questo può essere un file PSM1 o qualsiasi altro file di modulo come un file di modulo binario. Per costruire su questo, il vostro psm1 dovrebbe avere delle funzioni definite al suo interno, o non sarà molto utile a nessuno.

Mentre non ci sono requisiti per come le funzioni dovrebbero apparire o cosa dovrebbero fare, ci sono alcune linee guida. Di solito è preferibile che tutte le funzioni di un modulo siano costruite intorno allo stesso concetto.

I moduli contengono funzioni simili

Per esempio, il modulo ActiveDirectory include solo funzioni che interagiscono in qualche modo con Active Directory. Di solito i nomi delle funzioni contengono anche un prefisso. Tornando al modulo ActiveDirectory come esempio, tutti i nomi delle funzioni iniziano con AD.

L’utilizzo di queste linee guida aiuta a scoprire le funzioni. Immaginate di aver appena importato questo nuovo modulo e di voler scorrere le funzioni. Questo è molto più facile da fare se tutte le funzioni hanno una struttura di nomi simile. Mentre potreste vedere spesso moduli che iniziano con PS, questo prefisso è ufficialmente riservato solo ai moduli Microsoft. Probabilmente non causerete un problema se usate PS all’inizio del vostro modulo, potreste creare un conflitto con il nome di un altro modulo.

Utilizzando queste linee guida, se aveste un mucchio di funzioni che hanno tutte a che fare con l’interazione con il registro potreste avere qualcosa come:

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

Module Manifests

Per costruire sul file modulo di testo, potete anche includere un module manifest. Questi file hanno un’estensione PSD1 e contengono metadati sul modulo. Questo è dove includereste informazioni sull’autore, la descrizione del modulo, altri moduli richiesti, e molti altri attributi. Per pubblicare su un repository, è necessario che i campi Author e Description siano popolati.

Ecco un esempio di un manifesto che potremmo avere per il nostro modulo di registro:

#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 = ''}

Anche se questo può sembrare intimidatorio all’inizio, Microsoft ha un comodo cmdlet che potete usare per generare un manifesto del modulo. Il comando incluso è New-ModuleManifest. Per generare il manifesto mostrato sopra potresti usare:

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.'

File di aiuto esterno

Potresti anche vedere file di aiuto esterno in alcuni moduli. Potrebbero essere identificati da <NomeModulo>-Help.xml alla fine del nome del file. Questi file di aiuto esterno contengono le stesse informazioni che normalmente sarebbero contenute nell’aiuto basato sui comandi che potete trovare nella definizione di una funzione.

Questo richiederebbe anche di aggiungere # .ExternalHelp <ModulePath>-Help.xml alla vostra funzione per farla funzionare correttamente quando usate il comando Get-Help dopo aver importato il modulo. Di solito è comune vedere file di aiuto esterni solo con moduli molto grandi e per questo sono fuori dallo scopo.

Mentre questi sono i tipi più comuni di file che vedrete in un modulo, questi non sono gli unici file. A volte vedrete file binari in aggiunta a un modulo di testo perché ci sono altre dipendenze. Esplorando i percorsi dei moduli, puoi trovare molti esempi di tipi di file aggiuntivi nei moduli.

Per pubblicare correttamente i file non standard dei moduli dovresti includere altri file nel parametro FileList del tuo manifesto del modulo.

Nel manifesto del modulo, noterai molti altri parametri che sono attualmente vuoti. Puoi usarli per definire altri requisiti per l’uso del tuo modulo. Per esempio, puoi definire le versioni di PowerShell con cui il modulo può lavorare. Se provi a importare il modulo su una versione non supportata di PowerShell, questo è ciò che vedresti:

PSRepositories

Una delle opzioni di distribuzione chiave per i moduli è un PSRepository. Ad una visione al 1000′, un PSRepository è un locale dove più persone o più dispositivi possono accedere ai file del modulo. Questi sono spesso server web dove puoi pubblicare i file.

Puoi anche usare una directory per il repository, ma questo ti limita nella funzionalità del tuo repository. Puoi ospitare un PSRepository da solo, o puoi utilizzare una delle molte opzioni disponibili su internet come la PowerShell Gallery. Puoi vedere i tuoi PSRepository usando il comando Get-PSRepository.

Di default, avrai solo una voce e sarà per la PowerShell Gallery. Potresti notare che ci sarà scritto untrusted. Questo perché PowerShell ti rende consapevole che usando la PowerShell Gallery potresti usare codice non scritto e approvato da Microsoft. Questo significa che prima di installare qualsiasi modulo da essa, dovrai dare un permesso esplicito.

Aggiungere PSRepositories

Puoi anche aggiungere i tuoi repository. Per fidarti di PowerShell Gallery, puoi eseguire Get-PSRepository -Name PSGallery | Set-PSRepository -InstallationPolicy Trusted o puoi accettare l’avvertimento la prima volta che installi un modulo dalla PowerShell Gallery.

Tutti i comandi che useresti per interagire con questi PSRepository si trovano nel modulo PowerShellGet. Potete vedere le funzioni qui:

Il modulo PowerShellGet potrebbe dover essere aggiornato prima di interagire con certi repository.

Trovare i moduli

Un’altra caratteristica chiave dell’uso di un PSRepository è la possibilità di cercare i moduli. Questo si ottiene usando il comando Find-Module. Ci sono diversi modi di filtrare per trovare specificamente ciò che stai cercando, ma per ora puoi cercare i moduli VMware in questo modo:

Questo mostrerà tutti i moduli che iniziano con VMware. Mentre la maggior parte di questi sono di VMware, devi guardare l’attributo dell’autore per vedere chi ha pubblicato il modulo.

Siccome chiunque può caricare su PowerShell Gallery, ci sono migliaia di moduli disponibili. Questo significa che potresti trovare moduli che non funzionano correttamente per il tuo caso d’uso. Molti moduli che troverai sono open source in modo da poter contribuire ad essi per migliorare la funzionalità del modulo.

Installare i moduli

Per usare il comando Install-Module, devi avere un PSRepository affidabile che ospita il modulo. Questo può essere la PowerShell Gallery, un altro PSRepository su internet, o un sito auto-ospitato. Puoi fare un pipe dal comando Find-Module per essere disponibile per confermare facilmente il modulo prima di installarlo.

Puoi anche definire la versione di un modulo usando i parametri MinimumVersion, MaximumVersion, o RequiredVersion.

Per vedere tutti i moduli installati usando Install-Module puoi usare Get-InstalledModule. Questo elencherà tutti i moduli installati nell’ambito AllUsers o nel tuo ambito CurrentUser.

Disinstallazione dei moduli

Proprio come puoi installare un modulo, puoi anche disinstallare un modulo. Se il modulo non è stato installato tramite il comando Install-Module, non è possibile disinstallarlo con il comando Uninstall-Module.

Come potete vedere qui stiamo cercando di disinstallare il modulo ActiveDirectory. Poiché questo modulo non è installato con Install-Module, riceverete un errore quando proverete a usare Uninstall-Module. Per disinstallare questo modulo, dovremmo disinstallarlo invertendo quello che hai usato per installare il modulo.

Per vedere una disinstallazione riuscita di un modulo, puoi disinstallare il modulo VMware.PowerCLI che hai installato prima.

Anche se hai disinstallato VMware.PowerCLI, puoi vedere che ci sono ancora molte dipendenze installate. Se si volesse disinstallare tutti i moduli potremmo usare Get-InstalledModule VMware.* | Uninstall-Module -Force.

La ragione per cui avreste tali difficoltà a disinstallare completamente questo modulo è perché ha così tante dipendenze. Inoltre, alcuni di questi moduli sono dipendenti l’uno dall’altro, ed è per questo che il parametro Force sarebbe necessario.

Aggiornare i moduli

Ora che sai come installare e disinstallare un modulo, potresti chiederti come aggiornare un modulo che hai installato.

Proprio come altri processi, se il modulo non è stato installato usando Install-Module, non puoi aggiornarlo usando i comandi PowerShell. Puoi usare Update-Module per aggiornare un modulo alla versione più recente, o a una versione specifica più recente.

C’è anche uno switch a AllowPreRelease che ti permetterebbe di aggiornare a una versione che non è stata ufficialmente rilasciata. A volte questo può essere utile perché potrebbe esserci una correzione per un bug che stai sperimentando o una nuova caratteristica aggiunta che vorresti usare.

Ispezionare/Salvare un Modulo

Uno dei comandi molto meno usati che è molto utile quando si controllano i moduli prima dell’uso è Save-Module. Usando questo comando, puoi scaricare un modulo in un percorso senza installarlo.

Puoi poi ispezionare i file e se il modulo non è un modulo binario puoi aprire e guardare il codice che lo compone. Questo può essere buono non solo per assicurarsi che un modulo non stia facendo qualcosa di dannoso, ma anche per imparare come gli altri stanno strutturando i loro moduli.

In questo esempio, non solo viene scaricato il modulo VMware.PowerCLI, ma anche tutte le dipendenze. Ecco cosa viene mostrato nella cartella VMware.PowerCLI:

Questo è un buon esempio per mostrare come a volte ci siano file non standard inclusi nel modulo, come il contratto di licenza dell’utente finale.

Scrivere il proprio modulo

Hai visto come interagire con il modulo di qualcun altro. Ora vuoi imparare come creare il tuo in modo da poter iniziare a ottimizzare il tuo codice per la scalabilità.

Creare i file del modulo

Prima di tutto devi creare una cartella per tutti i file del tuo modulo. Dopo aver creato il contenitore, devi creare il tuo file modulo. Dovete assicurarvi che il vostro file del modulo abbia lo stesso nome della vostra cartella, altrimenti quando cercherete di pubblicare il vostro modulo, PowerShell non scoprirà il modulo correttamente.

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

Ora volete anche usare un manifesto, dovrete anche dargli lo stesso nome del contenitore e del file del modulo.

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'

Con il contenitore, il file del modulo e il file manifesto, avete un modulo completamente funzionante. Potreste pubblicare questo modulo in un PSRepository e iniziare a installarlo dove volete. Anche se, dato che il file del modulo è vuoto, probabilmente non vi servirà a molto. Puoi comunque usare questi file per testare la pubblicazione per assicurarti che il tuo repository funzioni.

Registrazione di un PSRepository

Prima di poter pubblicare il tuo modulo, dovrai aggiungere un altro PSRepository alla tua sessione. Per i test, puoi usare un percorso locale come PSRepository dato che sarà facile da configurare e smontare.

Normalmente, se dovessi configurare un PSRepository con una directory, vorresti assicurarti che più computer possano accedervi. Puoi creare un repository locale come questo:

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

Se stessi solo scaricando dal PSRepository e mai pubblicando, potresti escludere il parametro PublishLocation.

Pubblicando il tuo modulo

Siccome hai già impostato la politica di installazione su trusted, non riceverai una conferma per permettere l’installazione di un modulo dal repository. Ora che avete un nuovo PSRepository disponibile, potete pubblicare il vostro modulo usando Publish-Module -Name .\Scripts\ATARegistry -Repository LocalRepo.

Dopo aver pubblicato il vostro modulo, potete usare i comandi di cui sopra per trovare il modulo e installarlo.

Ora che avete installato il modulo, potete usare Get-Module per vedere il modulo importato nella vostra sessione locale. Poiché non hai aggiunto alcuna funzione all’array FunctionsToExport nel manifest, la proprietà ExportedCommands è vuota.

Aggiungere al tuo modulo

Ora che sai che puoi pubblicare e installare il tuo modulo, puoi iniziare ad aggiungere alcune funzionalità ad esso. Potreste aggiungere una funzione per restituire una chiave di registro in modo che assomigli a questa:

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

Se lasciaste il manifesto così com’è e provaste a caricare il vostro nuovo modulo incontrereste due problemi. Il primo è che ricevereste un errore che afferma che la versione del vostro modulo esiste già nel vostro repository. Questo perché non avete cambiato la versione del modulo nel file manifest.

Esportazione delle funzioni del modulo

L’altro problema sarebbe che dopo aver importato il modulo, non vedreste ancora nessuna funzione nella proprietà ExportedCommands perché non avete aggiunto la vostra nuova funzione al manifest.

Mentre la vostra funzione potrebbe essere usata senza elencarla nella lista FunctionsToExport, ciò la renderebbe molto più difficile da localizzare.

Per risolvere questi due problemi, puoi aggiornare il file del tuo modulo in questo modo:

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

Ora che hai aggiunto una funzione al tuo modulo e hai aggiornato il tuo manifesto per riflettere questi cambiamenti, puoi pubblicare la nuova versione del tuo modulo usando lo stesso comando di prima.

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

Aggiornare il tuo modulo

L’ultimo passo sarebbe quello di aggiornare il tuo modulo nella tua sessione per poter utilizzare i file aggiornati. Usando Update-Module ATARegistry scarichi l’aggiornamento che hai appena pubblicato nel repository.

Ora puoi vedere che hai la nuova versione del modulo e puoi vedere la funzione che hai definito nel manifesto.

Costruire il contenuto della guida

Una delle opzioni che è stata passata prima è il sistema di aiuto che è costruito in PowerShell. Probabilmente a un certo punto hai usato Get-Help su una funzione. Queste informazioni possono essere aggiunte in due modi principali.

Il primo è quello di aggiungere un aiuto basato su commenti nella definizione della funzione. Questo è di solito il modo che molti autori di moduli implementano. L’altro modo è quello di usare un file di aiuto esterno. Puoi usare il parametro Full per mostrare tutto ciò che l’aiuto ha da offrire.

Come puoi vedere, non ci sono davvero molte informazioni e le poche informazioni che ottieni molto probabilmente non sarebbero utili a nessuno.

Puoi aggiungere un aiuto basato sui commenti al tuo file del modulo per popolare questi campi nel sistema di aiuto. Puoi leggere tutte le opzioni per l’aiuto basato sui commenti usando Get-Help about_Comment_Based_Help.

Per ora, puoi aggiornare la tua funzione come segue. Questa è una lista dei parametri di aiuto più comunemente usati, ma tutti questi sono ancora opzionali e ce ne sono altri che potrebbero essere aggiunti al loro posto.

Ora la tua funzione ha questo aspetto:

 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}

Ci sono alcuni parametri di aiuto speciali, come .FORWARDHELPTARGETNAME. Questa opzione inoltra tutte le richieste di aiuto in arrivo a un comando diverso. Questo potrebbe essere usato in un caso in cui l’aiuto dovrebbe mostrare le stesse informazioni per più comandi.

Ora che hai aggiunto l’aiuto, puoi aggiornare la versione nel manifesto del modulo, pubblicare la nuova versione e aggiornare la versione installata per la tua sessione come hai fatto prima.

Se ora guardi l’aiuto per la funzione, puoi vedere che ci sono molte più informazioni disponibili. Questo è un ottimo modo per includere la documentazione su come usare le funzioni, specialmente per qualcuno che ha meno esperienza e potrebbe non essere in grado di capire rapidamente cosa sta facendo il modulo guardando il codice.

Nel caso di un file di aiuto esterno, le informazioni aggiunte sono le stesse, ma le informazioni sono messe in un file separato e collegate nella funzione.

Se guardi nel percorso del modulo AllUsers puoi vedere la versione del modulo e tutti i file del modulo che hai installato.

Se torni al tuo percorso PSRepository C:\Repo che hai creato prima, puoi vedere una serie di file NUPKG. Ce ne sarà uno per ogni versione che è stata pubblicata. Queste sono versioni compresse di ciò che hai pubblicato usando Publish-Module.

Riepilogo

Una volta che hai imparato a conoscere la console PowerShell, PowerShell come linguaggio e a scrivere script, costruire i tuoi moduli è l’ultimo passo. I moduli ti permettono di iniziare a sviluppare strumenti utili in PowerShell. Se progettati e costruiti correttamente creando moduli per un unico scopo, ti troverai inevitabilmente a scrivere sempre meno codice nel tempo. Inizierai a fare riferimento alle tue funzioni di modulo in più codice e a costruire da lì.

Le funzioni di modulo ti permettono di astrarre il codice che ti ritrovi a ripetere negli script. Rappresentano “etichette” a cui fare riferimento in seguito nel codice che può essere chiamato in qualsiasi momento piuttosto che reinventare la ruota e cercare di capire come avete già realizzato il vostro obiettivo in precedenza. I moduli sono il “packaging” finale del codice PowerShell che raggruppa codice simile per evitare di perdere tempo su problemi che hai già risolto.