PowerShellGallery Publishing Guidelines and Best Practices

Artykuł
10/04/2023

W tym artykule opisano zalecane kroki używane przez zespoły firmy Microsoft w celu zapewnienia, że pakiety opublikowane w Galeria programu PowerShell będą powszechnie stosowane i zapewniają użytkownikom wysoką wartość w zależności od tego, jak Galeria programu PowerShell obsługuje dane manifestu i opinie od dużej liczby osób Galeria programu PowerShell użytkowników. Pakiety publikowane zgodnie z tymi wytycznymi będą częściej instalowane, zaufane i przyciągają większej liczby użytkowników.

Poniżej przedstawiono wskazówki dotyczące tego, co sprawia, że dobry pakiet Galeria programu PowerShell, jakie opcjonalne ustawienia manifestu są najważniejsze, ulepszając kod przy użyciu opinii od wstępnych recenzentów i analizatora skryptów programu PowerShell, przechowywania wersji modułu, dokumentacji, testów i przykładów używania elementów udostępnionych. Większość tej dokumentacji jest zgodna z wytycznymi dotyczącymi publikowania modułów zasobów DSC wysokiej jakości.

Aby zapoznać się z mechaniką publikowania pakietu w Galeria programu PowerShell, zobacz Tworzenie i publikowanie pakietu.

Opinie na temat tych wytycznych są mile widziane. Jeśli masz opinię, otwórz problemy w naszym repozytorium dokumentacji usługi GitHub.

Najlepsze rozwiązania dotyczące publikowania pakietów

Poniższe najlepsze rozwiązania to to, co mówią użytkownicy Galeria programu PowerShell elementów, jest ważne i są wymienione w kolejności nominalnego priorytetu. Pakiety zgodne z tymi wytycznymi są znacznie bardziej prawdopodobne, aby zostały pobrane i przyjęte przez inne osoby.

Korzystanie z narzędzia PSScriptAnalyzer
Dołączanie dokumentacji i przykładów
Odpowiadaj na opinie
Udostępnianie modułów, a nie skryptów
Podawanie linków do witryny projektu
Tagowanie pakietu przy użyciu zgodnych elementów PSEdition i platform
Dołączanie testów do modułów
Dołącz i/lub link do postanowień licencyjnych
Podpisywanie kodu
Postępuj zgodnie z wytycznymi SemVer dotyczącymi przechowywania wersji
Używanie typowych tagów, jak opisano w artykule Common Galeria programu PowerShell tags (Typowe tagi Galeria programu PowerShell)
Testowanie publikowania przy użyciu repozytorium lokalnego
Publikowanie przy użyciu modułu PowerShellGet

Każdy z nich jest krótko omówiony w poniższych sekcjach.

Korzystanie z narzędzia PSScriptAnalyzer

PSScriptAnalyzer to bezpłatne narzędzie do analizy kodu statycznego, które działa w kodzie programu PowerShell. Narzędzie PSScriptAnalyzer zidentyfikuje najczęstsze problemy występujące w kodzie programu PowerShell i często zaleca sposób rozwiązania problemu. Narzędzie jest łatwe w użyciu i kategoryzuje problemy jako Błędy (poważne, należy rozwiązać), Ostrzeżenie (należy je przejrzeć i rozwiązać) oraz Informacje (warto zapoznać się z najlepszymi rozwiązaniami). Wszystkie pakiety opublikowane w Galeria programu PowerShell będą skanowane przy użyciu narzędzia PSScriptAnalyzer, a wszelkie błędy zostaną zgłoszone z powrotem do właściciela i należy rozwiązać ten problem.

Najlepszym rozwiązaniem jest uruchomienie polecenia Invoke-ScriptAnalyzer z elementami -Recurse i -Severity Ostrzeżenie.

Przejrzyj wyniki i upewnij się, że:

Wszystkie błędy są poprawiane lub rozwiązywane w dokumentacji.
Wszystkie ostrzeżenia są przeglądane i rozwiązywane, jeśli ma to zastosowanie.

Użytkownicy pobierający pakiety z Galeria programu PowerShell są zdecydowanie zachęcani do uruchamiania narzędzia PSScriptAnalyzer i oceniania wszystkich błędów i ostrzeżeń. Użytkownicy są bardzo skłonni skontaktować się z właścicielami pakietów, jeśli zobaczą, że wystąpił błąd zgłoszony przez narzędzie PSScriptAnalyzer. Jeśli istnieje przekonujący powód, dla którego pakiet ma zachować kod oznaczony jako błąd, dodaj te informacje do dokumentacji, aby uniknąć wielokrotnego odpowiadania na to samo pytanie.

Dołączanie dokumentacji i przykładów

Dokumentacja i przykłady to najlepszy sposób, aby zapewnić użytkownikom możliwość korzystania z dowolnego udostępnionego kodu.

Dokumentacja jest najbardziej przydatna do uwzględnienia w pakietach publikowanych w Galeria programu PowerShell. Użytkownicy zazwyczaj pomijają pakiety bez dokumentacji, ponieważ alternatywą jest odczytanie kodu w celu zrozumienia, czym jest pakiet i jak go używać. Dostępnych jest kilka artykułów dotyczących udostępniania dokumentacji pakietów programu PowerShell, w tym:

Wskazówki dotyczące zapewniania pomocy znajdują się w temacie How to Write Cmdlet Help (Jak napisać pomoc poleceń cmdlet).
Tworzenie pomocy polecenia cmdlet, która jest najlepszym rozwiązaniem dla dowolnego skryptu, funkcji lub polecenia cmdlet programu PowerShell. Aby uzyskać informacje na temat tworzenia pomocy dotyczącej poleceń cmdlet, zacznij od tematu How to Write Cmdlet Help (Jak napisać pomoc dotyczącą poleceń cmdlet). Aby dodać pomoc w skrycie, zobacz About Comment Based Help (Informacje o pomocy opartej na komentarzach).
Wiele modułów zawiera również dokumentację w formacie tekstowym, takim jak pliki MarkDown. Może to być szczególnie przydatne w przypadku witryny projektu w usłudze GitHub, w której język Markdown jest w dużym stopniu używanym formatem. Najlepszym rozwiązaniem jest użycie języka Markdown o różnych wersjach usługi GitHub.

Przykłady pokazują użytkownikom, jak pakiet ma być używany. Wielu deweloperów powie, że przyjrzy się przykładom przed dokumentacją, aby zrozumieć, jak z nich korzystać. Najlepsze typy przykładów pokazują podstawowe użycie, a także symulowany realistyczny przypadek użycia, a kod jest dobrze skomentowany. Przykłady modułów opublikowanych w Galeria programu PowerShell powinny znajdować się w folderze Examples w folderze głównym modułu.

Dobry wzorzec przykładów można znaleźć w module PSDscResource w folderze Examples\RegistryResource . Istnieją cztery przykładowe przypadki użycia z krótkim opisem w górnej części każdego pliku, który dokumentuje, co jest pokazane.

Zarządzanie zależnościami

Ważne jest, aby określić moduły zależne od modułu w manifeście modułu. Dzięki temu użytkownik końcowy nie musi martwić się o zainstalowanie odpowiednich wersji modułów, od których zależy Użytkownik. Aby określić moduły zależne, należy użyć pola wymaganego modułu w manifeście modułu. Spowoduje to załadowanie wszystkich modułów wymienionych do środowiska globalnego przed zaimportowaniem modułu, chyba że zostały już załadowane. Na przykład niektóre moduły mogą być już załadowane przez inny moduł. Można również określić określoną wersję do załadowania przy użyciu pola RequiredVersion , a nie pola ModuleVersion . W przypadku korzystania z funkcji ModuleVersion zostanie załadowana najnowsza wersja dostępna z minimalną określoną wersją. Jeśli nie używasz pola RequiredVersion , aby określić określoną wersję, ważne jest, aby monitorować aktualizacje wersji wymaganego modułu. Szczególnie ważne jest, aby pamiętać o wszelkich zmianach powodujących niezgodność, które mogą mieć wpływ na środowisko użytkownika w module.

Example: RequiredModules = @(@{ModuleName="myDependentModule"; ModuleVersion="2.0"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Example: RequiredModules = @(@{ModuleName="myDependentModule"; RequiredVersion="1.5"; Guid="cfc45206-1e49-459d-a8ad-5b571ef94857"})

Odpowiadanie na opinie

Właściciele pakietów, którzy odpowiednio reagują na opinie, są bardzo cenni przez społeczność. Użytkownicy, którzy przekazują konstruktywne opinie, są ważne, aby reagować, ponieważ są wystarczająco zainteresowani pakietem, aby spróbować go ulepszyć.

W Galeria programu PowerShell jest dostępna jedna metoda przesyłania opinii:

Właściciel kontaktu: umożliwia użytkownikowi wysłanie wiadomości e-mail do właściciela pakietu. Jako właściciel pakietu ważne jest monitorowanie adresu e-mail używanego z pakietami Galeria programu PowerShell i reagowanie na zgłaszane problemy. Jedną wadą tej metody jest to, że tylko użytkownik i właściciel kiedykolwiek zobaczą komunikację, więc właściciel może wielokrotnie odpowiedzieć na to samo pytanie.

Właściciele, którzy reagują na opinie konstruktywnie, są doceniani przez społeczność. Użyj szansy sprzedaży w raporcie, aby poprosić o więcej informacji. W razie potrzeby podaj obejście lub określ, czy aktualizacja rozwiązuje problem.

Jeśli z jednego z tych kanałów komunikacyjnych zaobserwowano niewłaściwe zachowanie, użyj funkcji Zgłaszanie nadużyć w Galeria programu PowerShell, aby skontaktować się z administratorami galerii.

Moduły a skrypty

Udostępnianie skryptu innym użytkownikom jest doskonałe i udostępnia innym osobom przykłady rozwiązywania problemów, które mogą mieć. Problem polega na tym, że skrypty w Galeria programu PowerShell to pojedyncze pliki bez oddzielnej dokumentacji, przykładów i testów.

Moduły programu PowerShell mają strukturę folderów, która umożliwia dołączanie wielu folderów i plików do pakietu. Struktura modułu umożliwia uwzględnienie innych pakietów, które udostępniamy jako najlepsze rozwiązania: pomoc poleceń cmdlet, dokumentację, przykłady i testy. Największą wadą jest to, że skrypt wewnątrz modułu musi być uwidoczniony i używany jako funkcja. Aby uzyskać informacje na temat tworzenia modułu, zobacz Pisanie modułu Windows PowerShell.

Istnieją sytuacje, w których skrypt zapewnia lepsze środowisko dla użytkownika, szczególnie w przypadku konfiguracji DSC. Najlepszym rozwiązaniem dla konfiguracji DSC jest opublikowanie konfiguracji jako skryptu z towarzyszącym modułem zawierającym dokumenty, przykłady i testy. Skrypt wyświetla listę towarzyszących modułów przy użyciu polecenia RequiredModules = @(Name of the Module). Tego podejścia można użyć z dowolnym skryptem.

Autonomiczne skrypty zgodne z innymi najlepszymi rozwiązaniami zapewniają realną wartość innym użytkownikom. Udostępnianie dokumentacji opartej na komentarzach i linku do witryny projektu jest zdecydowanie zalecane podczas publikowania skryptu w Galeria programu PowerShell.

Podaj link do witryny projektu

Witryna projektu umożliwia wydawcy bezpośrednią interakcję z użytkownikami pakietów Galeria programu PowerShell. Użytkownicy preferują pakiety, które to udostępniają, ponieważ pozwala im łatwiej uzyskać informacje o pakiecie. Wiele pakietów w Galeria programu PowerShell jest opracowywanych w usłudze GitHub. Inne są dostarczane przez organizacje z dedykowaną obecnością w Internecie. Każda z nich może być uznawana za witrynę projektu.

Dodanie linku odbywa się przez dołączenie identyfikatora ProjectURI w sekcji PSData manifestu w następujący sposób:

  # A URL to the main website for this project.
  ProjectUri = 'https://github.com/powershell/powershell'

Po podaniu identyfikatora ProjectURI Galeria programu PowerShell będzie zawierać link do witryny projektu po lewej stronie pakietu.

Tagowanie pakietu przy użyciu zgodnych elementów PSEdition i platform

Użyj następujących tagów, aby zademonstrować użytkownikom, którzy pakiety będą dobrze współdziałać ze swoim środowiskiem:

PSEdition_Desktop: pakiety zgodne z Windows PowerShell
PSEdition_Core: pakiety zgodne z programem PowerShell 6 i nowszym
Windows: pakiety zgodne z systemem operacyjnym Windows
Linux: pakiety zgodne z systemami operacyjnymi Linux
MacOS: pakiety zgodne z systemem operacyjnym Mac

Oznaczając pakiet zgodnymi platformami, zostaną one uwzględnione w filtrach wyszukiwania galerii w okienku po lewej stronie wyników wyszukiwania. Jeśli hostujesz pakiet w usłudze GitHub, podczas tagowania pakietu możesz również skorzystać z naszego przykładu tarczy zgodności z osłonami zgodności Galeria programu PowerShell.

Dołączanie testów

Dołączanie testów z kodem typu open source jest ważne dla użytkowników, ponieważ daje im pewność, co weryfikujesz, i udostępnia informacje o sposobie działania kodu. Umożliwia również użytkownikom zapewnienie, że nie przerywają oryginalnej funkcjonalności, jeśli zmodyfikują kod w celu dopasowania ich do środowiska.

Zdecydowanie zaleca się napisanie testów w celu skorzystania z platformy testowej Pester, która została zaprojektowana specjalnie dla programu PowerShell. Pester jest dostępny w serwisie GitHub, Galeria programu PowerShell i dostarczanych w Windows 10, Windows Server 2016, WMF 5.0 i WMF 5.1.

Witryna projektu Pester w usłudze GitHub zawiera dobrą dokumentację dotyczącą pisania testów Pester, od rozpoczęcia pracy z najlepszymi rozwiązaniami.

Cele pokrycia testów są wywoływane w dokumentacji modułu zasobów wysokiej jakości z zalecanym pokryciem kodu testu jednostkowego 70%.

Dołącz i/lub link do postanowień licencyjnych

Wszystkie pakiety opublikowane w Galeria programu PowerShell muszą określać postanowienia licencyjne lub być powiązane przez licencję zawartą w Warunkach użytkowania w ramach wystawy A. Najlepszym podejściem do określenia innej licencji jest podanie linku do licencji przy użyciu identyfikatora LicenseURI w pliku PSData. Aby uzyskać więcej informacji, zobacz Manifest pakietów i Interfejs użytkownika galerii.

PrivateData = @{
    PSData = @{

        # Tags applied to this module. These help with module discovery in online galleries.
        Tags = @('.net','acl','active-directory')

        # A URL to the license for this module.
        LicenseUri = 'http://www.apache.org/licenses/LICENSE-2.0'

Podpisywanie kodu

Podpisywanie kodu zapewnia użytkownikom najwyższy poziom zapewniania, kto opublikował pakiet, oraz że kopia uzyskanego kodu jest dokładnie tym, co wydawca wydał. Aby dowiedzieć się więcej na temat podpisywania kodu ogólnie, zobacz Wprowadzenie do podpisywania kodu. Program PowerShell obsługuje walidację podpisywania kodu za pomocą dwóch podstawowych metod:

Podpisywanie plików skryptów
Podpisywanie katalogu modułu

Podpisywanie plików programu PowerShell to dobrze ugruntowane podejście do zapewnienia, że wykonywany kod został utworzony przez niezawodne źródło i nie został zmodyfikowany. Szczegółowe informacje na temat podpisywania plików skryptów programu PowerShell opisano w artykule About Signing (Informacje o podpisywaniu ). W przeglądzie można dodać podpis do dowolnego .PS1 pliku, który program PowerShell weryfikuje podczas ładowania skryptu. Program PowerShell można ograniczyć przy użyciu poleceń cmdlet zasad wykonywania w celu zapewnienia korzystania z podpisanych skryptów.

Moduły podpisywania wykazu to funkcja dodana do programu PowerShell w wersji 5.1. Jak podpisać moduł został omówiony w artykule Catalog Cmdlets (Polecenia cmdlet wykazu ). W przeglądzie podpisywanie wykazu odbywa się przez utworzenie pliku wykazu zawierającego wartość skrótu dla każdego pliku w module, a następnie podpisanie tego pliku.

Polecenia cmdlet PowerShellGetPublish-Module, Install-Modulei Update-Module sprawdzają podpis, aby upewnić się, że jest prawidłowy, a następnie upewnij się, że wartość skrótu dla każdego pakietu jest zgodna z tym, co znajduje się w wykazie. Save-Module nie weryfikuje podpisu. Jeśli poprzednia wersja modułu jest zainstalowana w systemie, potwierdzi, że urząd podpisywania dla nowej wersji jest zgodny z tym, Install-Module co zostało wcześniej zainstalowane. Install-Module i Update-Module użyje podpisu w .PSD1 pliku, jeśli pakiet nie jest podpisany. Podpisywanie wykazu działa z programem, ale nie zastępuje plików skryptów podpisywania. Program PowerShell nie weryfikuje podpisów wykazu w czasie ładowania modułu.

Postępuj zgodnie z wytycznymi SemVer dotyczącymi przechowywania wersji

SemVer to publiczna konwencja, która opisuje sposób struktury i zmiany wersji, aby umożliwić łatwą interpretację zmian. Wersja pakietu musi być uwzględniona w danych manifestu.

Wersja powinna być ustrukturyzowana jako trzy bloki liczbowe oddzielone kropkami, tak jak w 0.1.1 systemie lub 4.11.192.
Wersje rozpoczynające się od 0 wskazują, że pakiet nie jest jeszcze gotowy do produkcji, a pierwsza liczba powinna zaczynać się 0 tylko wtedy, gdy jest to jedyna liczba użyta.
Zmiany w pierwszej liczbie (1.9.9999 do 2.0.0) wskazują na poważne i powodujące niezgodność zmiany między wersjami.
Zmiany w drugim numerze (1.1 do 1.2) wskazują zmiany na poziomie funkcji, takie jak dodawanie nowych poleceń cmdlet do modułu.
Zmiany trzeciej liczby wskazują na zmiany powodujące niezgodność, takie jak nowe parametry, zaktualizowane przykłady lub nowe testy.
Podczas wyświetlania listy wersji program PowerShell posortuje wersje jako ciągi, więc 1.01.0 będzie traktowany jako większy niż 1.001.0.

Program PowerShell został utworzony przed opublikowaniem programu SemVer, dlatego zapewnia obsługę większości, ale nie wszystkich elementów programu SemVer, w szczególności:

Nie obsługuje ciągów wersji wstępnej w numerach wersji. Jest to przydatne, gdy wydawca chce dostarczyć wersję zapoznawcza nowej wersji głównej po udostępnieniu wersji 1.0.0. Będzie to obsługiwane w przyszłej wersji poleceń cmdlet Galeria programu PowerShell i PowerShellGet.
Program PowerShell i Galeria programu PowerShell zezwalają na ciągi wersji z segmentami 1, 2 i 4. Wiele wczesnych modułów nie przestrzegało wytycznych, a wersje produktów firmy Microsoft zawierają informacje o kompilacji jako 4 blok liczb (na przykład 5.1.14393.1066). Z punktu widzenia przechowywania wersji te różnice są ignorowane.

Testowanie przy użyciu repozytorium lokalnego

Galeria programu PowerShell nie jest przeznaczony do testowania procesu publikowania. Najlepszym sposobem przetestowania kompleksowego procesu publikowania w Galeria programu PowerShell jest skonfigurowanie i użycie własnego lokalnego repozytorium. Można to zrobić na kilka sposobów, w tym:

Skonfiguruj lokalne wystąpienie Galeria programu PowerShell przy użyciu projektu galeria prywatna PS w usłudze GitHub. Ten projekt w wersji zapoznawczej pomoże ci skonfigurować wystąpienie Galeria programu PowerShell, które można kontrolować i używać do testów.
Skonfiguruj wewnętrzne repozytorium Nuget. Będzie to wymagało większej liczby pracy w celu skonfigurowania, ale będzie mieć zaletę weryfikacji kilku dodatkowych wymagań, szczególnie weryfikacji użycia klucza interfejsu API i tego, czy zależności są obecne w elemencie docelowym podczas publikowania.
Skonfiguruj udział plików jako repozytorium testowe. Jest to łatwe do skonfigurowania, ale ponieważ jest to udział plików, weryfikacje wymienione powyżej nie będą miały miejsca. Jedną z potencjalnych zalet w tym przypadku jest to, że udział plików nie sprawdza wymaganego klucza interfejsu API, więc można użyć tego samego klucza, którego należy użyć do opublikowania w Galeria programu PowerShell.

W przypadku dowolnego z tych rozwiązań użyj polecenia Register-PSRepository , aby zdefiniować nowe repozytorium, które jest używane w parametrze -Repository .Publish-Module

Jeden dodatkowy punkt dotyczący publikowania testowego: nie można usunąć żadnego pakietu publikowanego w Galeria programu PowerShell bez pomocy zespołu operacyjnego, który potwierdzi, że nic nie zależy od pakietu, który chcesz opublikować. Z tego powodu nie obsługujemy Galeria programu PowerShell jako celu testowania i skontaktujemy się z każdym wydawcą, który to robi.

Publikowanie za pomocą polecenia PowerShellGet

Zdecydowanie zaleca się, aby wydawcy używali Publish-Module poleceń cmdlet i Publish-Script podczas pracy z Galeria programu PowerShell. Program PowerShellGet został utworzony w celu uniknięcia zapamiętania ważnych szczegółów dotyczących instalowania i publikowania w Galeria programu PowerShell. Czasami wydawcy zdecydowali się pominąć moduł PowerShellGet i użyć klienta NuGet lub poleceń cmdlet PackageManagement zamiast Publish-Module. Istnieje wiele szczegółów, które można łatwo przegapić, co skutkuje różnymi żądaniami pomocy technicznej.

Jeśli istnieje powód, dla którego nie możesz użyć Publish-Module polecenia lub Publish-Script, daj nam znać. Zgłoś problem w repozytorium GitHub PowerShellGet i podaj szczegóły, które powodują wybranie narzędzia NuGet lub PackageManagement.

Zalecany przepływ pracy

Najbardziej udaną metodą, która została znaleziona w przypadku pakietów opublikowanych w Galeria programu PowerShell, jest następująca:

Wykonaj wstępne programowanie w lokacji projektu open source. Zespół programu PowerShell używa usługi GitHub.
Użyj opinii recenzentów i analizatora skryptów programu PowerShell , aby uzyskać kod do stabilnego stanu.
Dołącz dokumentację, aby inni wiedzieli, jak korzystać z pracy.
Przetestuj akcję publikowania przy użyciu repozytorium lokalnego.
Opublikuj stabilną lub alfa wydanie do Galeria programu PowerShell, upewniając się, że dołącz dokumentację i link do witryny projektu.
Zbierz opinię i iteruj kod w witrynie projektu, a następnie opublikuj stabilne aktualizacje w Galeria programu PowerShell.
Dodaj przykłady i testy Pester w projekcie i module.
Zdecyduj, czy chcesz podpisać pakiet za pomocą kodu.
Gdy projekt jest gotowy do użycia w środowisku produkcyjnym, opublikuj 1.0.0 wersję w Galeria programu PowerShell.
Kontynuuj zbieranie opinii i iterowanie kodu na podstawie danych wejściowych użytkownika.