Adam the Automator

Att arbeta med PowerShell-moduler är en viktig del av PowerShell-automatiseringen. När du börjar lära dig PowerShell brukar de första stegen vara att använda enskilda kommandon. Detta leder till att bygga skript som sedan leder till att bygga funktioner.

Genom att använda funktioner kan du göra dina skript mer modulära. Detta gör att du kan använda samma kod på många ställen utan att behöva kopiera och klistra in koden överallt. Genom att använda funktioner kan du spendera mindre tid på att göra samma redigering av samma kod överallt där den används. Istället kan du arbeta med att göra din kod bättre på ett enda ställe.

För att ta funktioner till nästa nivå kan du kombinera dessa funktioner till en modul.

En modul är en samling funktioner i en textfil med ett psm1-tillägg. Det finns vissa valfria tillägg, t.ex. ett modulmanifest och kommentarsbaserad eller extern hjälp som också kan inkluderas. Dessa kommer att behandlas senare.

Förutsättningar

Jag kommer att använda Windows PowerShell 5.1 i den här artikeln. Om du använder en äldre version eller PowerShell Core kan det variera beroende på vilka resultat du ser.

Interagera med moduler

När du först öppnar en PowerShell-session kommer du att börja med två moduler. Den första är Microsoft.PowerShell.Utility som innehåller många grundläggande PowerShell-funktioner som du redan använder. Den andra modulen är PSReadline. Du kan se dessa startmoduler genom att använda kommandot Get-Module.

Detta är dock inte en fullständig lista över alla tillgängliga moduler. Ända sedan PowerShell 3 kommer moduler som är installerade att importeras vid behov. Om du kör en äldre version av PowerShell måste du använda kommandot Import-Module för att först importera modulen innan du använder något av kommandona.

Det finns tillfällen då du fortfarande vill använda Import-Module även i senare versioner. Om du vill importera en modul efter att den redan är installerad kan du använda Import-Module så här:

Men Get-Module visar alla moduler som är importerade, men du kommer inte att se de moduler som ännu inte har importerats. Du kan sedan använda parametern ListAvailable för att visa alla andra moduler som är tillgängliga.

Inte alla kommandon visas som standard

Gegenskapen ExportedCommands innehåller en lista över alla tillgängliga kommandon som exporteras från modulen. Du kan se vissa skillnader mellan den här listan och vad som finns i modulfilen. Exporterade kommandon är en funktion som är inbyggd i modulmanifestet och som gör det möjligt för författaren att lämna en funktion som dold. Modulförfattare kan också använda cmdlet Export-ModuleMember, men det ligger utanför den här artikelns räckvidd.

Modulförfattare kan vilja ha en funktion dold eftersom den är tänkt att stödja andra funktioner, inte vara användarvänlig. För att dölja en funktion måste författaren utesluta den från arrayen FunctionsToExport i manifestet. Här kan du se en utökad vy av egenskapen ExportedCommands.

Import av moduler

Det finns många sätt att börja använda moduler. Du kan manuellt importera modulen med hjälp av sökvägen till modulfilerna. Detta gör att du kan testa och uppdatera modulen utan att behöva göra mycket arbete. Men detta ger inte mycket portabilitet, eftersom du måste använda den exakta sökvägen till modulen. PowerShell kommer inte heller att autoimportera moduler som inte finns i variabeln $env:PSModulePath.

Selektivt importerande kommandon

Du kan använda Import-Module för att endast importera specifika funktioner istället för hela modulen genom att använda parametern Function. Detta kan spara tid när du importerar moduler från fjärrsystem, till exempel Office 365-moduler.

Alla användarmoduler

Moduler som installeras för alla användare placeras i C:\Program Files\WindowsPowerShell\Modules. Den här katalogen innehåller många förinstallerade moduler, inklusive alla moduler som installerats med Install-Module med standardomfång AllUsers.

Moduler för nuvarande användare

Om du installerar en modul men bara vill att en enskild användare ska använda den, finns det ett CurrentUser-omfång. Detta placerar modulfilerna i din dokumentmapp på C:\Users\<användarnamn>\Documents\WindowsPowerShell\Modules. Detta kan vara användbart i en miljö där du använder mappomdirigering med mappen Dokument.

I det här fallet kan du installera en modul på en dator och använda den på en annan eftersom båda delar samma dokumentmapp.

System Modules

För fullständighetens skull finns det också en modulkatalog på C:\Windows\System32\WindowsPowerShell\1.0\Modules. Tekniskt sett skulle en modul som placeras i den här sökvägen importeras på samma sätt som en av de andra sökvägarna, men det rekommenderas inte eftersom den är reserverad för Microsofts systemmoduler.

Namngivningen är viktig

Du kan manuellt placera din modul i en av de här sökvägarna för att göra den tillgänglig som standard vid en ny session, men du måste se till att du följer den namngivning som krävs för moduler. Mappen som modulfilerna placeras i måste ha samma namn som psm1-modulfilen och psd1-modulmanifestet om det finns ett.

Användning av Get-Module -ListAvailable som vi nämnde tidigare hänvisar till dessa sökvägar. Du kan se alla modulsökvägar med hjälp av $env:PSModulePath -Split ';'. Du kanske märker andra sökvägar i listan än vad som visas här. Många program lägger till sina egna modulsökvägar när de installeras. Ett exempel på detta är SQL, som har sina egna moduler inkluderade i sina egna modulsökvägar.

Det finns också vissa moduler som du skulle installera med en annan process. Ett av de viktigaste exemplen på detta är ActiveDirectory-modulen. Från Windows 7 till och med Windows 10 1803 installerar du den med installationsprogrammet RSAT (Remote Server Administration Tools).

På nyare versioner av Windows 10 (1809+) är den endast tillgänglig via funktionen Features On Demand. Genom att installera RSAT installeras ActiveDirectory-modulerna och många andra som du använder för att administrera andra Windows-roller. På Windows serveroperativsystem installeras dessa moduler via Serverhanteraren.

Importera fjärrmoduler (implicit fjärrstyrning)

Det finns vissa fall där det inte är praktiskt att ha en modul som körs lokalt. Istället är det bättre att ansluta till en fjärrenhet och importera en modul som är installerad på den. När du gör detta utförs kommandona faktiskt på fjärrmaskinen. Detta används ofta med Microsofts Office 365-moduler. Många av dem ansluter till en Office 365-server som sedan importerar en modul. När du kör något av kommandona körs de på fjärrservern och sedan skickas resultatet tillbaka till din session.

En annan användning av import av fjärrmoduler är när du inte har modulen installerad lokalt. Det här är vad du skulle få om du inte har ActiveDirectory-modulen installerad, men försöker importera den.

För att importera en fjärrmodul måste du först skapa en PSSession. Du kan använda New-PSSession för att skapa sessionen. Därefter importerar du den modul som är tillgänglig på fjärrenheten genom att använda PSSession-parametern med Import-Module.

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

Användning av den här metoden för att importera fjärrmoduler gör det möjligt att snabbare exekvera kod i en distribuerad miljö. Om du till exempel arbetar från din dator, men servrarna du arbetar på finns på andra sidan USA, kan det ta betydligt längre tid att köra vissa kommandon lokalt mot servrarna. Medan det går mycket snabbare att köra kommandona på en server och föra tillbaka utdata till din lokala session.

Lägga till ett modulprefix

Du kan också lägga till ett prefix på de funktioner som importeras från fjärrmaskinen. Det här alternativet är tillgängligt vid import av lokala moduler, men används sällan utanför testning av olika versioner av en modul sida vid sida.

Om du körde importkommandot ovan och det här är vad du skulle se när du tittar på kommandona:

I det här fallet kan du använda ett prefix för att visa att det inte är en lokal modul. Detta kan användas i fall där du importerar en modul som också är tillgänglig lokalt. Genom att lägga till prefixet minskar förvirringen om var koden exekveras.

Ta bort moduler

Du kan också ta bort en modul från den aktuella sessionen utan att använda Remove-Module. Detta tar bort en modul från den lokala sessionen utan att modulfilerna tas bort. Du kanske vill använda detta i ett fall där du använde en fjärrsession för att använda en modul. Du kan använda Remove-Module för att rensa din session och sedan koppla bort fjärrsessionen.

En annan användning av Remove-Module är om du gör ändringar i en modul och inte vill starta en ny PowerShell-session. I det här fallet använder du Remove-Module följt av Import-Module för att ladda om den till sessionen. Alternativt kan du använda parametern Force med Import-Module. Detta kommer att slutföra lossningen och återladdningen av modulen åt dig.

Vad som ingår i en PowerShell-modul

En modul kan bestå av en eller flera filer. För att uppfylla minimikraven för en modul måste du ha en modulfil. Det kan vara en PSM1-fil eller någon annan modulfil, till exempel en binär modulfil. För att bygga vidare på detta bör din psm1 ha funktioner definierade i den, annars kommer den inte att vara till någon större nytta för någon.

Men även om det inte finns några krav på hur funktionerna skall se ut eller vad de skall göra, finns det några riktlinjer. Det är vanligtvis att föredra att alla funktioner i en modul bygger på samma koncept.

Moduler innehåller likadana funktioner

Till exempel innehåller ActiveDirectory-modulen endast funktioner som interagerar med Active Directory på något sätt. Vanligtvis innehåller funktionsnamnen också ett prefix. Om vi återgår till ActiveDirectory-modulen som exempel börjar alla substantiv i funktionsnamnen med AD.

Att använda dessa riktlinjer underlättar upptäckbarheten av funktionerna. Föreställ dig att du precis har importerat den här nya modulen och vill bläddra genom funktionerna. Detta är mycket lättare att göra om alla funktioner har en liknande namnstruktur. Även om du ofta ser moduler som börjar med PS, är detta prefix officiellt reserverat endast för Microsoft-moduler. Du kommer förmodligen inte att orsaka något problem om du använder PS i början av din modul, du kan skapa en konflikt med ett annat modulnamn.

Med hjälp av dessa riktlinjer kan du, om du har ett gäng funktioner som alla har att göra med att interagera med registret, ha något som liknar:

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

Modulmanifest

För att bygga vidare på textmodulsfilen kan du också inkludera ett modulmanifest. Dessa filer har ett PSD1-tillägg och innehåller metadata om modulen. Här kan du inkludera information om författare, beskrivning av modulen, andra nödvändiga moduler och många andra attribut. För att publicera till ett arkiv krävs att fälten Author och Description är ifyllda.

Här är ett exempel på ett manifest som vi kan ha för vår registermodul:

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

Och även om detta kan se skrämmande ut vid första anblicken har Microsoft en praktisk cmdlet som du kan använda för att generera ett modulmanifest. Det inkluderade kommandot är New-ModuleManifest. För att generera manifestet som visas ovan kan du använda:

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

Externa hjälpfiler

Du kan också se externa hjälpfiler i vissa moduler. De kan identifieras genom <ModuleName>-Help.xml i slutet av filnamnet. Dessa externa hjälpfiler innehåller samma information som normalt finns i den kommandobaserade hjälpen som du kan hitta i en funktionsdefinition.

Detta skulle också kräva att du lägger till # .ExternalHelp <ModulePath>-Help.xml till din funktion för att den ska fungera korrekt när du använder kommandot Get-Help efter att du importerat modulen. Det är vanligtvis bara vanligt att se externa hjälpfiler med mycket stora moduler och på grund av detta ligger de utanför tillämpningsområdet.

Men även om dessa är de vanligaste typerna av filer som du kommer att se i en modul, så är det inte de enda filerna. Ibland kommer du att se binära filer utöver en textmodul eftersom det finns andra beroenden. Genom att utforska modulens sökvägar kan du hitta många exempel på ytterligare filtyper i moduler.

För att få icke-standardiserade modulfiler korrekt publicerade skulle du inkludera andra filer i parametern FileList i ditt modulmanifest.

I modulmanifestet kommer du att märka många andra parametrar som för närvarande är tomma. Du kan använda dessa för att definiera andra krav för att använda din modul. Du kan till exempel definiera vilka versioner av PowerShell som modulen kan arbeta med. Om du försöker importera modulen på en PowerShell-version som inte stöds, är det här vad du skulle se:

PSRepositories

Ett av de viktigaste distributionsalternativen för moduler är ett PSRepository. Vid en 1000′ vy är ett PSRepository en lokal där flera personer eller flera enheter kan få tillgång till modulfilerna. Dessa är ofta webbservrar där du kan publicera filer.

Du kan också använda en katalog för repository, men detta begränsar dig i fråga om funktionaliteten hos ditt repository. Du kan vara värd för ett PSRepository själv, eller så kan du använda ett av de många alternativ som finns tillgängliga på Internet, till exempel PowerShell Gallery. Du kan se dina PSRepositories genom att använda kommandot Get-PSRepository.

Som standard kommer du bara att ha en post och den kommer att vara för PowerShell Gallery. Du kanske märker att det står untrusted. Detta beror på att PowerShell gör dig uppmärksam på att du genom att använda PowerShell Gallery kan använda kod som inte är skriven och godkänd av Microsoft. Detta innebär att du måste ge uttryckligt tillstånd innan några moduler installeras därifrån.

Lägga till PSRepositories

Du kan också lägga till dina egna repositories. Om du vill lita på PowerShell Gallery kan du köra Get-PSRepository -Name PSGallery | Set-PSRepository -InstallationPolicy Trusted eller acceptera varningen första gången du installerar en modul från PowerShell Gallery.

Alla kommandon som du skulle använda för att interagera med dessa PSRepositories finns i modulen PowerShellGet. Du kan se funktionerna här:

PowerShellGet-modulen kan behöva uppdateras för att kunna interagera med vissa repositories.

Söka efter moduler

En annan viktig funktion för att använda ett PSRepository är att kunna söka efter moduler. Detta görs med hjälp av kommandot Find-Module. Det finns flera sätt att filtrera för att hitta specifikt det du letar efter, men för tillfället kan du söka efter VMware-moduler så här:

Detta kommer att visa alla moduler som börjar med VMware. Även om de flesta av dessa är från VMware måste du titta på författarattributet för att se vem som publicerat modulen.

Då vem som helst kan ladda upp till PowerShell Gallery finns det tusentals moduler tillgängliga. Detta innebär att du kan hitta moduler som inte fungerar korrekt för ditt användningsområde. Många moduler som du hittar är öppen källkod så du kan bidra till dem för att förbättra modulens funktionalitet.

Installera moduler

För att kunna använda kommandot Install-Module måste du ha ett betrodd PSRepository som är värd för modulen. Detta kan vara PowerShell Gallery, ett annat PSRepository på internet eller en egenhästad webbplats. Du kan använda pipe från kommandot Find-Module för att vara tillgänglig för att enkelt kunna bekräfta modulen innan du installerar den.

Du kan också definiera versionen av en modul med hjälp av parametrarna MinimumVersion, MaximumVersion eller RequiredVersion.

För att se alla moduler som installerats med hjälp av Install-Module kan du använda Get-InstalledModule. Då visas alla moduler som installerats i AllUsers eller CurrentUser.

Avinstallera moduler

Samma som du kan installera en modul kan du också avinstallera en modul. Om modulen inte installerades via kommandot Install-Module kan du inte avinstallera den med kommandot Uninstall-Module.

Som du kan se här försöker vi avinstallera modulen ActiveDirectory. Eftersom den här modulen inte är installerad med Install-Module skulle du få ett fel när du försöker använda Uninstall-Module. För att du ska kunna avinstallera den här modulen måste vi avinstallera den genom att vända på det du använde för att installera modulen.

För att se en lyckad avinstallation av en modul kan du avinstallera modulen VMware.PowerCLI som du installerade tidigare.

Även om du avinstallerade VMware.PowerCLI kan du se att det fortfarande finns många beroenden som är installerade. Om du vill avinstallera alla moduler kan vi använda Get-InstalledModule VMware.* | Uninstall-Module -Force.

Anledningen till att du skulle ha sådana svårigheter att helt avinstallera den här modulen är att den har så många beroenden. Dessutom är vissa av dessa moduler beroende av varandra, vilket är anledningen till att parametern Force skulle behövas.

Uppdatering av moduler

Nu när du vet hur du installerar och avinstallerar en modul kanske du undrar hur du uppdaterar en modul som du har installerat.

Samma som för andra processer gäller att om modulen inte har installerats med hjälp av Install-Module, kan du inte uppdatera den med hjälp av PowerShell-kommandon. Du kan använda Update-Module för att uppdatera en modul till den senaste versionen eller till en nyare specifik version.

Det finns också en växel till AllowPreRelease som gör det möjligt att uppdatera till en version som inte har släppts officiellt. Ibland kan detta vara till hjälp eftersom det kan ha gjorts en korrigering av ett fel som du upplever eller en ny funktion som lagts till och som du skulle vilja använda.

Inspektion/Sparande av en modul

Ett av de mycket mindre använda kommandona som är till stor hjälp när du granskar moduler innan de används är Save-Module. Med detta kommando kan du ladda ner en modul till en sökväg utan att installera den.

Du kan sedan inspektera filerna och om modulen inte är en binär modul kan du öppna och titta på koden som utgör modulen. Detta kan vara bra inte bara för att se till att en modul inte gör något skadligt, utan också för att lära sig hur andra strukturerar sina moduler.

I det här exemplet hämtas inte bara modulen VMware.PowerCLI, utan även alla beroenden. Här är vad som visas i mappen VMware.PowerCLI:

Detta är ett bra exempel på att visa hur det ibland finns icke-standardiserade modulfiler som ingår i modulen, t.ex. licensavtalet för slutanvändare.

Skriva en egen modul

Du har nu sett hur man interagerar med någon annans modul. Nu vill du lära dig hur du skapar din egen så att du kan börja optimera din kod för skalbarhet.

Skapa mallfiler

Först måste du skapa en mapp för alla dina modulfiler. När du har behållaren måste du skapa din modulfil. Du måste se till att din modulfil har samma namn som din mapp, annars kommer PowerShell inte att upptäcka modulen korrekt när du försöker publicera din modul.

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

Nu vill du också använda ett manifest, du måste också namnge det på samma sätt som behållaren och modulfilen.

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'

Med behållaren, modulfilen och manifestfilen har du en fullt fungerande modul. Du kan publicera den här modulen i ett PSRepository och börja installera den var du vill. Fast eftersom modulfilen är tom kommer det förmodligen inte att göra någon större nytta för dig. Du kan ändå använda dessa filer för att testa publicering för att se till att ditt arkiv fungerar.

Registrera ett PSRepository

För att du ska kunna publicera din modul måste du lägga till ett annat PSRepository i din session. För testning kan du använda en lokal sökväg som ditt PSRepository eftersom det är lätt att installera och ta bort.

Normalt sett, om du skulle konfigurera ett PSRepository med en katalog, skulle du vilja se till att flera datorer kan komma åt det. Du kan skapa ett lokalt arkiv så här:

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

Om du bara skulle hämta från PSRepository och aldrig publicera kan du utesluta parametern PublishLocation.

Publicera din modul

Då du redan har ställt in installationspolicyn till betrodd kommer du inte att få någon bekräftelse för att tillåta att en modul installeras från arkivet. Nu när du har ett nytt PSRepository tillgängligt kan du publicera din modul med hjälp av Publish-Module -Name .\Scripts\ATARegistry -Repository LocalRepo.

När du har publicerat din modul kan du använda kommandona från ovan för att hitta modulen och installera den.

När du har installerat modulen kan du använda Get-Module för att se hur modulen importeras till din lokala session. Eftersom du inte lade till några funktioner till arrayen FunctionsToExport i manifestet är egenskapen ExportedCommands tom.

Lägga till din modul

Nu när du vet att du kan publicera och installera din modul kan du börja lägga till funktionalitet till den. Du kan lägga till en funktion som returnerar en registernyckel så att det ser ut så här:

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

Om du lämnar manifestet som det är och försöker ladda upp din nya modul skulle du stöta på två problem. Det första är att du skulle få ett felmeddelande om att versionen av din modul redan finns i ditt arkiv. Detta beror på att du inte har ändrat modulversionen i manifestfilen.

Exportera modulfunktioner

Det andra problemet skulle vara att efter att du importerat modulen skulle du fortfarande inte se några funktioner i egenskapen ExportedCommands eftersom du inte har lagt till din nya funktion i manifestet.

Samtidigt som din funktion skulle kunna användas utan att den listas i FunctionsToExport-listan, skulle det göra den mycket svårare att hitta.

För att åtgärda dessa två problem kan du uppdatera din modulfil på följande sätt:

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

Nu när du har lagt till en funktion i din modul och uppdaterat ditt manifest för att återspegla dessa ändringar kan du publicera den nya versionen av din modul genom att använda samma kommando som tidigare.

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

Uppdatering av din modul

Det sista steget skulle vara att du uppdaterar din modul i din session för att kunna använda de uppdaterade filerna. Med hjälp av Update-Module ATARegistry laddar du ner uppdateringen som du just publicerat till repository.

Nu kan du se att du har den nya versionen av modulen och du kan se funktionen som du har definierat i manifestet.

Byggande av hjälpinnehåll

Ett av alternativen som gick igenom tidigare är det hjälpsystem som är inbyggt i PowerShell. Du har förmodligen någon gång använt Get-Help på en funktion. Den här informationen kan läggas till på två primära sätt.

Det första är att lägga till kommentarsbaserad hjälp i funktionsdefinitionen. Detta är vanligtvis det sätt som många modulförfattare implementerar. Det andra sättet är att använda en extern hjälpfil. Du kan använda parametern Full för att visa allt som hjälpen har att erbjuda.

Som du kan se finns det verkligen inte mycket information och den lilla information du får skulle med största sannolikhet inte vara till hjälp för någon.

Du kan lägga till en del kommentarsbaserad hjälp i din modulfil för att fylla dessa fält i hjälpsystemet. Du kan läsa om alla alternativ för kommentarsbaserad hjälp genom att använda Get-Help about_Comment_Based_Help.

För tillfället kan du uppdatera din funktion så att den ser ut som nedan. Detta är en lista över de vanligaste hjälpparametrarna, men alla dessa är fortfarande valfria och det finns andra som kan läggas till i stället.

Nu ser din funktion ut så här:

 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}

Det finns en del speciella hjälpparametrar, som .FORWARDHELPTARGETNAME. Detta alternativ vidarebefordrar alla inkommande hjälpförfrågningar till ett annat kommando. Detta kan användas i ett fall där hjälpen ska visa samma information för flera kommandon.

När du nu har lagt till hjälpen kan du uppdatera versionen i modulmanifestet, publicera den nya versionen och uppdatera den installerade versionen för din session som du gjorde tidigare.

Om du nu tittar på hjälpen för funktionen kan du se att det finns mycket mer information tillgänglig. Detta är ett bra sätt att inkludera dokumentation om hur man använder funktionerna, särskilt för någon som har mindre erfarenhet och kanske inte snabbt kan förstå vad modulen gör genom att titta på koden.

I fallet med en extern hjälpfil är informationen som läggs till samma sak, men informationen placeras i en separat fil och länkas inom funktionen.

Om du tittar i modulsökvägen AllUsers kan du se modulens version och alla modulfiler som du har installerat.

Om du går tillbaka till din PSRepository-sökväg C:\Repo som du skapade tidigare kan du se ett gäng NUPKG-filer. Det kommer att finnas en för varje version som publicerats. Dessa är komprimerade versioner av det du publicerade när du använde Publish-Module.

Sammanfattning

När du har fått grepp om PowerShell-konsolen, PowerShell som språk och skrivande av skript är byggandet av egna moduler det sista steget. Moduler gör att du kan börja utveckla användbara verktyg i PowerShell. Om de utformas och byggs på rätt sätt genom att skapa moduler för ett enda syfte kommer du oundvikligen att upptäcka att du skriver mindre och mindre kod med tiden. Du kommer att börja referera till dina modulfunktioner i mer kod och bygga därifrån.

Modulfunktioner gör att du kan abstrahera bort den kod som du upptäcker att du upprepar i skript. De representerar ”etiketter” att referera till senare i kod som kan anropas när som helst i stället för att uppfinna hjulet på nytt och försöka komma på hur du redan tidigare hade uppnått ditt mål. Moduler är den slutliga ”förpackningen” av PowerShell-kod som grupperar ihop likartad kod för att undvika att slösa tid på problem som du redan har löst.