Tworzymy moduł: od czego zacząć?
Dawno temu napisałem krótką serię o tym jak wyglądają moduły w PowerShellu. Tym postem chciałbym rozpocząć cykl, w którym spróbuję się podzielić moimi doświadczeniami dotyczącymi tworzenia modułów. Wiele z zawartych tu rad bierze się wprost z kilkuletniego doświadczenia w pracy nad modułami w ramach kilkuosobowego zespołu. Mam nadzieję, że choć część uwag/ spostrzeżeń/ rad przyda Wam się w trakcie tworzenia własnych modułów, czy to na potrzeby firmy, w której pracujecie, czy to na potrzeby wspólnoty w ramach platform takich jak GitHub.
Od razu ostrzegam: ten cykl klasyfikowałbym raczej jeden z „zaawansowanych” i zakładać będę, że wiecie czym jest moduł w PowerShellu, jak pracować z gitem (na bardzo podstawowym poziomie) i raczej nie będę przybliżał podstaw dotyczących pisania kodu w PowerShellu. Zakładam też, że macie pomysł na swój moduł – czy to będzie narzędzie do zarządzania urządzeniem IoT, moduł do konfiguracji sieci czy zarządzania SCCM – nie będzie miało wielkiego znaczenia, ale oczywiście musicie najpierw mieć o czym pisać. 
„Spoiler alert” zaliczony – zaczynajmy więc!
Myślę, że bardzo ważne jest to, by zaraz na początku wybrać zestaw narzędzi, którymi będziemy się posługiwać. Z mojego punktu widzenia absolutnie niezbędne elementy to:
- platforma, w której umieszczać będziemy współdzielony kod
- narzędzie do zarządzania zmianami w kodzie, takie jak git (w zasadzie trudno mi znaleźć uzasadnienie, by korzystać z czegoś innego niż git, ale warto sprawdzić, czy inne narzędzie nie sprawdzi się lepiej)
- coś do testów jednostkowych (kodowi bez takich testów raczej bym nie ufał…)
- coś, co przeprowadzi automatyczną „budowę” naszego kodu
W firmie korzystamy z narzędzi takich, jakie zastaliśmy (zatrudnionych jest u nas sporo programistów, więc większość narzędzi nam potrzebnych było już dostępnych), ale w ramach tego cyklu skorzystamy z narzędzi nieco innych:
- kod przechowywać będziemy na GitHubie
- testować będziemy Pesterem (jedyny przypadek, gdzie rozwiązanie pokrywać się będzie z tym, co używamy w firmie)
- automatycznie budować będzie dla nas AppVeyor (dostępny w ramach GitHuba i radzący sobie świetnie z kodem w PowerShellu)
Wybór narzędzi jest o tyle istotny, że może on również wpływać na to, jak skonstruowany będzie nasz moduł.
Tworzymy repozytorium
Zanim napiszemy pierwszą linijkę kodu – warto już uprzednio utworzyć odpowiednie repozytorium. Im wcześniej zaczniemy śledzić zmiany w naszym kodzie, tym większą korzyść zyskamy z używania tego typu narzędzi.
Repozytorium możemy utworzyć od razu na GitHubie (zalecane rozwiązanie), bądź najpierw utworzyć moduł lokalnie a następnie dokonać synchronizacji ze zdalnym repozytorium. Wybór pierwszej opcji dodatkowo oferuje nam proste instrukcje jak zadbać o repozytorium na naszym lokalnym komputerze.
Tworząc moduł na GitHubie warto od razu zdecydować na jakiej licencji zamierzamy udostępniać nasz kod. Ja zwykle wybieram licencję MIT – czyli „róbta co chceta”.
Tak utworzone repozytorium musimy pobrać na naszym systemie korzystając z klonowania. Następnie tworzymy prosty plik README.md i przesyłamy na serwer. Repozytorium mamy przygotowane.
| git clone git@github.com:bielawb/PowerShellPL.git | |
| Set-Location .\PowerShellPL | |
| Set-Content README.md -Value @' | |
| # Moduł PowerShellPL | |
| Moduł na potrzeby serii postów o tworzeniu modułów w PowerShellu. | |
| '@ -Encoding UTF8 | |
| git add README.md | |
| git commit -m 'Dodajemy pierwotną wersję README' | |
| git push origin master |
Na razie nasz kod „popchnęliśmy” na gałęź master, prawdopodobnie pierwszy i ostatni raz. Wrócimy do tego w kolejnej części cyklu, gdzie omówimy pracę z gitem. Na razie utwórzmy jeszcze jeden element absolutnie niezbędny: manifest naszego modułu.
Tworzenie manifestu
PowerShell oferuje nam polecenie New-ModuleManifest, dzięki któremu dość szybko utworzyć możemy manifest dla naszego modułu. Raczej odradzałbym tworzenia tego pliku „na piechotę”. Równie mocno odradzałbym poprzestanie na skorzystaniu z tego polecenia.
| mkdir PowerShellPL | |
| New-ModuleManifest -Path PowerShellPL\PowerShellPL.psd1 -Author 'Bartek Bielawski' -ModuleVersion 1.0.0 | |
| psedit PowerShellPL\PowerShellPL.psd1 |
Plik manifestu zawiera wszystkie możliwe informacje, warto pozbyć się wszystkiego, co nie przyda nam się w tworzonym przez nas module. Pozostawimy więc informacje meta takie jak wersja, autor, opis. Warto zadbać o statyczną listę eksportowanych poleceń: funkcji i aliasów. W module przez nas tworzonym (jeśli nie zamierzamy korzystać z plików binarnych) innych typów poleceń mieć nie będziemy. Raczej nie będziemy eksportować żadnych zmiennych. Wreszcie – sekcja PSData. Tam umieścimy dodatkowe informacje, które PowerShell wykorzysta w trakcie publikowania modułu w galerii modułów. Po naszych zmianach manifest może wyglądać następująco:
| @{ | |
| # Plik w którym definiowane będą nasze funkcje. | |
| RootModule = 'PowerShellPL.psm1' | |
| # Wersja naszego modułu. | |
| ModuleVersion = '1.0.0' | |
| # Unikalny identyfikator. | |
| GUID = '2909cfd3-3dde-43f7-b210-bb2943485681' | |
| # Coś o tfórcy... | |
| Author = 'Bartek Bielawski' | |
| CompanyName = 'PowerShellPL.NET' | |
| Copyright = '(c) 2020 Bartek Bielawski. All rights reserved.' | |
| # Opis naszego modułu. | |
| Description = 'Demo na potrzeby bloga' | |
| # Eksportujemy... póki co wielkie nic. | |
| FunctionsToExport = @() | |
| CmdletsToExport = @() | |
| VariablesToExport = @() | |
| AliasesToExport = @() | |
| PrivateData = @{ | |
| PSData = @{ | |
| # Tagi - pomogą w szukaniu modułu | |
| Tags = @( | |
| 'Demo' | |
| ) | |
| # Linki rozmaite... | |
| LicenseUri = 'https://opensource.org/licenses/MIT' | |
| ProjectUri = 'https://github.com/bielawb/PowerShellPL' | |
| IconUri = 'https://powershellpl.net/wp-content/uploads/2020/04/powershellpl.png' | |
| } | |
| } | |
| } |
Dodajemy plik manifestu do naszego repozytorium (nadal na gałęzi master) i przesyłamy do GitHuba. Tak oto utworzyliśmy nasz moduł. Na razie nie da się z niego korzystać (bez poleceń moduł raczej nie ma racji bytu), ale już teraz moglibyśmy go opublikować w PowerShell Gallery. W kolejnej części cyklu przyjrzymy się temu, jak możemy tworzyć nasz moduł korzystając z gita do przechowywania informacji o zmianach w naszym kodzie.
PowerShell po polsku 
