Adam the Automator

Práce s moduly prostředí PowerShell je důležitou součástí automatizace prostředí PowerShell. Když se začínáte učit prostředí PowerShell, první kroky obvykle spočívají v používání jednotlivých příkazů. To vede k vytváření skriptů, které pak vedou k vytváření funkcí.

Pomocí funkcí můžete své skripty více modulovat. Díky tomu budete moci používat stejný kód na mnoha místech, aniž byste museli všude kopírovat a vkládat do kódu. Používání funkcí vám umožní strávit méně času prováděním stejných úprav stejného kódu všude, kde se používá. Místo toho můžete pracovat na vylepšení kódu na jediném místě.

Chcete-li funkce posunout na další úroveň, můžete tyto funkce spojit dohromady do modulu.

Modul je soubor funkcí v textovém souboru s příponou psm1. Součástí mohou být i některé volitelné doplňky, jako je manifest modulu a nápověda založená na komentářích nebo externí nápověda. Těm se budeme věnovat později.

Předpoklady

V tomto článku budu používat prostředí Prostředí Windows PowerShell 5.1.

. Pokud používáte starší verzi nebo jádro prostředí PowerShell, mohou se vaše výsledky lišit.

Interakce s moduly

Po prvním otevření relace prostředí PowerShell začnete se dvěma moduly. Prvním je Microsoft.PowerShell.Utility, který obsahuje mnoho základních funkcí prostředí PowerShell, které již používáte. Druhým modulem je PSReadline. Tyto počáteční moduly si můžete prohlédnout pomocí příkazu Get-Module.

Tento příkaz není úplným seznamem všech dostupných modulů. Od prostředí PowerShell 3 se nainstalované moduly importují podle potřeby. Pokud používáte starší verzi prostředí PowerShell, budete muset před použitím některého z příkazů nejprve použít příkaz Import-Module k importu modulu.

V některých případech by bylo vhodné použít příkaz Import-Module i v novějších verzích. Pokud byste chtěli importovat modul poté, co je již nainstalován, můžete použít Import-Module takto:

Přestože Get-Module zobrazí všechny importované moduly, moduly, které ještě nebyly importovány, neuvidíte. Pomocí parametru ListAvailable pak můžete zobrazit všechny ostatní dostupné moduly.

Ve výchozím nastavení nejsou zobrazeny všechny příkazy

Vlastnost ExportedCommands obsahuje seznam všech dostupných příkazů, které jsou z modulu exportovány. Mezi tímto seznamem a seznamem v souboru modulu mohou být určité rozdíly. Exportované příkazy je vlastnost zabudovaná do manifestu modulu, která umožňuje pisateli ponechat funkci jako skrytou. Autoři modulů mohou také použít rutinu Export-ModuleMember, ale to je mimo rozsah tohoto článku.

Autoři modulů mohou chtít mít funkci skrytou, protože je určena k podpoře jiných funkcí, nikoli k tomu, aby byla přístupná uživateli. Pokud chce mít autor funkci skrytou, vyloučí ji z pole FunctionsToExport v manifestu. Zde vidíte rozšířený pohled na vlastnost ExportedCommands.

Importování modulů

Existuje mnoho způsobů, jak začít používat moduly. Modul můžete importovat ručně pomocí cesty k souborům modulu. Díky tomu budete moci modul testovat a aktualizovat, aniž byste s tím měli mnoho práce. To však neumožňuje velkou přenositelnost, protože byste museli použít přesnou cestu k modulu. Prostředí PowerShell také nebude automaticky importovat moduly, které nejsou v proměnné $env:PSModulePath.

Selektivní import příkazů

Pomocí parametru Function můžete použít Import-Module pro import pouze určitých funkcí namísto celého modulu. To může ušetřit čas při importu modulů ze vzdálených systémů, například modulů Office 365.

Všechny uživatelské moduly

Moduly nainstalované pro všechny uživatele se umístí do C:\Program Files\WindowsPowerShell\Moduly. Tento adresář obsahuje mnoho předem přidaných modulů včetně všech modulů nainstalovaných pomocí Install-Module s použitím výchozího oboru AllUsers.

Moduly pro aktuální uživatele

Pokud instalujete modul, ale chcete, aby jej používal pouze jeden uživatel, je zde obor CurrentUser. Tím se soubory modulu umístí do složky Dokumenty na adresu C:\Users\<uživatelské jméno>\Documents\WindowsPowerShell\Moduly. To může být užitečné v prostředí, kde používáte přesměrování složek se složkou Dokumenty.

V tomto případě můžete modul nainstalovat na jeden počítač a používat ho na druhém, protože oba budou sdílet stejnou složku Dokumenty.

Systémové moduly

Pro úplnost je zde také adresář modulů na adrese C:\Windows\System32\WindowsPowerShell\1.0\Moduly. Technicky vzato by se sice modul umístěný v této cestě importoval stejně jako některá z ostatních cest, ale nedoporučuje se to, protože tato cesta je vyhrazena pro systémové moduly společnosti Microsoft.

Důležité je pojmenování

Modul můžete ručně umístit do jedné z těchto cest, aby byl ve výchozím nastavení k dispozici při nové relaci, ale musíte se ujistit, že dodržujete požadované pojmenování modulů. Složka, do které jsou soubory modulu umístěny, se musí jmenovat stejně jako soubor modulu psm1 a manifest modulu psd1, pokud existuje.

Použití Get-Module -ListAvailable, které jsme zmínili dříve, odkazuje na tyto cesty. Všechny cesty k modulům můžete zobrazit pomocí $env:PSModulePath -Split ';'. V seznamu si můžete všimnout i jiných cest, než které jsou zde uvedeny. Mnoho programů si při instalaci přidává vlastní cesty k modulům. Jedním z příkladů je SQL, který má své vlastní moduly zahrnuty ve vlastních cestách k modulům.

Existují také některé moduly, které byste nainstalovali jiným postupem. Jedním z nejvýznamnějších příkladů je modul ActiveDirectory. Od systému Windows 7 až do systému Windows 10 1803 byste jej nainstalovali pomocí instalačního programu Nástroje pro vzdálenou správu serveru (RSAT).

V novějších verzích systému Windows 10 (1809+) je k dispozici pouze prostřednictvím nástroje Funkce na vyžádání. Instalace RSAT nainstaluje moduly ActiveDirectory a mnoho dalších, které byste použili ke správě jiných rolí systému Windows. V serverových operačních systémech Windows se tyto moduly instalují prostřednictvím Správce serveru.

Import vzdálených modulů (Implicit Remoting)

V některých případech není praktické mít modul spuštěný lokálně. Místo toho je lepší připojit se ke vzdálenému zařízení a importovat modul nainstalovaný na něm. Když to uděláte, příkazy se skutečně provedou na vzdáleném zařízení. Tento postup se často používá u modulů Microsoft Office 365. Mnoho z nich se připojuje k serveru Office 365, který pak importuje modul. Když spustíte některý z příkazů, spustí se na vzdáleném serveru a výstup se pak odešle zpět do vaší relace.

Další využití importu vzdálených modulů je, když nemáte modul nainstalovaný lokálně. To by se stalo, kdybyste neměli nainstalovaný modul ActiveDirectory, ale pokusili byste se ho importovat.

Chcete-li importovat vzdálený modul, musíte nejprve vytvořit relaci PSSession. K vytvoření relace můžete použít New-PSSession. Poté byste importovali modul dostupný na vzdáleném zařízení pomocí parametru PSSession s Import-Module.

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

Použití této metody importu vzdálených modulů umožňuje rychlejší provádění kódu v distribuovaném prostředí. Pokud například pracujete ze svého počítače, ale servery, na kterých pracujete, jsou na druhém konci USA, může lokální spuštění některých příkazů proti serverům trvat podstatně déle. Zatímco spuštění příkazů na serveru a předání výstupu zpět do místní relace je mnohem rychlejší.

Přidání předpony modulu

Můžete také přidat předponu na funkce importované ze vzdáleného počítače. Tato možnost je k dispozici při importu lokálních modulů, ale mimo testování různých verzí modulu vedle sebe se používá jen zřídka.

Pokud byste spustili výše uvedený příkaz import a při pohledu na příkazy byste viděli toto:

V tomto případě můžete použít předponu, která ukáže, že se nejedná o lokální modul. Toho lze využít v případech, kdy importujete modul, který je dostupný i lokálně. Přidání předpony snižuje zmatek v tom, kde se kód spouští.

Odebrání modulů

Modul můžete také odebrat z aktuální relace bez použití Remove-Module. Tím odstraníte modul z místní relace, aniž byste odstranili soubory modulu. To můžete chtít použít v případě, kdy jste k použití modulu používali vzdálenou relaci. Pomocí Remove-Module můžete relaci vyčistit a poté vzdálenou relaci odpojit.

Další použití Remove-Module je v případě, že provádíte změny modulu a nechcete spouštět novou relaci prostředí PowerShell. V takovém případě byste použili Remove-Module následovaný Import-Module pro jeho opětovné načtení do relace. Alternativně můžete použít parametr Force s Import-Module. To za vás dokončí vyjmutí a opětovné načtení modulu.

Co tvoří modul prostředí PowerShell

Modul se může skládat z jednoho nebo více souborů. Abyste splnili minimální požadavky na modul, musíte mít soubor modulu. Může to být soubor PSM1 nebo jakýkoli jiný soubor modulu, například soubor binárního modulu. Abyste na něm mohli stavět, měl by váš psm1 obsahovat definované funkce, jinak nebude nikomu k ničemu.

Ačkoli neexistují žádné požadavky na to, jak by funkce měly vypadat nebo co by měly dělat, existují určité zásady. Obvykle se dává přednost tomu, aby všechny funkce v modulu byly postaveny na stejném konceptu.

Moduly obsahují podobně zaměřené funkce

Například modul ActiveDirectory obsahuje pouze funkce, které nějakým způsobem komunikují s Active Directory. Názvy funkcí obvykle obsahují také předponu. Vrátíme-li se zpět k modulu ActiveDirectory jako k příkladu, všechna podstatná jména v názvech funkcí začínají na AD.

Používání těchto pokynů pomáhá při vyhledávání funkcí. Představte si, že jste právě importovali tento nový modul a chcete procházet funkce na kartě. To je mnohem snazší, pokud mají všechny funkce podobnou strukturu názvů. I když se můžete často setkat s moduly začínajícími na PS, tato předpona je oficiálně vyhrazena pouze pro moduly společnosti Microsoft. Pokud na začátku modulu použijete předponu PS, pravděpodobně tím nezpůsobíte problém, můžete však vyvolat konflikt s názvem jiného modulu.

Podle těchto pokynů, pokud byste měli několik funkcí, které by všechny měly co do činění s interakcí s registrem, mohli byste mít něco takového:

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

Manifesty modulů

Chcete-li navázat na textový soubor modulu, můžete také připojit manifest modulu. Tyto soubory mají příponu PSD1 a obsahují metadata o modulu. Zde byste uvedli informace o autorovi, popis modulu, další požadované moduly a mnoho dalších atributů. Pro publikování do úložiště je nutné, aby byla vyplněna pole Author a Description.

Tady je příklad manifestu, který můžeme mít pro náš modul registru:

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

Ačkoli to může na první pohled vypadat hrozivě, společnost Microsoft má k dispozici praktickou rutinu, pomocí které můžete manifest modulu vygenerovat. Obsažený příkaz je New-ModuleManifest. Pro vygenerování výše uvedeného manifestu byste mohli použít:

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

Externí soubory nápovědy

V některých modulech se mohou objevit i externí soubory nápovědy. Mohly by být identifikovány pomocí <Název modulu>-Help.xml na konci názvu souboru. Tyto externí soubory nápovědy obsahují stejné informace, které by normálně byly obsaženy v příkazové nápovědě, kterou můžete najít v definici funkce.

Také byste museli do funkce přidat # .ExternalHelp <ModulePath>-Help.xml, aby správně fungovala při použití příkazu Get-Help po importu modulu. S externími soubory nápovědy se obvykle běžně setkáte jen u velmi rozsáhlých modulů a díky tomu jsou mimo rozsah.

Přestože se jedná o nejčastější typy souborů, které v modulu uvidíte, nejsou to soubory jediné. Někdy uvidíte kromě textového modulu i binární soubory, protože existují další závislosti. Prozkoumáním cest k modulům můžete najít mnoho příkladů dalších typů souborů v modulech.

Chcete-li správně publikovat nestandardní soubory modulu, měli byste do parametru FileList v manifestu modulu zahrnout další soubory.

V manifestu modulu si všimnete mnoha dalších parametrů, které jsou v současné době prázdné. Pomocí nich můžete definovat další požadavky na používání vašeho modulu. Můžete například definovat verze prostředí PowerShell, se kterými může modul pracovat. Pokud byste se pokusili modul importovat v nepodporované verzi prostředí PowerShell, zobrazilo by se toto:

PSRepository

Jednou z klíčových možností distribuce modulů je PSRepository. Při pohledu 1000′ je PSRepository místním místem, kde může k souborům modulu přistupovat více lidí nebo více zařízení. Často se jedná o webové servery, kde můžete publikovat soubory.

Pro úložiště můžete také použít adresář, ale to vás omezuje ve funkčnosti úložiště. Úložiště PSRepository můžete hostovat sami nebo můžete využít některou z mnoha možností dostupných na internetu, například galerii PowerShell. Své úložiště PSRepositories můžete zobrazit pomocí příkazu Get-PSRepository.

Ve výchozím nastavení budete mít pouze jednu položku, a to pro galerii PowerShell. Můžete si všimnout, že u ní bude uvedeno nedůvěryhodné. Je to proto, že vás prostředí PowerShell upozorňuje, že používáním Galerie PowerShell můžete používat kód, který nebyl napsán a schválen společností Microsoft. To znamená, že před instalací jakýchkoli modulů z ní budete muset udělit výslovné povolení.

Přidání PSRepozitářů

Můžete také přidat vlastní repozitáře. Chcete-li Galerii PowerShell důvěřovat, můžete spustit příkaz Get-PSRepository -Name PSGallery | Set-PSRepository -InstallationPolicy Trusted nebo můžete přijmout varování při první instalaci modulu z Galerie PowerShell.

Všechny příkazy, které byste použili k interakci s těmito PSRepository, najdete v modulu PowerShellGet. Jednotlivé funkce si můžete prohlédnout zde:

Před interakcí s některými úložišti může být nutné aktualizovat modul PowerShellGet.

Vyhledávání modulů

Další klíčovou funkcí používání úložiště PSRepository je možnost vyhledávání modulů. To se provádí pomocí příkazu Find-Module. Existuje více způsobů, jak filtrovat, abyste našli konkrétně to, co hledáte, ale prozatím můžete vyhledávat moduly VMware takto:

Tímto způsobem se zobrazí všechny moduly začínající na VMware. I když většina z nich pochází od společnosti VMware, musíte se podívat na atribut autora, abyste zjistili, kdo modul publikoval.

Protože do Galerie PowerShell může nahrávat kdokoli, jsou k dispozici tisíce modulů. To znamená, že můžete najít moduly, které pro váš případ použití nefungují správně. Mnoho nalezených modulů má otevřený zdrojový kód, takže do nich můžete přispět a vylepšit tak funkčnost modulu.

Instalace modulů

Chcete-li použít příkaz Install-Module, musíte mít důvěryhodné úložiště PSRepository, které modul hostuje. Může to být Galerie prostředí PowerShell, jiné internetové úložiště PSRepository nebo vlastní hostovaný web. Můžete použít rouru z příkazu Find-Module, abyste měli k dispozici snadné potvrzení modulu před jeho instalací.

Můžete také určit verzi modulu pomocí parametrů MinimumVersion, MaximumVersion nebo RequiredVersion.

Chcete-li zobrazit všechny moduly nainstalované pomocí příkazu Install-Module, můžete použít parametr Get-InstalledModule. Zobrazí se seznam všech modulů nainstalovaných do oboru AllUsers nebo vašeho oboru CurrentUser.

Odinstalování modulů

Stejně jako můžete modul nainstalovat, můžete modul také odinstalovat. Pokud modul nebyl nainstalován příkazem Install-Module, nemůžete jej odinstalovat příkazem Uninstall-Module.

Jak vidíte, zde se snažíme odinstalovat modul ActiveDirectory. Protože tento modul není nainstalován pomocí Install-Module, došlo by při pokusu o použití Uninstall-Module k chybě. Abyste mohli tento modul odinstalovat, museli bychom jej odinstalovat pomocí obráceného postupu, který jste použili při instalaci modulu.

Chcete-li vidět úspěšné odinstalování modulu, můžete odinstalovat modul VMware.PowerCLI, který jste nainstalovali dříve.

Přestože jste odinstalovali modul VMware.PowerCLI, můžete vidět, že je stále nainstalováno mnoho závislostí. Pokud byste chtěli odinstalovat všechny moduly, mohli bychom použít Get-InstalledModule VMware.* | Uninstall-Module -Force.

Důvodem, proč byste měli takové potíže s úplným odinstalováním tohoto modulu, je to, že má mnoho závislostí. Navíc některé z těchto modulů jsou závislé na sobě navzájem, což je důvod, proč by byl vyžadován parametr Force.

Aktualizace modulů

Když už víte, jak modul nainstalovat a odinstalovat, možná vás zajímá, jak nainstalovaný modul aktualizovat.

Stejně jako u jiných procesů, pokud modul nebyl nainstalován pomocí Install-Module, nelze jej aktualizovat pomocí příkazů prostředí PowerShell. Pomocí Update-Module můžete modul aktualizovat na nejnovější vydání nebo na novější konkrétní verzi.

Existuje také přepínač AllowPreRelease, který by vám umožnil aktualizovat na verzi, která nebyla oficiálně vydána. Někdy to může pomoci, protože mohla být opravena chyba, se kterou se potýkáte, nebo byla přidána nová funkce, kterou byste chtěli používat.

Kontrola/uložení modulu

Jeden z mnohem méně používaných příkazů, který je velmi užitečný při prověřování modulů před použitím, je Save-Module. Pomocí tohoto příkazu můžete modul stáhnout do cesty, aniž byste jej instalovali.

Soubory pak můžete zkontrolovat, a pokud se nejedná o binární modul, můžete je otevřít a podívat se na kód, který modul tvoří. To může být dobré nejen pro ujištění, že modul nedělá nic škodlivého, ale také pro zjištění, jak své moduly strukturují ostatní.

V tomto příkladu je stažen nejen modul VMware.PowerCLI, ale také všechny závislosti. Zde je uvedeno, co se zobrazí ve složce VMware.PowerCLI:

Tento příklad dobře ukazuje, jak jsou někdy součástí modulu nestandardní soubory, například licenční ujednání s koncovým uživatelem.

Psaní vlastního modulu

Teď jste viděli, jak komunikovat s cizím modulem. Nyní se chcete naučit, jak vytvořit svůj vlastní, abyste mohli začít optimalizovat svůj kód pro škálovatelnost.

Vytvoření souborů šablony

Nejprve musíte vytvořit složku pro všechny soubory modulu. Poté, co máte kontejner, musíte vytvořit soubor modulu. Musíte se ujistit, že soubor modulu má stejný název jako složka, jinak při pokusu o publikování modulu prostředí PowerShell modul správně neobjeví.

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

Nyní chcete použít také manifest, budete ho muset také pojmenovat stejně jako kontejner a soubor modulu.

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'

S kontejnerem, souborem modulu a souborem manifest máte plně funkční modul. Tento modul můžete publikovat do úložiště PSRepository a začít jej instalovat kamkoli chcete. I když vzhledem k tomu, že soubor modulu je prázdný, pravděpodobně vám to nebude k ničemu. Přesto můžete tyto soubory použít k testování publikování, abyste se ujistili, že vaše úložiště funguje.

Registrace úložiště PSRepository

Předtím, než budete moci svůj modul publikovat, budete muset do relace přidat další úložiště PSRepository. Pro účely testování můžete jako úložiště PSRepository použít místní cestu, protože bude snadné jej zřídit a zrušit.

Obvykle, pokud byste se chystali zřídit úložiště PSRepository s adresářem, byste chtěli zajistit, aby k němu mělo přístup více počítačů. Místní úložiště můžete vytvořit takto:

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

Pokud byste z PSRepository pouze stahovali a nikdy nepublikovali, mohli byste vyloučit parametr PublishLocation.

Publikování modulu

Protože jste již nastavili zásady instalace na důvěryhodné, nedostanete potvrzení o povolení instalace modulu z úložiště. Nyní, když máte k dispozici nové úložiště PSRepository, můžete svůj modul publikovat pomocí příkazu Publish-Module -Name .\Scripts\ATARegistry -Repository LocalRepo.

Po publikování modulu můžete pomocí výše uvedených příkazů modul najít a nainstalovat.

Teď, když jste modul nainstalovali, můžete pomocí příkazu Get-Module zobrazit modul importovaný do místní relace. Protože jste do pole FunctionsToExport v manifestu nepřidali žádné funkce, je vlastnost ExportedCommands prázdná.

Doplňování modulu

Teď, když víte, že můžete publikovat a nainstalovat svůj modul, můžete do něj začít přidávat některé funkce. Můžete přidat funkci, která vrátí klíč registru, takže to bude vypadat takto:

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

Pokud byste nechali manifest tak, jak je, a pokusili se nahrát svůj nový modul, narazili byste na dva problémy. Prvním je, že byste obdrželi chybové hlášení, že verze vašeho modulu již v úložišti existuje. Je to proto, že jste v souboru manifestu nezměnili verzi modulu.

Export funkcí modulu

Druhým problémem by bylo, že po importu modulu byste ve vlastnosti ExportedCommands stále neviděli žádné funkce, protože jste do manifestu nepřidali svou novou funkci.

Vaši funkci by sice bylo možné používat bez uvedení v seznamu FunctionsToExport, ale bylo by mnohem obtížnější ji najít.

Abyste tyto dva problémy vyřešili, můžete soubor svého modulu aktualizovat takto:

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

Teď, když jste do svého modulu přidali funkci a aktualizovali svůj manifest tak, aby tyto změny odrážel, můžete novou verzi svého modulu publikovat pomocí stejného příkazu jako předtím.

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

Aktualizace modulu

Posledním krokem by pro vás bylo aktualizovat svůj modul v relaci, abyste mohli používat aktualizované soubory. Pomocí Update-Module ATARegistry stáhnete aktualizaci, kterou jste právě publikovali do úložiště.

Nyní vidíte, že máte novou verzi modulu a vidíte funkci, kterou jste definovali v manifestu.

Vytvoření obsahu nápovědy

Jednou z možností, která byla předána dříve, je systém nápovědy, který je zabudován do prostředí PowerShell. Pravděpodobně jste někdy použili Get-Help u nějaké funkce. Tyto informace lze přidat dvěma základními způsoby.

Prvním je přidání nápovědy založené na komentářích do definice funkce. Tento způsob obvykle implementuje mnoho autorů modulů. Druhým způsobem je použití externího souboru nápovědy. Pomocí parametru Full můžete zobrazit vše, co nápověda nabízí.

Jak vidíte, informací opravdu není mnoho a to málo informací, které získáte, by s největší pravděpodobností nikomu nepomohlo.

Do souboru modulu můžete přidat nápovědu založenou na komentářích, která tato pole v systému nápovědy vyplní. O všech možnostech nápovědy založené na komentářích si můžete přečíst pomocí Get-Help about_Comment_Based_Help.

Prozatím můžete svou funkci aktualizovat tak, aby vypadala následovně. Jedná se o seznam nejčastěji používaných parametrů nápovědy, ale všechny tyto parametry jsou stále volitelné a místo nich lze přidat další.

Nyní vaše funkce vypadá takto:

 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}

Existují některé speciální parametry nápovědy, například .FORWARDHELPTARGETNAME. Tato volba přeposílá všechny příchozí požadavky na nápovědu na jiný příkaz. To lze použít v případě, kdy má nápověda zobrazovat stejné informace pro více příkazů.

Teď, když jste přidali nápovědu, můžete aktualizovat verzi v manifestu modulu, publikovat novou verzi a aktualizovat nainstalovanou verzi pro relaci, jak jste to udělali dříve.

Pokud se nyní podíváte do nápovědy k funkci, uvidíte, že je k dispozici mnohem více informací. To je skvělý způsob, jak zahrnout dokumentaci k používání funkcí, zejména pro někoho, kdo je méně zkušený a nemusí být schopen rychle pochopit, co modul dělá při pohledu na kód.

V případě externího souboru nápovědy jsou přidané informace stejné, ale informace jsou umístěny v samostatném souboru a propojeny v rámci funkce.

Podíváte-li se do cesty k modulu AllUsers, uvidíte verzi modulu a všechny soubory modulu, které jste instalovali.

Pokud se vrátíte do cesty k úložišti PSRepository C:\Repo, kterou jste vytvořili dříve, uvidíte spoustu souborů NUPKG. Pro každou zveřejněnou verzi bude jeden. Jedná se o komprimované verze toho, co jste publikovali při použití Publish-Module.

Souhrn

Když už ovládáte konzolu PowerShell, PowerShell jako jazyk a psaní skriptů, je posledním krokem vytvoření vlastních modulů. Moduly vám umožní začít vyvíjet užitečné nástroje v prostředí PowerShell. Pokud jsou moduly správně navrženy a sestaveny vytvořením modulů pro jeden účel, nevyhnutelně zjistíte, že časem budete psát méně a méně kódu. Na funkce modulů začnete odkazovat v dalších částech kódu a z nich budete vycházet.

Funkce modulů vám umožní abstrahovat kód, který se vám ve skriptech opakuje. Představují „štítky“, na které se můžete později v kódu odkazovat a které lze kdykoli zavolat, místo abyste znovu vynalézali kolo a snažili se přijít na to, jak jste již dříve dosáhli svého cíle. Moduly představují konečné „balení“ kódu prostředí PowerShell, které seskupuje podobně zaměřený kód, abyste nemuseli ztrácet čas řešením již vyřešených problémů.