Adam Automator

Praca z modułami PowerShell jest ważnym elementem automatyzacji PowerShell. Kiedy zaczynasz uczyć się PowerShell, pierwsze kroki zwykle polegają na używaniu pojedynczych poleceń. Prowadzi to do budowania skryptów, które następnie prowadzą do budowania funkcji.

Używając funkcji, możesz uczynić swoje skrypty bardziej modularnymi. Pozwala to na używanie tego samego kodu w wielu miejscach bez konieczności kopiowania i wklejania kodu w każdym miejscu. Używanie funkcji pozwala Ci spędzić mniej czasu na edytowaniu tego samego kodu wszędzie, gdzie jest on używany. Zamiast tego możesz pracować nad ulepszaniem swojego kodu w jednym miejscu.

Aby przenieść funkcje na następny poziom, możesz połączyć te funkcje razem w moduł.

Moduł jest zbiorem funkcji w pliku tekstowym z rozszerzeniem psm1. Istnieją pewne opcjonalne dodatki, takie jak manifest modułu i pomoc oparta na komentarzach lub pomoc zewnętrzna, które również mogą być dołączone. Zostaną one omówione w dalszej części rozdziału.

Wymagania wstępne

W tym artykule będę używać programu Windows PowerShell 5.1. Jeśli używasz starszej wersji lub PowerShell Core, Twoje wyniki mogą się różnić.

Interakcja z modułami

Gdy po raz pierwszy otworzysz sesję PowerShell, zaczniesz od dwóch modułów. Pierwszym z nich jest Microsoft.PowerShell.Utility, który zawiera wiele podstawowych funkcji PowerShell, których już używasz. Drugim modułem jest PSReadline. Możesz zobaczyć te moduły startowe za pomocą polecenia Get-Module.

To powiedziawszy, nie jest to kompletna lista wszystkich dostępnych modułów. Od czasu PowerShell 3, moduły, które są zainstalowane będą importowane w razie potrzeby. Jeśli używasz starszej wersji PowerShell, będziesz musiał użyć polecenia Import-Module, aby najpierw zaimportować moduł przed użyciem któregokolwiek z poleceń.

Są sytuacje, w których nadal chciałbyś użyć Import-Module, nawet w późniejszych wersjach. Jeśli chciałbyś zaimportować moduł, gdy jest już zainstalowany, możesz użyć Import-Module w następujący sposób:

Podczas gdy Get-Module pokaże wszystkie zaimportowane moduły, nie zobaczysz modułów, które nie zostały jeszcze zaimportowane. Możesz wtedy użyć parametru ListAvailable, aby pokazać wszystkie inne moduły, które są dostępne.

Not all Commands are Shown By Default

Właściwość ExportedCommands zawiera listę wszystkich dostępnych poleceń, które są eksportowane z modułu. Możesz zobaczyć pewne różnice między tą listą a tym, co jest w pliku modułu. Eksportowane polecenia to cecha wbudowana w manifest modułu, która pozwala autorowi na pozostawienie funkcji jako ukrytej. Autorzy modułów mogą również używać cmdlet Export-ModuleMember, ale to jest poza zakresem tego artykułu.

Autorzy modułów mogą chcieć mieć ukrytą funkcję, ponieważ jest ona przeznaczona do wspierania innych funkcji, a nie być skierowana do użytkownika. Aby mieć ukrytą funkcję autor wykluczyłby ją z tablicy FunctionsToExport w manifeście. Tutaj możesz zobaczyć rozszerzony widok właściwości ExportedCommands.

Importowanie modułów

Istnieje wiele sposobów na rozpoczęcie używania modułów. Możesz ręcznie zaimportować moduł używając ścieżki do plików modułu. To pozwala ci być w stanie testować i aktualizować moduł bez konieczności wykonywania dużej ilości pracy. Ale to nie pozwala na wiele przenośności, ponieważ musiałbyś użyć dokładnej ścieżki do modułu. PowerShell nie będzie również automatycznie importował modułów, które nie znajdują się w zmiennej $env:PSModulePath.

Selektywne importowanie poleceń

Możesz użyć Import-Module, aby zaimportować tylko określone funkcje zamiast całego modułu za pomocą parametru Function. Może to zaoszczędzić czas podczas importowania modułów z systemów zdalnych, takich jak moduły Office 365.

Wszystkie moduły użytkownika

Moduły zainstalowane dla wszystkich użytkowników trafiają do katalogu C:\Program Files\WindowsPowerShell\Modules. Katalog ten zawiera wiele wstępnie dodanych modułów, w tym wszelkie moduły zainstalowane przy użyciu Install-Module z wykorzystaniem domyślnego zakresu AllUsers.

Current User Modules

Jeśli instalujesz moduł, ale chcesz, aby korzystał z niego tylko jeden użytkownik, istnieje zakres CurrentUser. To umieszcza pliki modułu w folderze Documents w C:\Users\<username>\Documents\WindowsPowerShell\Modules. Może to być przydatne w środowisku, w którym używasz przekierowania folderów z folderem Documents.

W tym przypadku możesz zainstalować moduł na jednym komputerze i używać go na innym, ponieważ oba będą współużytkować ten sam folder Documents.

Moduły systemowe

Dla kompletności, istnieje również katalog modułów w C:\WindowsSystem32\WindowsPowerShell\1.0\Modules. Chociaż technicznie rzecz biorąc, moduł umieszczony w tej ścieżce byłby importowany tak jak jedna z pozostałych ścieżek, ale nie jest to zalecane, ponieważ jest to zarezerwowane dla modułów systemowych Microsoftu.

Nazewnictwo jest ważne

Możesz ręcznie umieścić swój moduł w jednej z tych ścieżek, aby był dostępny domyślnie z nową sesją, ale musisz się upewnić, że przestrzegasz wymaganego nazewnictwa dla modułów. Folder, w którym umieszczone są pliki modułów, musi mieć taką samą nazwę jak plik modułu psm1 i manifest modułu psd1, jeśli taki istnieje.

Używanie Get-Module -ListAvailable, o którym wspomnieliśmy wcześniej, odwołuje się do tych ścieżek. Możesz zobaczyć wszystkie ścieżki do modułów używając $env:PSModulePath -Split ';'. Możesz zauważyć inne ścieżki na liście niż te, które są tutaj pokazane. Wiele programów dodaje swoje własne ścieżki modułów, gdy są instalowane. Jednym z przykładów jest SQL, który ma swoje własne moduły zawarte we własnych ścieżkach modułów.

Istnieją również pewne moduły, które można zainstalować za pomocą innego procesu. Jednym z najbardziej znaczących przykładów jest moduł ActiveDirectory. W systemach od Windows 7 do Windows 10 1803 można go zainstalować za pomocą instalatora Remote Server Administration Tools (RSAT).

W nowszych wersjach Windows 10 (1809+) jest on dostępny tylko poprzez Features On Demand. Instalacja RSAT instaluje moduły ActiveDirectory i wiele innych, których można używać do administrowania innymi rolami systemu Windows. Na serwerowych systemach operacyjnych Windows te moduły są instalowane za pośrednictwem Menedżera serwera.

Importowanie modułów zdalnych (Implicit Remoting)

Są pewne przypadki, w których nie jest praktyczne posiadanie modułu działającego lokalnie. Zamiast tego lepiej jest połączyć się ze zdalnym urządzeniem i zaimportować zainstalowany na nim moduł. Kiedy to zrobisz, polecenia są faktycznie wykonywane na zdalnej maszynie. Jest to często używane z modułami Office 365 firmy Microsoft. Wiele z nich łączy się z serwerem Office 365, który następnie importuje moduł. Kiedy uruchamiasz dowolne polecenia, są one uruchamiane na zdalnym serwerze, a następnie dane wyjściowe są wysyłane z powrotem do twojej sesji.

Innym zastosowaniem importowania zdalnych modułów jest sytuacja, gdy nie masz zainstalowanego modułu lokalnie. Oto, co byś otrzymał, gdybyś nie miał zainstalowanego modułu ActiveDirectory, ale próbował go zaimportować.

Aby zaimportować zdalny moduł, musisz najpierw utworzyć sesję PSSession. Możesz użyć New-PSSession, aby utworzyć sesję. Następnie zaimportowałbyś moduł dostępny na zdalnym urządzeniu, używając parametru PSSession z Import-Module.

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

Użycie tej metody importowania zdalnych modułów pozwala na szybsze wykonywanie kodu w środowisku rozproszonym. Na przykład, jeśli pracujesz na swoim komputerze, ale serwery, na których pracujesz, znajdują się w Stanach Zjednoczonych, wykonanie pewnych poleceń lokalnie przeciwko serwerom może zająć znacznie więcej czasu. Natomiast uruchomienie poleceń na serwerze i przekazanie danych wyjściowych z powrotem do sesji lokalnej jest znacznie szybsze.

Dodawanie prefiksu modułu

Możesz również dodać prefiks do funkcji importowanych ze zdalnej maszyny. Ta opcja jest dostępna podczas importowania modułów lokalnych, ale jest rzadko używana poza testowaniem różnych wersji modułu obok siebie.

Jeśli uruchomiłeś polecenie importu powyżej i to jest to, co byś zobaczył, gdy patrzysz na polecenia:

W tym przypadku możesz użyć przedrostka, aby pokazać, że nie jest to moduł lokalny. Może to być użyte w przypadkach, gdy importujesz moduł, który jest również dostępny lokalnie. Dodanie prefiksu zmniejsza zamieszanie co do miejsca wykonywania kodu.

Usuwanie modułów

Możesz również usunąć moduł z bieżącej sesji bez użycia Remove-Module. To usuwa moduł z sesji lokalnej bez usuwania plików modułu. Możesz chcieć użyć tego w przypadku, gdy używałeś zdalnej sesji do korzystania z modułu. Mógłbyś użyć Remove-Module, aby wyczyścić swoją sesję, a następnie odłączyć sesję zdalną.

Innym zastosowaniem Remove-Module jest sytuacja, gdy dokonujesz zmian w module i nie chcesz uruchamiać nowej sesji PowerShell. W tym przypadku użyłbyś Remove-Module, a następnie Import-Module, aby przeładować go do sesji. Alternatywnie możesz użyć parametru Force z Import-Module. To zakończy rozładowywanie i ponowne ładowanie modułu za Ciebie.

Co składa się na moduł PowerShell

Moduł może składać się z jednego lub więcej plików. Aby spełnić minimalne wymagania dla modułu, musisz mieć plik modułu. Może to być plik PSM1 lub jakikolwiek inny plik modułu, taki jak plik modułu binarnego. Aby się na tym oprzeć, twój psm1 powinien mieć zdefiniowane funkcje, lub nie będzie to zbyt użyteczne dla nikogo.

Choć nie ma wymagań co do tego jak funkcje powinny wyglądać lub co powinny robić, są pewne wytyczne. Zwykle preferuje się, aby wszystkie funkcje w module były zbudowane wokół tej samej koncepcji.

Moduły zawierają podobne funkcje

Na przykład moduł ActiveDirectory zawiera tylko funkcje, które w jakiś sposób współdziałają z Active Directory. Zazwyczaj nazwy funkcji zawierają również przedrostek. Wracając do modułu ActiveDirectory jako przykładu, wszystkie rzeczowniki w nazwach funkcji zaczynają się od AD.

Używanie tych wytycznych pomaga w odkrywaniu funkcji. Wyobraź sobie, że właśnie zaimportowałeś ten nowy moduł i chcesz przejrzeć wszystkie funkcje. Jest to znacznie łatwiejsze do zrobienia, jeśli wszystkie funkcje mają podobną strukturę nazw. Chociaż często można spotkać moduły zaczynające się od PS, ten przedrostek jest oficjalnie zarezerwowany tylko dla modułów Microsoft. Prawdopodobnie nie spowodujesz problemu, jeśli użyjesz PS na początku swojego modułu, możesz stworzyć konflikt z inną nazwą modułu.

Używając tych wytycznych, jeśli miałbyś kilka funkcji, które wszystkie miały do czynienia z interakcją z rejestrem, mógłbyś mieć coś w stylu:

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

Manifesty modułów

Aby rozwinąć plik modułu tekstowego, możesz również dołączyć manifest modułu. Te pliki mają rozszerzenie PSD1 i zawierają metadane o module. To jest miejsce, gdzie można zawrzeć informacje o autorze, opis modułu, inne wymagane moduły i wiele innych atrybutów. Aby opublikować do repozytorium, wymagane jest wypełnienie pól Author i Description.

Oto przykład manifestu, który możemy mieć dla naszego modułu rejestru:

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

Pomimo że na początku może to wyglądać niepokojąco, Microsoft ma poręczny cmdlet, którego można użyć do wygenerowania manifestu modułu. Dołączone polecenie to New-ModuleManifest. Aby wygenerować manifest pokazany powyżej, mógłbyś użyć:

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

Zewnętrzne pliki pomocy

Możesz również zobaczyć zewnętrzne pliki pomocy w niektórych modułach. Mogą one być identyfikowane przez <ModuleName>-Help.xml na końcu nazwy pliku. Te zewnętrzne pliki pomocy zawierają te same informacje, które normalnie byłyby zawarte w pomocy opartej na poleceniach, które możesz znaleźć w definicji funkcji.

To również wymagałoby dodania # .ExternalHelp <ModulePath>-Help.xml do twojej funkcji, aby działała poprawnie, gdy używasz polecenia Get-Help po zaimportowaniu modułu. Jest to zwykle tylko powszechne, aby zobaczyć zewnętrzne pliki pomocy z bardzo dużych modułów i dlatego są one poza zakresem.

Choć są to najczęstsze typy plików, które można zobaczyć w module, nie są to jedyne pliki. Czasami zobaczysz pliki binarne jako dodatek do modułu tekstowego, ponieważ istnieją inne zależności. Badając ścieżki modułu, można znaleźć wiele przykładów dodatkowych typów plików w modułach.

Aby mieć niestandardowe pliki modułu prawidłowo publikować należy dołączyć inne pliki w parametrze FileList w swoim module manifest.

Wewnątrz manifestu modułu, można zauważyć wiele innych parametrów, które są obecnie puste. Możesz ich użyć do zdefiniowania innych wymagań dotyczących używania twojego modułu. Na przykład, możesz zdefiniować wersje PowerShell, z którymi moduł może pracować. Jeśli spróbujesz zaimportować moduł na nieobsługiwanej wersji PowerShell, oto co byś zobaczył:

PSRepository

Jedną z kluczowych opcji dystrybucji modułów jest PSRepository. W widoku 1000′, PSRepository jest lokalnym miejscem, gdzie wiele osób lub wiele urządzeń może uzyskać dostęp do plików modułu. Są to często serwery internetowe, na których możesz publikować pliki.

Możesz również użyć katalogu dla repozytorium, ale to ogranicza cię w funkcjonalności twojego repozytorium. Możesz hostować PSRepository samodzielnie, lub skorzystać z jednej z wielu opcji dostępnych w Internecie, takich jak Galeria PowerShell. Możesz zobaczyć swoje PSRepozytoria za pomocą polecenia Get-PSRepository.

Domyślnie będziesz miał tylko jeden wpis i będzie on dotyczył Galerii PowerShell. Możesz zauważyć, że będzie tam napisane „niezaufane”. Jest to spowodowane tym, że PowerShell uświadamia, że używając Galerii PowerShell możesz używać kodu nie napisanego i nie zatwierdzonego przez Microsoft. Oznacza to, że zanim jakiekolwiek moduły zostaną z niej zainstalowane, będziesz musiał udzielić wyraźnego pozwolenia.

Dodawanie PSRepositories

Możesz również dodać własne repozytoria. Aby zaufać Galerii PowerShell, możesz uruchomić Get-PSRepository -Name PSGallery | Set-PSRepository -InstallationPolicy Trusted lub możesz zaakceptować ostrzeżenie przy pierwszej instalacji modułu z Galerii PowerShell.

Wszystkie polecenia, których używałbyś do interakcji z tymi PSRepositories można znaleźć w module PowerShellGet. Możesz zobaczyć te funkcje tutaj:

Moduł PowerShellGet może wymagać aktualizacji przed wejściem w interakcję z niektórymi repozytoriami.

Znajdowanie modułów

Kolejną kluczową cechą korzystania z PSRepository jest możliwość wyszukiwania modułów. Jest to osiągane za pomocą polecenia Find-Module. Istnieje wiele sposobów filtrowania, aby znaleźć konkretnie to, czego szukasz, ale na razie możesz wyszukać moduły VMware w następujący sposób:

Pokaże to wszystkie moduły, które zaczynają się od VMware. Chociaż większość z nich pochodzi od VMware, musisz spojrzeć na atrybut autora, aby zobaczyć, kto opublikował moduł.

Ponieważ każdy może przesłać moduł do galerii PowerShell, dostępne są tysiące modułów. Oznacza to, że możesz znaleźć moduły, które nie działają poprawnie dla twojego przypadku użycia. Wiele modułów, które znajdziesz są open source, więc możesz przyczynić się do nich, aby poprawić funkcjonalność modułu.

Instalowanie modułów

Aby użyć polecenia Install-Module, musisz mieć zaufane PSRepository, które hostuje moduł. Może to być Galeria PowerShell, inne internetowe PSRepository lub samodzielnie hostowana witryna. Możesz potokować z polecenia Find-Module, aby być dostępnym w celu łatwego potwierdzenia modułu przed jego zainstalowaniem.

Możesz również określić wersję modułu za pomocą parametrów MinimumVersion, MaximumVersion lub RequiredVersion.

Aby zobaczyć wszystkie moduły zainstalowane za pomocą Install-Module, możesz użyć Get-InstalledModule. Spowoduje to wyświetlenie listy wszystkich modułów zainstalowanych do zakresu AllUsers lub Twojego zakresu CurrentUser.

Odinstalowywanie modułów

Tak jak możesz zainstalować moduł, możesz również odinstalować moduł. Jeśli moduł nie został zainstalowany za pomocą polecenia Install-Module, nie można go odinstalować za pomocą polecenia Uninstall-Module.

Jak widać tutaj próbujemy odinstalować moduł ActiveDirectory. Ponieważ ten moduł nie jest zainstalowany z Install-Module, otrzymałbyś błąd przy próbie użycia Uninstall-Module. Abyś mógł odinstalować ten moduł, musielibyśmy go odinstalować poprzez odwrócenie tego, co zostało użyte do zainstalowania modułu.

Aby zobaczyć pomyślne odinstalowanie modułu, możesz odinstalować moduł VMware.PowerCLI, który zainstalowałeś wcześniej.

Mimo odinstalowania modułu VMware.PowerCLI można zauważyć, że nadal zainstalowanych jest wiele zależności. Gdybyśmy chcieli odinstalować wszystkie moduły, moglibyśmy użyć Get-InstalledModule VMware.* | Uninstall-Module -Force.

Powodem, dla którego miałbyś takie trudności z całkowitym odinstalowaniem tego modułu jest to, że ma on tak wiele zależności. Na dodatek niektóre z tych modułów są zależne od siebie nawzajem, dlatego parametr Force byłby wymagany.

Aktualizowanie modułów

Teraz, gdy wiesz, jak zainstalować i odinstalować moduł, możesz się zastanawiać, jak zaktualizować moduł, który został zainstalowany.

Tak jak w przypadku innych procesów, jeśli moduł nie został zainstalowany za pomocą Install-Module, nie można go zaktualizować za pomocą poleceń PowerShell. Możesz użyć Update-Module, aby zaktualizować moduł do najnowszego wydania lub do nowszej określonej wersji.

Jest też przełącznik do AllowPreRelease, który pozwoliłby ci zaktualizować do wersji, która nie została oficjalnie wydana. Czasami może to być pomocne, ponieważ mogła być poprawka do błędu, którego doświadczasz, lub nowa funkcja, która została dodana, której chciałbyś użyć.

Sprawdzanie/zapisywanie modułu

Jednym z dużo rzadziej używanych poleceń, które jest bardzo pomocne przy sprawdzaniu modułów przed użyciem, jest Save-Module. Używając tej komendy, możesz pobrać moduł na ścieżkę bez instalowania go.

Możesz wtedy sprawdzić pliki i jeśli moduł nie jest modułem binarnym, możesz otworzyć i spojrzeć na kod, który tworzy moduł. To może być dobre nie tylko do upewnienia się, że moduł nie robi nic złośliwego, ale także do nauki, jak inni konstruują swoje moduły.

W tym przykładzie nie tylko moduł VMware.PowerCLI jest pobierany, ale także wszystkie jego zależności. Oto co widać w folderze VMware.PowerCLI:

Jest to dobry przykład pokazujący, że czasami do modułu dołączane są niestandardowe pliki, takie jak umowa licencyjna użytkownika końcowego.

Pisanie własnego modułu

Zobaczyłeś już, jak współdziałać z cudzym modułem. Teraz chcesz się dowiedzieć, jak stworzyć własny, abyś mógł zacząć optymalizować swój kod pod kątem skalowalności.

Tworzenie plików szablonów

Najpierw musisz utworzyć folder dla wszystkich swoich plików modułów. Po tym jak masz kontener, musisz utworzyć swój plik modułu. Musisz upewnić się, że twój plik modułu ma taką samą nazwę jak folder, w przeciwnym razie podczas próby opublikowania modułu, PowerShell nie wykryje modułu poprawnie.

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

Teraz chcesz również użyć manifestu, będziesz musiał również nazwać go tak samo jak kontener i plik modułu.

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'

Z kontenerem, plikiem modułu i plikiem manifestu, masz w pełni funkcjonujący moduł. Mógłbyś opublikować ten moduł w PSRepository i zacząć go instalować gdziekolwiek byś chciał. Chociaż, ponieważ plik modułu jest pusty, prawdopodobnie nie przyniesie ci to wiele pożytku. Nadal możesz używać tych plików do testowego publikowania, aby upewnić się, że twoje repozytorium działa.

Rejestrowanie PSRepository

Zanim będziesz mógł opublikować swój moduł, będziesz musiał dodać kolejne PSRepository do swojej sesji. Do testowania, możesz użyć lokalnej ścieżki jako PSRepository, ponieważ będzie to łatwe do skonfigurowania i zniszczenia.

Normalnie, jeśli zamierzasz utworzyć PSRepository z katalogiem, chciałbyś się upewnić, że wiele komputerów może uzyskać do niego dostęp. Możesz utworzyć lokalne repozytorium w ten sposób:

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

Jeśli tylko pobierasz z PSRepository i nigdy nie publikujesz, możesz wykluczyć parametr PublishLocation.

Publikowanie modułu

Ponieważ ustawiłeś już politykę instalacji na zaufaną, nie otrzymasz potwierdzenia, aby zezwolić na instalację modułu z repozytorium. Teraz, gdy masz dostępne nowe PSRepository, możesz opublikować swój moduł używając Publish-Module -Name .\Scripts\ATARegistry -Repository LocalRepo.

Po opublikowaniu modułu, możesz użyć poleceń z góry, aby znaleźć moduł i zainstalować go.

Teraz, gdy zainstalowałeś moduł, możesz użyć Get-Module, aby zobaczyć moduł zaimportowany do twojej lokalnej sesji. Ponieważ nie dodałeś żadnych funkcji do tablicy FunctionsToExport w manifeście, właściwość ExportedCommands jest pusta.

Dodawanie do swojego modułu

Teraz, gdy wiesz, że możesz opublikować i zainstalować swój moduł, możesz zacząć dodawać do niego jakąś funkcjonalność. Możesz dodać funkcję, aby zwrócić klucz rejestru, więc wygląda to tak:

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

Jeśli zostawiłeś manifest jak jest i próbowałeś przesłać swój nowy moduł, napotkałbyś dwa problemy. Pierwszym z nich jest otrzymanie błędu stwierdzającego, że wersja twojego modułu już istnieje w twoim repozytorium. Dzieje się tak dlatego, że nie zmieniłeś wersji modułu w pliku manifestu.

Eksportowanie funkcji modułu

Drugim problemem byłoby to, że po zaimportowaniu modułu, nadal nie widziałbyś żadnych funkcji we właściwości ExportedCommands, ponieważ nie dodałeś swojej nowej funkcji do manifestu.

Choć twoja funkcja byłaby w stanie być używana bez wymieniania jej na liście FunctionsToExport, sprawiłoby to, że byłaby znacznie trudniejsza do zlokalizowania.

Aby naprawić te dwa problemy, możesz zaktualizować swój plik modułu w ten sposób:

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

Teraz, gdy dodałeś funkcję do swojego modułu i zaktualizowałeś swój manifest, aby odzwierciedlić te zmiany, możesz opublikować nową wersję swojego modułu, używając tego samego polecenia, co poprzednio.

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

Aktualizowanie swojego modułu

Ostatnim krokiem byłoby dla ciebie zaktualizowanie swojego modułu w sesji, aby móc używać zaktualizowanych plików. Używając Update-Module ATARegistry pobierasz aktualizację, którą właśnie opublikowałeś do repozytorium.

Teraz możesz zobaczyć, że masz nową wersję modułu i możesz zobaczyć funkcję, którą zdefiniowałeś w manifeście.

Budowanie zawartości pomocy

Jedną z opcji, która została przekazana wcześniej, jest system pomocy, który jest wbudowany w PowerShell. W pewnym momencie prawdopodobnie użyłeś Get-Help w jakiejś funkcji. Informacje te mogą być dodane na dwa podstawowe sposoby.

Pierwszym z nich jest dodanie pomocy opartej na komentarzach do definicji funkcji. Jest to zwykle sposób, który implementuje wielu autorów modułów. Drugim sposobem jest użycie zewnętrznego pliku pomocy. Możesz użyć parametru Full, aby pokazać wszystko, co pomoc ma do zaoferowania.

Jak widzisz, naprawdę nie ma zbyt wielu informacji, a te małe informacje, które dostajesz, najprawdopodobniej nie byłyby pomocne dla nikogo.

Możesz dodać trochę pomocy opartej na komentarzach do swojego pliku modułu, aby wypełnić te pola w systemie pomocy. Możesz przeczytać o wszystkich opcjach pomocy opartej na komentarzach, używając Get-Help about_Comment_Based_Help.

Na razie możesz zaktualizować swoją funkcję, aby wyglądała jak poniżej. Jest to lista najczęściej używanych parametrów pomocy, ale wszystkie z nich są nadal opcjonalne i istnieją inne, które można dodać zamiast nich.

Teraz twoja funkcja wygląda tak:

 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}

Istnieją pewne specjalne parametry pomocy, takie jak .FORWARDHELPTARGETNAME. Opcja ta przekazuje wszystkie przychodzące żądania pomocy do innego polecenia. Może to być użyte w przypadku, gdy pomoc powinna pokazywać te same informacje dla wielu poleceń.

Teraz, gdy dodałeś pomoc, możesz zaktualizować wersję w manifeście modułu, opublikować nową wersję i zaktualizować zainstalowaną wersję dla swojej sesji, tak jak zrobiłeś to wcześniej.

Jeśli teraz spojrzysz na pomoc dla funkcji, możesz zobaczyć, że dostępnych jest znacznie więcej informacji. Jest to świetny sposób na dołączenie dokumentacji dotyczącej korzystania z funkcji, szczególnie dla kogoś, kto ma mniejsze doświadczenie i może nie być w stanie szybko zrozumieć, co robi moduł, patrząc na kod.

W przypadku zewnętrznego pliku pomocy dodawane informacje są takie same, ale informacje są umieszczane w oddzielnym pliku i łączone wewnątrz funkcji.

Jeśli spojrzysz w ścieżkę modułu AllUsers, możesz zobaczyć wersję modułu i wszystkie pliki modułu, które instalowałeś.

Jeśli wrócisz do swojej ścieżki PSRepository C:™Repo, którą utworzyłeś wcześniej, możesz zobaczyć kilka plików NUPKG. Będzie tam jeden dla każdej wersji, która została opublikowana. Są to skompresowane wersje tego, co zostało opublikowane przy użyciu Publish-Module.

Podsumowanie

Po opanowaniu konsoli PowerShell, PowerShell jako języka i pisania skryptów, budowanie własnych modułów jest ostatnim krokiem. Moduły pozwalają na rozpoczęcie tworzenia użytecznych narzędzi w PowerShell. Jeśli są zaprojektowane i zbudowane poprawnie poprzez tworzenie modułów dla jednego celu, z czasem będziesz pisał coraz mniej kodu. Zaczniesz odwoływać się do swoich funkcji modułowych w większej ilości kodu i budować stamtąd.

Funkcje modułowe pozwalają wyabstrahować kod, który powtarzasz w skryptach. Reprezentują one „etykiety”, do których można się odwołać później w kodzie, a które można wywołać w dowolnym momencie, zamiast wymyślać koło na nowo i próbować dowiedzieć się, jak już wcześniej osiągnąłeś swój cel. Moduły są ostatecznym „opakowaniem” kodu PowerShell, które grupuje podobny kod, aby zapobiec marnowaniu czasu na problemy, które już rozwiązałeś.