PowerShell po polsku

Coś nie specjalnie (póki co) udaje mi się dotrzymać obietnicy – pisuję nadal rzadko. Cóż jednak zrobić, gdy doba nie chce się wydłużyć, a ilość rzeczy do zrobienia piętrzy się nieustannie. Dziś jednak w końcu mam chwilkę czasu, wypada więc zamknąć to, co zaczęliśmy jakiś czas temu.

W pierwszej części napisaliśmy banalnie prosty moduł. Przyjrzeliśmy się temu, jak utworzyć odpowiedni projekt, pobrać niezbędne biblioteki i wreszcie – jak przyjrzeć się naszemu modułowi w debuggerze. Dziś przyjrzymy się temu, jak wokół modułu binarnego zbudować pełny moduł: z manifestem, plikami pomocy, formatów i typów.

Manifest

Tworzenie manifestu nie wymaga od nas zbyt wiele pracy. Mamy do tego wszak polecenie (New-ModuleManifest), które utworzy dla nas manifest z wypełnionymi odpowiednimi polami. W zależności od wykorzystywanej przez nas wersji PowerShella wymogi i finalny dokument mogą się różnić, istotne jest jednak to, że nawet jeśli niektóre opcje pominiemy w trakcie jego uruchamiania, to w samym dokumencie znajdą się one również, będą jedynie oznaczone jako komentarze.

W naszym wypadku na tym etapie podać powinniśmy jedynie trzy parametry: ścieżkę do głównego pliku modułu (RootModule), ścieżkę do pliku tworzonego (Path) i listę eksportowanych przez nasz moduł cmdletów (dość skromną):

$param = @{            
    Path = 'Przywitania.psd1'             
    RootModule = 'Przywitania.dll'             
    CmdletsToExport = 'Write-Hello'            
}            
New-ModuleManifest @param

Uzupełniać manifest będziemy w miarę potrzeb o pozostałe elementy. Na etapie obecnym nie ma takiej potrzeby.

Format i typy

Polecenie definiowane przez nasz moduł średnio nadaje się do tego, by wzbogacać je o dodatkowe formaty (zwracać wszak będzie jedynie ciąg znaków) czy dodatkowe właściwości i metody (znów ten sam problem: trudno o sensowne rozszerzenia dla prostego ciągu znaków). Wspomnę więc jedynie o tym, jak wygląda procedura ich tworzenia.

W przypadku typów tworzymy plik XML (a dokładniej: ps1xml) i uzupełniamy go o informację o wszelkich właściwościach (głównie skryptowych i stanowiących wynik wykonania metody) i metodach (znów: przeważać będą metody skryptowe). Względną ścieżkę do utworzonego pliku (lub plików) umieścimy w manifeście jako wartość właściwości TypesToProcess.

Pliki formatu na ogół są bardziej rozbudowane. Umieścimy w nich informację o tym jak prezentować się mają obiekty opisywanych typów. Możemy dla każdego z nich zdefiniować kilka widoków. Szczególnie cenne jest zdefiniowanie takiego widoku dla każdego z dostępnych formatów: tabeli, listy czy widoku szerokiego. Każdy typ widoku wymaga od nas nieco innych informacji. Aby dowiedzieć się, jak taki plik powinien wyglądać, warto przyjrzeć się plikom istniejącym.

Gdy plik (lub pliki) już powstaną, wystarczy dodać je jako wartość parametru FormatsToProcess.

W obu przypadkach wystarczy "odblokować" odpowiednie linie i przekazać ścieżki (względne) do odpowiednich plików:

# Type files (.ps1xml) to be loaded when importing this module            
# TypesToProcess = @()            
            
# Format files (.ps1xml) to be loaded when importing this module            
# FormatsToProcess = @()            

Oferowana składnia nie pozostawia wątpliwości, że obie właściwości moduły stanowić mogą kolekcję.

Pomoc

W przypadku modułów skryptowych pomoc do poleceń umieścimy w formie komentarza, razem z funkcjami, których będzie ona dotyczyć. Nie mamy oczywiście takiej możliwości w przypadku modułów binarnych. W tej sytuacji sięgnąć musimy po pliki MAML.

Problem z plikami tego typu wynika z faktu, że nie ma zbyt wielu narzędzi, które wspomogą nas w ich tworzeniu. Możliwości mamy w zasadzie dwie: darmowy "PowerShell Cmdlet Help Editor" oraz płatny produkt firmy Sapien "PowerShell HelpWriter". Ten ostatni możemy wypróbować, korzystając przy tym z 45-dniowej wersji próbnej. Przyjrzymy się obu alternatywom.

PowerShell Cmdlet Help Editor

Produkt ten pobrać możemy ze strony projektu, w ramach którego był tworzony. Projekt ten znajdziemy na stronie codeplex.com. Po zainstalowaniu i uruchomieniu przywita nas strona zawierające instrukcje, jak z programu tego skorzystać:

Ponieważ program ten współpracuje jedynie z modułami "zainstalowanymi" (czyli takimi, które znajdują się w $Env:PSModulePath) musimy wcześniej zadbać o to, by moduł przez nas tworzony tam umieścić. Po wybraniu naszego modułu z listy pojawi się lista zawartych w nim poleceń:

Na tym etapie elementy tworzące pomoc (widoczne po prawej stronie) są niedostępne, musimy najpierw wybrać polecenie, którego pomoc zamierzamy stworzyć. Po zatwierdzeniu tego wyboru możemy przystąpić do uzupełniania poszczególnych elementów pomocy.

Po uzupełnieniu wszystkich pól, musimy pomoc wyeksportować do pliku (Actions -> Publish XML Help to file). Warto też zapisać zmiany: jeśli zechcemy pomoc zmienić, wystarczy plik taki wczytać. Teoretycznie można wczytać wyeksportowany plik, ale na ogół wygodniej jest skorzystać bezpośrednio z uprzednio przygotowanego projektu. Ważne, by eksportując pomoc zadbać o dwie rzeczy: odpowiednią lokalizację i nazwę tworzonego pliku pomocy. W zależności od wykorzystywanych przez nas ustawień regionalnych, musimy plik pomocy umieścić w jednym z dwóch folderów:

• domyślnie wykorzystywanym folderze en-US
• folderze, którego nazwa pokrywa się z ustawieniami regionalnymi naszego systemu ($PSUICulture).

Nazwa pliku pokrywa się częściowo z nazwą modułu binarnego. Do pełnej nazwy dodać musimy jedynie końcówkę informującą o tym, że mamy do czynienia z pomocą, oraz informację o typie pliku:

ls ~\Documents\WindowsPowerShell\Modules\Przywitania\en-US

Wynik wykonania tego polecenia:

Zanim przyjrzymy się temu, jak działa nasza pomoc, spróbujemy podobną procedurę przeprowadzić z wykorzystaniem produktu firmy Sapien.

PowerShell HelpWriter

Produkt firmy Sapien jest stosunkowo krótko na rynku. Trzeba jednak przyznać, że już w obecnej wersji spełnia większość wymogów, które przed produktem tego typu można postawić. Cena nie jest wygórowana a zanim dokonamy zakupu, możemy produkt ten przetestować.

Zanim przystąpimy do pisania pomocy, mamy dwie możliwości: wczytać utworzony uprzednio plik XML, bądź utworzyć nową pomoc w oparciu jedynie o składnię naszego polecenia. W tym drugim przypadku skorzystamy z opcji "New Help File (From Module)":

Po wybraniu odpowiedniego modułu z listy znów przedstawiony nam zostanie zestaw możliwych elementów pomocy. Jeśli wczytaliśmy uprzednio utworzoną pomoc, to część opcji będzie już uzupełniona. W każdej chwili możemy się przełączyć na widok XML, co pozwoli nam przy okazji tworzenia pomocy dowiedzieć się nieco więcej o tym, jak to "naprawdę" działa.

Gdy jesteśmy już zadowoleni z rezultatów naszej pracy, pozostaje jedynie pomoc w odpowiednim formacie zapisać do pliku. Warto zwrócić uwagę, że ścieżkę do tego pliku podać musimy już na samym początku, zaraz po wczytaniu informacji z "żywego" modułu.

Co dalej? Mamy manifest, mamy pomoc. Pora przyjrzeć się nieco praktyczniejszym poleceniom po to, by skorzystać z plików typów i formatów. I przede wszystkim – by zrozumieć, kiedy moglibyśmy zechcieć moduł binarny utworzyć. Temu zagadnieniu poświęcona będzie trzecia część tego cyklu.

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

Napisane w PowerShell
Tagi: moduł binarny, moduły PowerShella, narzędzia, pomoc