Tworzymy moduł: od czego zacząć?

First-StepDawno 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ć. Winking smile „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”. Winking smile

Tworzenie-Modułu-PowerShell

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.files.wordpress.com/2020/04/powershellpl.png'
}
}
}
view raw PowerShellPL.psd1 hosted with ❤ by GitHub

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.

~ - autor: Bartek Bielawski w dniu 24 kwietnia, 2020.

Skomentuj

Wprowadź swoje dane lub kliknij jedną z tych ikon, aby się zalogować:

Logo WordPress.com

Komentujesz korzystając z konta WordPress.com. Wyloguj /  Zmień )

Zdjęcie na Google

Komentujesz korzystając z konta Google. Wyloguj /  Zmień )

Zdjęcie z Twittera

Komentujesz korzystając z konta Twitter. Wyloguj /  Zmień )

Zdjęcie na Facebooku

Komentujesz korzystając z konta Facebook. Wyloguj /  Zmień )

Połączenie z %s

 
%d blogerów lubi to: