Wskazówki i najlepsze rozwiązania dotyczące publikowania w programie PowerShellGallery

Artykuł
06/26/2024

W tym artykule opisano zalecane kroki używane przez zespoły firmy Microsoft w celu zapewnienia, że pakiety opublikowane w galerii programu PowerShell będą powszechnie stosowane i zapewniają użytkownikom wysoką wartość w oparciu o sposób obsługi danych manifestu przez galerię programu PowerShell i opinii od dużej liczby użytkowników galerii programu PowerShell. Pakiety opublikowane zgodnie z tymi wytycznymi będą częściej instalowane, zaufane i przyciągają więcej użytkowników.

Poniżej przedstawiono wskazówki dotyczące tego, co sprawia, że dobry pakiet galerii programu PowerShell, jakie opcjonalne ustawienia manifestu są najważniejsze, ulepszając kod z opiniami od początkowych recenzentów i analizatora skryptów programu PowerShell, przechowywanie wersji modułu, dokumentacji, testów i przykładów sposobu używania udostępnionej zawartości. Większość tej dokumentacji jest zgodna z wytycznymi dotyczącymi publikowania wysokiej jakości modułów zasobów DSC.

Aby zapoznać się z mechaniką publikowania pakietu w galerii 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 są ważne dla użytkowników elementów galerii programu PowerShell i są wymienione w nominalnej kolejności 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łącz dokumentację i przykłady
Odpowiadanie na opinie
Udostępnianie modułów, a nie skryptów
Udostępnianie linków do witryny projektu
Tagowanie pakietu przy użyciu zgodnych programó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 PowerShell Gallery tags (Typowe tagi galerii programu PowerShell)
Testowanie publikowania przy użyciu repozytorium lokalnego
Publikowanie przy użyciu polecenia 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. psScriptAnalyzer zidentyfikuje najczęstsze problemy występujące w kodzie programu PowerShell i często zaleca się rozwiązanie 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 galerii programu PowerShell zostaną zeskanowane przy użyciu psScriptAnalyzer, a wszelkie błędy zostaną zgłoszone z powrotem do właściciela i należy je rozwiązać.

Najlepszym rozwiązaniem jest uruchomienie Invoke-ScriptAnalyzer z -Recurse i ostrzeżeniem -Severity.

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 galerii programu PowerShell są zdecydowanie zachęcani do uruchamiania 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 widzą, że wystąpił błąd zgłoszony przez PSScriptAnalyzer. Jeśli istnieje przekonujący powód, dla którego pakiet zachowuje kod oflagowany jako błąd, dodaj te informacje do dokumentacji, aby uniknąć wielokrotnego odpowiadania na to samo pytanie.

Dołącz dokumentację i przykłady

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 opublikowanych w galerii programu PowerShell. Użytkownicy zazwyczaj pomijają pakiety bez dokumentacji, ponieważ alternatywą jest przeczytanie 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 Jak napisać pomoc dotyczącą poleceń cmdlet.
Tworzenie pomocy polecenia cmdlet, która jest najlepszym rozwiązaniem dla dowolnego skryptu, funkcji lub polecenia cmdlet programu PowerShell. Aby uzyskać informacje o sposobie tworzenia pomocy dotyczącej poleceń cmdlet, zacznij od Jak napisać pomoc dotyczącą poleceń cmdlet. Aby dodać pomoc w skrycie, zobacz 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 silnie używanym formatem. Najlepszym rozwiązaniem jest użycie języka Markdown w usłudze 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 używać czegoś. Najlepsze typy przykładów pokazują podstawowe użycie oraz symulowany realistyczny przypadek użycia, a kod jest dobrze skomentowany. Przykłady modułów opublikowanych w galerii programu PowerShell powinny znajdować się w folderze Examples w katalogu 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ć wymaganego pola modułu w manifeście modułu. Spowoduje to załadowanie wszystkich wymienionych modułów 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 ModuleVersionzostanie 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 galerii programu PowerShell jest dostępna jedna metoda 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 galerii programu PowerShell i reagowanie na zgłoszone 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 być musiał odpowiedzieć na to samo pytanie wiele razy.

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

Jeśli z jednego z tych kanałów komunikacyjnych zaobserwowano niewłaściwe zachowanie, użyj funkcji Zgłaszanie nadużyć w galerii 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 galerii 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 programu 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 zawiera listę towarzyszących modułów przy użyciu 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 galerii programu PowerShell.

Podaj link do witryny projektu

Witryna projektu umożliwia wydawcy bezpośrednią interakcję z użytkownikami pakietów galerii programu PowerShell. Użytkownicy wolą pakiety, które to udostępniają, ponieważ pozwala im łatwiej uzyskać informacje o pakiecie. Wiele pakietów w galerii programu PowerShell jest opracowywanych w usłudze GitHub. Inne są udostępniane 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 programó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 programem Windows PowerShell
PSEdition_Core: pakiety zgodne z programem PowerShell 6 lub 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 naszych osłon zgodności z galerią programu PowerShell przykład osłony zgodności .

Uwzględnij testy

Dołączanie testów z kodem typu open source jest ważne dla użytkowników, ponieważ zapewnia im pewność co do weryfikowania 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 korzystania z platformy testowej Pester, która została zaprojektowana specjalnie dla programu PowerShell. Pester jest dostępny w GitHub, galerii programu PowerShell i dostarczanych w systemach 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 testów jednostkowych 70%.

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

Wszystkie pakiety opublikowane w galerii programu PowerShell muszą określać postanowienia licencyjne lub być powiązane przez licencję zawartą w Warunki użytkowania w ramach Załącznik A. Najlepszym podejściem do określenia innej licencji jest podanie linku do licencji przy użyciu LicenseURI w 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 pewności dla osób, które opublikowały pakiet, oraz że kopia uzyskanego przez nich 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:

Pliki skryptów podpisywania
Podpisywanie wykazu modułu

Podpisywanie plików programu PowerShell to dobrze ugruntowane podejście do zapewnienia, że wykonywany kod został wygenerowany przez niezawodne źródło i nie został zmodyfikowany. Szczegółowe informacje o sposobie podpisywania plików skryptów programu PowerShell opisano w artykule About Signing (Informacje o podpisywaniu). W przeglądzie można dodać podpis do dowolnego pliku .PS1, który program PowerShell weryfikuje po załadowaniu skryptu. Program PowerShell można ograniczyć przy użyciu zasad wykonywania poleceń cmdlet w celu zapewnienia użycia 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 dotyczącym poleceń cmdlet katalogu . W przeglądzie podpisywanie wykazu odbywa się przez utworzenie pliku wykazu, który zawiera 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 on 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, Install-Module potwierdzi, że urząd podpisywania dla nowej wersji jest zgodny z tym, co zostało wcześniej zainstalowane. Install-Module i Update-Module będą używać podpisu w pliku .PSD1, jeśli pakiet nie jest podpisany. Podpisywanie katalogu 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 opisującą 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 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ę tylko od 0, jeśli 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 drugiej liczbie (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, dlatego 1.01.0 będą traktowane jako większe 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 podaniu wersji 1.0.0. Będzie to obsługiwane w przyszłej wersji galerii programu PowerShell i poleceń cmdlet programu PowerShellGet.
Program PowerShell i galeria programu PowerShell umożliwiają używanie ciągów 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 wersji te różnice są ignorowane.

Testowanie przy użyciu repozytorium lokalnego

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

Skonfiguruj lokalne wystąpienie galerii programu PowerShell przy użyciu projektu galerii prywatnej PS w usłudze GitHub. Ten projekt w wersji zapoznawczej pomoże Ci skonfigurować wystąpienie galerii 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 ilości pracy w celu skonfigurowania, ale będzie mieć zaletę weryfikacji kilku innych wymagań, w szczególności weryfikacji użycia klucza interfejsu API i tego, czy zależności są obecne w obiekcie docelowym podczas publikowania.
Skonfiguruj udział plików jako repozytorium testowe . Jest to łatwe do skonfigurowania, ale ponieważ jest to udział plików, walidacje opisane 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 galerii programu PowerShell.

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

Jeden dodatkowy punkt dotyczący publikowania testowego: nie można usunąć żadnego pakietu publikowanego w galerii 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 galerii programu PowerShell jako elementu docelowego testowania i skontaktujemy się z dowolnym wydawcą, który to robi.

Publikowanie przy użyciu polecenia PowerShellGet

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

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

Zalecany przepływ pracy

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

Wykonaj wstępne programowanie w witrynie projektu open source. Zespół programu PowerShell używa usługi GitHub.
Użyj opinii recenzentów i Analizator skryptów programu PowerShell, aby uzyskać kod do stabilnego stanu.
Dołącz dokumentację, aby inni wiedzieli, jak używać swojej pracy.
Przetestuj akcję publikowania przy użyciu repozytorium lokalnego.
Opublikuj stabilną lub alfa wydanie w galerii programu PowerShell, upewniając się, że dołącz dokumentację i link do witryny projektu.
Zbierz opinie i iteruj kod w witrynie projektu, a następnie opublikuj stabilne aktualizacje w galerii 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 wersję 1.0.0 w galerii programu PowerShell.
Kontynuuj zbieranie opinii i iterowanie kodu na podstawie danych wejściowych użytkownika.

Udostępnij za pośrednictwem