Tworzenie i publikowanie elementu

  • Artykuł

Galeria programu PowerShell jest miejscem publikowania i udostępniania stabilnych modułów programu PowerShell, skryptów i zasobów Desired State Configuration (DSC) z szerszą społecznością użytkowników programu PowerShell.

W tym artykule omówiono mechanikę i ważne kroki przygotowania skryptu lub modułu oraz opublikowanie go w Galeria programu PowerShell. Zdecydowanie zachęcamy do przejrzenia wytycznych dotyczących publikowania, aby zrozumieć, jak zapewnić, że opublikowane elementy będą powszechnie akceptowane przez użytkowników Galeria programu PowerShell.

Minimalne wymagania dotyczące publikowania elementu w Galeria programu PowerShell to:

  • Posiadanie konta Galeria programu PowerShell i skojarzonego z nim klucza interfejsu API
  • Upewnij się, że wymagane metadane są w elemencie
  • Użyj narzędzi przed walidacją, aby upewnić się, że element jest gotowy do opublikowania
  • Publikowanie elementu w Galeria programu PowerShell przy użyciu poleceń Publish-Module i Publish-Script
  • Odpowiadanie na pytania lub obawy dotyczące twojego elementu

Galeria programu PowerShell akceptuje moduły programu PowerShell i skrypty programu PowerShell. W przypadku odwoływania się do skryptów oznaczamy skrypt programu PowerShell, który jest pojedynczym plikiem, a nie częścią większego modułu.

Zobacz Tworzenie konta Galeria programu PowerShell, aby dowiedzieć się, jak skonfigurować konto Galeria programu PowerShell.

Po utworzeniu konta możesz uzyskać klucz interfejsu API potrzebny do opublikowania elementu. Po zalogowaniu się przy użyciu konta nazwa użytkownika będzie wyświetlana w górnej części stron Galeria programu PowerShell zamiast rejestracji. Kliknięcie nazwy użytkownika spowoduje przejście do strony Moje konto, na której znajdziesz klucz interfejsu API.

Ważne

Klucz interfejsu API musi być traktowany jako bezpieczny jako identyfikator logowania i hasła. Za pomocą tego klucza lub innej osoby możesz zaktualizować dowolny element, którego jesteś właścicielem w Galeria programu PowerShell. Zalecamy regularne aktualizowanie klucza, co można zrobić przy użyciu klucza resetowania na stronie Moje konto.

Galeria programu PowerShell zawiera informacje dla użytkowników galerii pochodzących z pól metadanych, które znajdują się w manifeście skryptu lub modułu. Tworzenie lub modyfikowanie elementów publikacji w Galeria programu PowerShell ma niewielki zestaw wymagań dotyczących informacji podanych w manifeście elementu. Zdecydowanie zachęcamy do przejrzenia sekcji Metadane elementów w wytycznych dotyczących publikowania , aby dowiedzieć się, jak dostarczać użytkownikom najlepsze informacje o elementach.

Polecenia cmdlet New-ModuleManifest i New-ScriptFileInfo spowodują utworzenie szablonu manifestu z symbolami zastępczymi dla wszystkich elementów manifestu.

Oba manifesty mają dwie sekcje, które są ważne do publikowania, podstawowe dane klucza i obszar PSData privateData. Dane klucza podstawowego w manifeście modułu programu PowerShell to wszystko poza sekcją PrivateData. Zestaw kluczy podstawowych jest powiązany z wersją programu PowerShell, a niezdefiniowane nie są obsługiwane. Funkcja PrivateData obsługuje dodawanie nowych kluczy, więc elementy specyficzne dla Galeria programu PowerShell znajdują się w pliku PSData.

Elementy manifestu, które są najważniejsze do wypełnienia dla elementu publikowanego w Galeria programu PowerShell są następujące:

  • Nazwa skryptu lub modułu — są one pobierane z nazw .PS1 dla skryptu lub . PsD1 dla modułu.
  • Wersja — jest to wymagany klucz podstawowy, format powinien być zgodny z wytycznymi SemVer. Aby uzyskać szczegółowe informacje, zobacz Najlepsze rozwiązania.
  • Autor — jest to wymagany klucz podstawowy i zawiera nazwę, która ma być skojarzona z elementem. Zobacz Autorzy i właściciele poniżej.
  • Opis — jest to wymagany klucz podstawowy, używany do krótkiego wyjaśnienia, co ten element robi i jakie są wymagania dotyczące korzystania z niego
  • Identyfikator ProjectURI — jest to zdecydowanie zalecane pole identyfikatora URI w usłudze PSData, które udostępnia link do repozytorium GitHub lub podobnej lokalizacji, w której programujesz w elemencie
  • Tagi — jest to silne zalecenie, aby oznaczyć pakiet na podstawie zgodności z programem PSEditions i platformami. Aby uzyskać szczegółowe informacje, zobacz Wytyczne dotyczące publikowania.

Autorzy i właściciele elementów Galeria programu PowerShell są powiązanymi pojęciami, ale nie zawsze są zgodne. Właściciele elementów to użytkownicy z kontami Galeria programu PowerShell, które mają uprawnienia do konserwacji elementu. Może istnieć wiele właścicieli, którzy mogą zaktualizować dowolny element. Właściciel jest dostępny tylko z Galeria programu PowerShell i zostanie utracony, jeśli element zostanie skopiowany z jednego systemu do innego. Author to ciąg wbudowany w dane manifestu, więc zawsze jest częścią elementu. Zalecenia dotyczące elementów produktów firmy Microsoft to:

  • Posiadanie wielu właścicieli, z co najmniej jedną nazwą zespołu, który generuje element
  • Autor ma dobrze znaną nazwę zespołu (na przykład Zespół zestawu Azure SDK) lub Microsoft Corporation

Wstępnie zweryfikuj element

Istnieje kilka narzędzi, które należy uruchomić względem kodu przed opublikowaniem elementu w Galeria programu PowerShell:

  • Analizator skryptów programu PowerShell, który znajduje się w Galeria programu PowerShell
  • W przypadku modułów Test-ModuleManifest, który jest częścią programu PowerShell
  • W przypadku skryptów Test-ScriptFileInfo, które są dostarczane z programem PowerShell Get

Analizator skryptów programu PowerShell to narzędzie do analizy kodu statycznego, które przeskanuje kod, aby upewnić się, że spełnia on podstawowe wytyczne dotyczące kodowania programu PowerShell. To narzędzie będzie identyfikować typowe i krytyczne problemy w kodzie i powinno być uruchamiane regularnie podczas programowania, aby ułatwić przygotowanie elementu do opublikowania. Analizator skryptów programu PowerShell udostępnia listę problemów zidentyfikowanych jako błędy, ostrzeżenie i informacje. Przed opublikowaniem w Galeria programu PowerShell należy rozwiązać wszystkie błędy. Należy przejrzeć ostrzeżenia, a większość z tych kwestii powinna zostać rozwiązana. Analizator skryptów programu PowerShell jest uruchamiany za każdym razem, gdy element jest publikowany lub aktualizowany w Galeria programu PowerShell. Zespół operacyjny galerii skontaktuje się z właścicielami elementów, aby rozwiązać błędy, które zostały znalezione.

Jeśli informacje o manifeście w elemencie nie mogą być odczytywane przez infrastrukturę Galeria programu PowerShell, nie będzie można opublikować. Test-ModuleManifest przechwyci typowe problemy, które mogłyby spowodować, że moduł nie będzie używany podczas instalacji. Należy go uruchomić dla każdego modułu przed opublikowaniem go w Galeria programu PowerShell.

Podobnie Test-ScriptFileInfo weryfikuje metadane w skrypcie i muszą być uruchamiane na każdym skrypcie (opublikowanym oddzielnie od modułu) przed opublikowaniem ich w Galeria programu PowerShell.

Elementy publikowania

Aby opublikować elementy w Galeria programu PowerShell, należy użyć skryptu publikowania lub publikowania modułu. Oba te polecenia wymagają:

  • Ścieżka do elementu, który zostanie opublikowany. W przypadku modułu użyj folderu o nazwie dla modułu. Jeśli określisz folder zawierający wiele wersji tego samego modułu, musisz określić wartość RequiredVersion.
  • Klucz interfejsu API Nuget. Jest to klucz interfejsu API znaleziony na stronie Moje konto w Galeria programu PowerShell.

Większość innych opcji w wierszu polecenia powinna znajdować się w danych manifestu dla publikowanego elementu, dlatego nie należy ich określać w poleceniu .

Aby uniknąć błędów, zdecydowanie zaleca się wypróbowanie poleceń przy użyciu polecenia -WhatIf -Verbose przed opublikowaniem. Pozwoli to zaoszczędzić dużo czasu, ponieważ za każdym razem, gdy publikujesz w Galeria programu PowerShell, musisz zaktualizować numer wersji w sekcji manifestu elementu.

Przykłady to:

  • Publish-Module -Path ".\MyModule" -NugetAPIKey "GUID" -WhatIf -Verbose
  • Publish-Script -Path ".\MyScriptFile.PS1" -NugetAPIKey "GUID" -WhatIf -Verbose

Dokładnie przejrzyj dane wyjściowe i jeśli nie widzisz żadnych błędów ani ostrzeżeń, powtórz polecenie bez parametru -WhatIf.

Wszystkie elementy opublikowane w Galeria programu PowerShell zostaną zeskanowane pod kątem wirusów i zostaną przeanalizowane przy użyciu analizatora skryptów programu PowerShell. Wszelkie problemy, które pojawiają się w tym czasie, zostaną wysłane z powrotem do wydawcy w celu rozwiązania problemu.

Po opublikowaniu elementu w Galeria programu PowerShell musisz watch opinii na temat elementu.

  • Upewnij się, że monitorujesz adres e-mail skojarzony z kontem użytym do opublikowania. Użytkownicy, a zespół ds. operacji Galeria programu PowerShell przekaże opinię za pośrednictwem tego konta, w tym problemy ze skanowaniami psSA lub antywirusowymi. Jeśli konto e-mail jest nieprawidłowe lub jeśli poważne problemy są zgłaszane do konta i pozostawione nierozwiązane przez długi czas, elementy można uznać za porzucone i zostaną usunięte z Galeria programu PowerShell zgodnie z opisem w naszych Warunkach użytkowania.