Wskazówki dotyczące publikowania PowerShellGallery i najlepsze rozwiązaniaPowerShellGallery Publishing Guidelines and Best Practices

W tym artykule opisano zalecane kroki używane przez zespoły Microsoft Teams w celu zapewnienia, że pakiety opublikowane w Galeria programu PowerShell będą powszechnie stosowane i zapewniają wysoką wartość użytkownikom, w zależności od tego, jak Galeria programu PowerShell obsługuje dane manifestu i opinie z dużej liczby Galeria programu PowerShell użytkowników.This article describes recommended steps used by Microsoft teams to ensure the packages published to the PowerShell Gallery will be widely adopted and provide high value to users, based on how the PowerShell Gallery handles manifest data and on feedback from large numbers of PowerShell Gallery users. Pakiety opublikowane w ramach tych wytycznych będą prawdopodobnie zainstalowane, zaufane i przyciągnąć większej liczby użytkowników.Packages that are published following these guidelines will be more likely to be installed, trusted, and attract more users.

Poniżej przedstawiono wskazówki dotyczące tego, co to jest dobry pakiet Galeria programu PowerShell, jakie opcjonalne ustawienia manifestu są najważniejsze, ulepszanie kodu za pomocą informacji zwrotnych od recenzentów początkowych i Analizator skryptów programu PowerShell, przechowywanie wersji modułu, dokumentacji, testów i przykładów dotyczących korzystania z udostępnionych elementów.Included below are guidelines for what makes a good PowerShell Gallery package, what optional Manifest settings are most important, improving your code with feedback from initial reviewers and Powershell Script Analyzer, versioning your module, documentation, tests and examples for how to use what you have shared. W większości tej dokumentacji przedstawiono wskazówki dotyczące publikowania modułów zasobów o wysokiej jakości DSC.Much of this documentation follows the guidelines for publishing High Quality DSC Resource Modules.

Mechanics publikowania pakietu do Galeria programu PowerShell można znaleźć w temacie Tworzenie i publikowanie pakietu.For the mechanics of publishing a package to the PowerShell Gallery, see Creating and Publishing a Package.

Opinie dotyczące tych wytycznych zostały zawitane.Feedback on these guidelines is welcomed. Jeśli masz opinię, Otwórz problemy w naszym repozytorium dokumentacji usługi GitHub.If you do have feedback, please open issues in our GitHub documentation repository.

Najlepsze rozwiązania dotyczące publikowania pakietówBest practices for publishing packages

Poniżej przedstawiono najlepsze rozwiązania dotyczące tego, co jest ważne dla użytkowników Galeria programu PowerShell elementów i są one wymienione w kolejności nominalnego priorytetu.The following best practices are what the users of PowerShell Gallery items say is important, and are listed in nominal priority order. Pakiety, które są zgodne z tymi wytycznymi, są znacznie łatwiejsze do pobrania i przyjęcia przez inne osoby.Packages that follow these guidelines are far more likely to be downloaded and adopted by others.

  • Użyj PSScriptAnalyzerUse PSScriptAnalyzer
  • Dołącz dokumentację i przykładyInclude documentation and examples
  • Reagowanie na OpinieBe responsive to feedback
  • Dostarczanie modułów zamiast skryptówProvide modules rather than scripts
  • Udostępnianie linków do witryny projektuProvide links to a project site
  • Oznacz swój pakiet za pomocą zgodnych PSEdition i platformTag your package with the compatible PSEdition(s) and platforms
  • Uwzględnij testy z modułamiInclude tests with your modules
  • Dołącz i/lub Połącz z postanowieniami licencyjnymiInclude and/or link to license terms
  • Podpisz swój kodSign your code
  • Postępuj zgodnie z SemVer wytycznych dotyczących przechowywania wersjiFollow SemVer guidelines for versioning
  • Używaj typowych tagów, jak opisano w typowych tagach Galeria programu PowerShellUse common tags, as documented in Common PowerShell Gallery tags
  • Testowanie publikacji przy użyciu repozytorium lokalnegoTest publishing using a local repository
  • Użyj PowerShellGet do opublikowaniaUse PowerShellGet to publish

Każda z nich została omówiona krótko w poniższych sekcjach.Each of these is covered briefly in the sections below.

Użyj PSScriptAnalyzerUse PSScriptAnalyzer

PSScriptAnalyzer to bezpłatne narzędzie do analizy kodu statycznego, które działa w kodzie programu PowerShell.PSScriptAnalyzer is a free static code analysis tool that works on PowerShell code. PSScriptAnalyzer będzie identyfikować najczęstsze problemy występujące w kodzie programu PowerShell i często zalecenia dotyczące sposobu rozwiązania problemu.PSScriptAnalyzer will identify the most common issues seen in PowerShell code, and often a recommendation for how to fix the issue. Narzędzie jest łatwe w użyciu i klasyfikuje problemy jako błędy (poważne, muszą być rozwiązane), ostrzeżenie (należy sprawdzić i należy je rozwiązać) oraz informacje (co jest przydatne w przypadku najlepszych rozwiązań).The tool is easy to use, and categorizes the issues as Errors (severe, must be addressed), Warning (need to be reviewed and should be addressed), and Information (worth checking out for best practices). Wszystkie pakiety opublikowane w Galeria programu PowerShell będą skanowane przy użyciu PSScriptAnalyzer , a wszelkie błędy zostaną zgłoszone do właściciela i należy je rozwiązać.All packages published to the PowerShell Gallery will be scanned using PSScriptAnalyzer , and any errors will be reported back to the owner and must be addressed.

Najlepszym rozwiązaniem jest uruchomienie Invoke-ScriptAnalyzer z -Recurse i -Severity ostrzeżenie.The best practice is to run Invoke-ScriptAnalyzer with -Recurse and -Severity Warning.

Przejrzyj wyniki i upewnij się, że:Review the results, and ensure that:

  • Wszystkie błędy są poprawiane lub rozwiązane w dokumentacji.All Errors are corrected or addressed in your documentation.
  • Wszystkie ostrzeżenia są analizowane i są rozwiązywane, gdy ma to zastosowanie.All Warnings are reviewed, and addressed where applicable.

Użytkownicy, którzy pobierają pakiety z Galeria programu PowerShell są zdecydowanie zachęcani do uruchamiania PSScriptAnalyzer i szacowania wszystkich błędów i ostrzeżeń.Users who download packages from the PowerShell Gallery are strongly encouraged to run PSScriptAnalyzer and evaluate all Errors and Warnings. Użytkownicy bardzo mogą kontaktować się z właścicielami pakietów, Jeśli zobaczysz, że wystąpił błąd zgłoszony przez PSScriptAnalyzer .Users are very likely to contact package owners if they see that there's an error reported by PSScriptAnalyzer . Jeśli istnieje atrakcyjny powód, aby pakiet mógł zachować kod oflagowany jako błąd, Dodaj te informacje do dokumentacji, aby uniknąć konieczności odpowiedzi na to samo pytanie wiele razy.If there's a compelling reason for your package to keep code that is flagged as an error, add that information to your documentation to avoid having to answer the same question many times.

Dołącz dokumentację i przykładyInclude documentation and examples

Dokumentacja i przykłady są najlepszym sposobem zapewnienia, że użytkownicy będą mogli korzystać z dowolnego kodu udostępnionego.Documentation and examples are the best way to ensure users can take advantage of any shared code.

Dokumentacja jest najbardziej przydatna do uwzględnienia w pakietach opublikowanych w Galeria programu PowerShell.Documentation is the most helpful thing to include in packages published to the PowerShell Gallery. Użytkownicy zwykle omijają pakiety bez dokumentacji, ponieważ alternatywą jest odczytanie kodu, aby zrozumieć, co to jest pakiet i jak go używać.Users will generally bypass packages without documentation, as the alternative is to read the code to understand what the package is and how to use it. Dostępnych jest kilka artykułów o udostępnianiu dokumentacji z pakietami programu PowerShell, w tym:There are several articles available about how to provide documentation with PowerShell packages, including:

  • Wskazówki dotyczące udostępniania pomocy znajdują się w temacie jak pisać pomoc poleceń cmdlet.Guidelines for providing help are in How to Write Cmdlet Help.
  • Tworzenie pomocy dotyczącej poleceń cmdlet, która jest najlepszym rozwiązaniem dla dowolnego skryptu, funkcji lub polecenia cmdlet programu PowerShell.Creating cmdlet help, which is the best approach for any PowerShell script, function, or cmdlet. Aby uzyskać informacje o sposobach tworzenia pomocy dotyczącej poleceń cmdlet, Zacznij od pisania pomocy poleceń cmdlet.For information about how to create cmdlet help, start with How to Write Cmdlet Help. Aby dodać pomoc w ramach skryptu, zobacz Informacje o pomocy na temat komentarzy.To add help within a script, see About Comment Based Help.
  • Wiele modułów zawiera również dokumentację w formacie tekstowym, na przykład pliki o promocji.Many modules also include documentation in text format, such as MarkDown files. Może to być szczególnie przydatne, gdy w serwisie GitHub znajduje się witryna projektu, w której jest to wysoce używany format.This can be particularly helpful when there's a project site in GitHub, where Markdown is a heavily used format. Najlepszym rozwiązaniem jest użycie promocji z obsługą usługi GitHub.The best practice is to use GitHub-flavored Markdown.

Przykłady przedstawiają sposób, w jaki pakiet jest przeznaczony do użycia.Examples show users how the package is intended to be used. Wielu deweloperów zobaczy, że zapoznają się z przykładami przed dokumentacją, aby zrozumieć, jak to zrobić.Many developers will say that they look at examples before documentation to understand how to use something. Najlepsze typy przykładów pokazują podstawowe użycie oraz symulowany realistyczny przypadek użycia i kod jest dobrze komentarz.The best types of examples show basic use, plus a simulated realistic use case, and the code is well-commented. Przykłady dla modułów opublikowanych w Galeria programu PowerShell powinny znajdować się w folderze przykładów w katalogu głównym modułu.Examples for modules published to the PowerShell Gallery should be in an Examples folder under the module root.

Dobry wzorzec przykładów można znaleźć w module PSDscResource w Examples\RegistryResource folderze.A good pattern for examples can be found in the PSDscResource module under the Examples\RegistryResource folder. Istnieją cztery przykładowe przypadki użycia z krótkim opisem w górnej części każdego pliku, który dokumentuje co jest prezentowane.There are four sample use cases with a brief description at the top of each file that documents what is being demonstrated.

Zarządzanie zależnościamiManage Dependencies

Ważne jest, aby określić moduły, od których moduł jest zależny w manifeście modułu.It's important to specify modules that your module is dependent on in the Module Manifest. Dzięki temu użytkownik końcowy nie musi martwić się o zainstalowanie odpowiednich wersji modułów, na których należy wziąć zależność.This allows the end user to not have to worry about installing the proper versions of modules that yours take a dependency on. Aby określić moduły zależne, należy użyć pola wymagane modułu w manifeście modułu.To specify dependent modules, you should use the required module field in the module manifest. Spowoduje to załadowanie dowolnego z wymienionych modułów do środowiska globalnego przed zaimportowaniem modułu, chyba że zostały już załadowane.This will load any listed modules into the global environment prior to importing your module unless they've already been loaded. Na przykład niektóre moduły mogą już być załadowane przez inny moduł.For example, some modules may already be loaded by a different module. Istnieje również możliwość określenia konkretnej wersji do załadowania przy użyciu pola RequiredVersion , a nie pola ModuleVersion .It's also possible to specify a specific version to load using the RequiredVersion field rather than the ModuleVersion field. W przypadku korzystania z programu ModuleVersion zostanie załadowana Najnowsza wersja dostępna z co najmniej określoną wersją.When using ModuleVersion , it will load the newest version available with a minimum of the version specified. Gdy nie korzystasz z pola RequiredVersion , aby określić konkretną wersję, ważne jest, aby monitorować aktualizacje wersji do wymaganego modułu.When not using the RequiredVersion field, to specify a specific version it's important to monitor version updates to the required module. Szczególnie ważne jest, aby mieć świadomość wszelkich istotnych zmian, które mogą mieć wpływ na środowisko użytkownika w Twoim module.It's especially important to be aware of any breaking changes that could affect the user experience with your 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"})

Odpowiedź na opinięRespond to feedback

Właściciele pakietu, którzy prawidłowo reagują na opinie, mają wysoką wartość przez społeczność.Package owners who respond properly to feedback are highly valued by the community. Użytkownicy, którzy przedstawiają konstruktywną opinię, są ważną odpowiedzią, ponieważ są one wystarczająco interesujące w pakiecie, aby pomóc w ulepszaniu tego rozwiązania.Users who provide constructive feedback are important to respond to, as they're interested enough in the package to try to help improve it.

W Galeria programu PowerShell jest dostępna jedna metoda przesyłania opinii:There is one feedback method available in the PowerShell Gallery:

  • Skontaktuj się z właścicielem: umożliwia użytkownikowi wysłanie wiadomości e-mail do właściciela pakietu.Contact Owner: This allows a user to send an email to the package owner. Jako właściciel pakietu jest ważne, aby monitorować adres e-mail używany z pakietami Galeria programu PowerShell i odpowiadać na zgłoszone problemy.As a package owner, is important to monitor the email address used with the PowerShell Gallery packages, and respond to issues that are raised. Wadą tej metody jest to, że tylko użytkownik i właściciel będą widzieli komunikację, więc właściciel może mieć wiele razy odpowiedzieć na to samo pytanie.The one disadvantage to this method is that only the user and owner will ever see the communication, so the owner may have to answer the same question many times.

Właściciele, którzy reagują na opinie, zwyczajowo doceniają społeczność.Owners who respond to feedback constructively are appreciated by the community. Aby uzyskać więcej informacji, Skorzystaj z szansy sprzedaży w raporcie.Use the opportunity in the report to request more information. W razie konieczności należy zastosować obejście lub określić, czy aktualizacja rozwiązuje problem.If needed, provide a workaround, or identify if an update fixes a problem.

W przypadku niewłaściwego zachowania zaobserwowanego z dowolnego z tych kanałów komunikacji Użyj funkcji Zgłoś nadużycie w Galeria programu PowerShell, aby skontaktować się z administratorami galerii.If there's inappropriate behavior observed from either of these communication channels, use the Report Abuse feature of the PowerShell Gallery to contact the Gallery Administrators.

Moduły a skryptyModules Versus Scripts

Udostępnianie skryptu innym użytkownikom jest doskonałe i zawiera inne przykłady sposobu rozwiązywania problemów, które mogą mieć.Sharing a script with other users is great, and provides others with examples of how to solve problems they may have. Problem polega na tym, że skrypty w Galeria programu PowerShell są pojedynczymi plikami bez oddzielnej dokumentacji, przykładów i testów.The issue is that scripts in the PowerShell Gallery are single files without separate documentation, examples, and tests.

Moduły programu PowerShell mają strukturę folderów, która umożliwia dołączenie wielu folderów i plików do pakietu.PowerShell Modules have a folder structure that allows multiple folders and files to be included with the package. Struktura modułów umożliwia uwzględnienie innych pakietów, które są wystawiane jako najlepsze rozwiązania: pomoc poleceń cmdlet, dokumentacja, przykłady i testy.The module structure enables including the other packages we list as best practices: cmdlet help, documentation, examples, and tests. Największą wadą jest to, że skrypt wewnątrz modułu musi być uwidoczniony i używany jako funkcja.The biggest disadvantage is that a script inside a module must be exposed and used as a function. Aby uzyskać informacje na temat sposobu tworzenia modułu, zobacz pisanie modułu programu Windows PowerShell.For information on how to create a module, see Writing a Windows PowerShell Module.

Istnieją sytuacje, w których skrypt zapewnia lepszy interfejs użytkownika, w szczególności konfiguracje DSC.There are situations where a script provides a better experience for the user, particularly with DSC configurations. Najlepszym rozwiązaniem w przypadku konfiguracji DSC jest opublikowanie konfiguracji jako skryptu z towarzyszącym modułem zawierającym dokumenty, przykłady i testy.The best practice for DSC configurations is to publish the configuration as a script with an accompanying module that contains the docs, examples, and tests. Skrypt zawiera listę towarzyszącego modułu przy użyciu RequiredModules = @(Name of the Module) .The script lists the accompanying module using RequiredModules = @(Name of the Module). Takie podejście może być używane z dowolnym skryptem.This approach can be used with any script.

Skrypty autonomiczne, które są zgodne z innymi najlepszymi rozwiązaniami, zapewniają wartość rzeczywistą innym użytkownikom.Standalone scripts that follow the other best practices provide real value to other users. Udostępnianie dokumentacji opartej na komentarzach i link do witryny projektu jest zdecydowanie zalecane podczas publikowania skryptu do Galeria programu PowerShell.Providing comment-based documentation and a link to a Project Site are highly recommended when publishing a script to the PowerShell Gallery.

Witryna projektu to miejsce, w którym Wydawca może współdziałać bezpośrednio z użytkownikami ich pakietów Galeria programu PowerShell.A Project Site is where a publisher can interact directly with the users of their PowerShell Gallery packages. Użytkownicy preferują pakiety, które je zapewniają, ponieważ umożliwiają im łatwiejsze uzyskiwanie informacji o pakiecie.Users prefer packages that provide this, as it allows them to get information about the package more easily. Wiele pakietów w Galeria programu PowerShell są opracowywane w serwisie GitHub, a inne są udostępniane przez organizacje z dedykowaną obecnością w sieci Web.Many packages in the PowerShell Gallery are developed in GitHub, others are provided by organizations with a dedicated web presence. Każdy z nich może być traktowany jako witryna projektu.Each of these can be considered a project site.

Dodawanie linku odbywa się przez włączenie ProjectURI w sekcji PSData manifestu w następujący sposób:Adding a link is done by including ProjectURI in the PSData section of the manifest as follows:

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

Gdy ProjectURI jest podany, Galeria programu PowerShell będzie zawierać link do witryny projektu po lewej stronie pakietu.When a ProjectURI is provided, the PowerShell Gallery will include a link to the Project Site on the left side of the package page.

Oznacz swój pakiet za pomocą zgodnych PSEdition i platformTag your package with the compatible PSEdition(s) and platforms

Użyj następujących tagów, aby zademonstrować użytkownikom, które pakiety będą dobrze współpracować ze swoimi środowiskami:Use the following tags to demonstrate to users which packages will work well with their environment:

  • PSEdition_Desktop: pakiety zgodne z programem Windows PowerShellPSEdition_Desktop: Packages that are compatible with Windows PowerShell
  • PSEdition_Core: pakiety zgodne z programem PowerShell CorePSEdition_Core: Packages that are compatible with PowerShell Core
  • Windows: pakiety zgodne z systemem operacyjnym WindowsWindows: Packages that are compatible with the Windows Operating System
  • Linux: pakiety zgodne z systemami operacyjnymi LinuxLinux: Packages that are compatible with Linux Operating Systems
  • MacOS: pakiety zgodne z systemem operacyjnym MacMacOS: Packages that are compatible with the Mac Operating System

Tagowanie pakietu przy użyciu zgodnych platform, które zostaną dołączone do filtrów wyszukiwania galerii w lewym okienku wyników wyszukiwania.By tagging your package with the compatible platform(s) it will be included in the Gallery search filters on the left pane of the search results. Jeśli pakiet jest hostowany w serwisie GitHub, po oznaczeniu pakietu można także skorzystać z naszego PowerShell Gallery compatibility shields  przykładu z osłoną zgodności Galeria programu PowerShell .If you host your package on GitHub, when you tag your package, you can also take advantage of our PowerShell Gallery compatibility shields compatibility shield example.

Uwzględnij testyInclude tests

Uwzględnienie testów z kodem Open Source jest ważne dla użytkowników, ponieważ daje im gwarancje dotyczące tego, co jest sprawdzane i zawiera informacje na temat sposobu działania kodu.Including tests with open-source code is important to users, as it gives them assurance about what you validate, and provides information on how your code works. Umożliwia ona również użytkownikom zagwarantowanie, że nie przerywają pierwotnych funkcji, jeśli zmodyfikujesz swój kod w celu dopasowania go do środowiska.It also allows users to ensure they don't break your original functionality if they modify your code to fit their environment.

Zdecydowanie zaleca się, aby testy były napisane w celu skorzystania z platformy testów szkodników, która została zaprojektowana specjalnie dla programu PowerShell.It's strongly recommended that tests be written to take advantage of the Pester test framework, which has been designed specifically for PowerShell. Program szkodnik jest dostępny w witrynie GitHub, Galeria programu PowerShelli dostarcza w systemie Windows 10, Windows Server 2016, wmf 5,0 i WMF 5,1.Pester is available in GitHub, the PowerShell Gallery, and ships in Windows 10, Windows Server 2016, WMF 5.0 and WMF 5.1.

Witryna projektu szkodników w usłudze GitHub zawiera dobrą dokumentację dotyczącą pisania testów szkodników, od rozpoczęcia do najlepszych rozwiązań.The Pester project site in GitHub includes good documentation on writing Pester tests, from getting started to best practices.

Elementy docelowe dla pokrycia testu są wywoływane w dokumentacji modułu zasobów o wysokiej jakościz zalecanym pokryciem kodu w przypadku 70%.The targets for test coverage are called out in the High Quality Resource Module documentation, with 70% unit test code coverage recommended.

Wszystkie pakiety opublikowane w Galeria programu PowerShell muszą określać postanowienia licencyjne lub być powiązane z licencją zawartą w warunkach użytkowania w obszarze wystawiony A . Najlepszym podejściem do określenia innej licencji jest udostępnienie linku do licencji przy użyciu LicenseURI w PSData .All packages published to the PowerShell Gallery must specify the license terms, or be bound by the license included in the Terms of Use under Exhibit A . The best approach to specifying a different license is to provide a link to the license using the LicenseURI in PSData . Aby uzyskać więcej informacji, zobacz interfejs użytkownika manifestu i kolekcji pakietów.For more information, see Packages manifest and Gallery UI.

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'

Podpisz swój kodSign your code

Podpisywanie kodu zapewnia użytkownikom najwyższy poziom pewności, kto opublikował pakiet, i że kopia pobieranego kodu jest dokładnie wydaną przez wydawcę.Code signing provides users with the highest level of assurance for who published the package, and that the copy of the code they acquire is exactly what the publisher released. Aby dowiedzieć się więcej na temat ogólnego podpisywania kodu, zobacz wprowadzenie do podpisywania kodu.To learn more about code signing generally, see Introduction to Code Signing. Program PowerShell obsługuje sprawdzanie poprawności podpisywania kodu przez dwa podstawowe podejścia:PowerShell supports validation of code signing through two primary approaches:

  • Podpisywanie plików skryptuSigning script files
  • Podpisywanie modułu przez katalogCatalog signing a module

Podpisywanie plików programu PowerShell to dobrze ustalone podejście do zapewnienia, że wykonywany kod został wyprodukowany przez niezawodne źródło i nie został zmodyfikowany.Signing PowerShell files is a well-established approach to ensuring that the code being executed was produced by a reliable source, and hasn't been modified. Szczegóły dotyczące podpisywania plików skryptów programu PowerShell znajdują się w artykule dotyczącym podpisywania .Details on how to sign PowerShell script files is covered in the About Signing article. W obszarze przegląd można dodać podpis do każdego .PS1 pliku, który program PowerShell sprawdza po załadowaniu skryptu.In overview, a signature can be added to any .PS1 file that PowerShell validates when the script is loaded. Program PowerShell można ograniczyć za pomocą poleceń cmdlet zasad wykonywania , aby zapewnić możliwość korzystania ze podpisanych skryptów.PowerShell can be constrained using the Execution Policy cmdlets to ensure use of signed scripts.

Moduły podpisywania katalogu to funkcja dodana do programu PowerShell w wersji 5,1.Catalog signing modules is a feature added to PowerShell in version 5.1. Sposób podpisywania modułu znajduje się w artykule polecenia cmdlet katalogu .How to sign a module is covered in the Catalog Cmdlets article. W obszarze przegląd podpisywanie wykazu jest wykonywane przez utworzenie pliku wykazu, który zawiera wartość skrótu dla każdego pliku w module, a następnie podpisuje ten plik.In overview, catalog signing is done by creating a catalog file, which contains a hash value for every file in the module, and then signing that file.

PowerShellGet Publish-Module , Install-Module , i Update-Module polecenia cmdlet sprawdzają podpis, aby upewnić się, że jest on prawidłowy, a następnie potwierdź, że wartość skrótu dla każdego pakietu jest zgodna z tym, co znajduje się w katalogu.The PowerShellGet Publish-Module, Install-Module, and Update-Module cmdlets will check the signature to ensure it's valid, then confirm that the hash value for each package matches what is in the catalog. Save-Module nie weryfikuje podpisu.Save-Module doesn't validate a signature. Jeśli w systemie zainstalowano poprzednią wersję modułu, Install-Module program potwierdzi, że urząd podpisywania dla nowej wersji pasuje do tego, co zostało wcześniej zainstalowane.If a previous version of the module is installed on the system, Install-Module will confirm that the signing authority for the new version matches what was previously installed. Install-Module i Update-Module użyje podpisu w pliku, .PSD1 Jeśli pakiet nie jest podpisany w wykazie.Install-Module and Update-Module will use the signature on a .PSD1 file if the package isn't catalog signed. Podpisywanie wykazu współpracuje z programem, ale nie zastępuje plików skryptów podpisywania.Catalog signing works with, but doesn't replace signing script files. Program PowerShell nie weryfikuje podpisów wykazu w czasie ładowania modułu.PowerShell doesn't validate catalog signatures at module load time.

Postępuj zgodnie z SemVer wytycznych dotyczących przechowywania wersjiFollow SemVer guidelines for versioning

SemVer to publiczna Konwencja opisująca sposób tworzenia struktury i zmiany wersji, aby umożliwić łatwą interpretację zmian.SemVer is a public convention that describes how to structure and change a version to allow easy interpretation of changes. Wersja pakietu musi być uwzględniona w danych manifestu.The version for your package must be included in the manifest data.

  • Wersja powinna mieć strukturę jako trzy bloki liczbowe oddzielone kropkami, jak w 0.1.1 lub 4.11.192 .The version should be structured as three numeric blocks separated by periods, as in 0.1.1 or 4.11.192.
  • Wersje zaczynające się od 0 wskazują, że pakiet nie jest jeszcze gotowy do produkcji, a pierwszy numer powinien rozpoczynać się tylko wtedy 0 , gdy jest to jedyna użyta liczba.Versions starting with 0 indicate that the package isn't yet production ready, and the first number should only begin with 0 if that's the only number used.
  • Zmiany w pierwszej liczbie ( 1.9.9999 do 2.0.0 ) wskazują na główne i istotne zmiany między wersjami.Changes in the first number (1.9.9999 to 2.0.0) indicate major and breaking changes between the versions.
  • Zmiany w drugiej liczbie ( 1.1 do 1.2 ) wskazują zmiany na poziomie funkcji, takie jak dodawanie nowych poleceń cmdlet do modułu.Changes to the second number (1.1 to 1.2) indicate feature-level changes, such as adding new cmdlets to a module.
  • Zmiany trzeciego numeru wskazują na niekrytyczne zmiany, takie jak nowe parametry, zaktualizowane przykłady lub nowe testy.Changes to the third number indicate non-breaking changes, such as new parameters, updated samples, or new tests.
  • Podczas tworzenia listy wersji program PowerShell sortuje wersje jako ciągi, więc 1.01.0 będzie traktowany jako większy niż 1.001.0 .When listing versions, PowerShell will sort the versions as strings, so 1.01.0 will be treated as greater than 1.001.0.

Program PowerShell został utworzony przed opublikowaniem SemVer, więc zapewnia obsługę większości, ale nie wszystkich elementów SemVer, w szczególności:PowerShell was created before SemVer was published, so it provides support for most but not all elements of SemVer, specifically:

  • Nie obsługuje on parametrów wersji wstępnej w numerach wersji.It doesn't support prerelease strings in version numbers. Jest to przydatne, gdy Wydawca chce dostarczyć wersję zapoznawczą nowej wersji głównej po udostępnieniu wersji 1.0.0 .This is useful when a publisher wishes to deliver a preview release of a new major version after providing a version 1.0.0. Ta wartość będzie obsługiwana w przyszłych wersjach Galeria programu PowerShell i poleceń cmdlet programu PowerShellGet .This will be supported in a future release of the PowerShell Gallery and PowerShellGet cmdlets.
  • Program PowerShell i Galeria programu PowerShell umożliwiają stosowanie ciągów wersji z 1, 2 i 4 segmentami.PowerShell and the PowerShell Gallery allow version strings with 1, 2, and 4 segments. Wiele wczesnych modułów nie była zgodna z wytycznymi, a wydania produktów firmy Microsoft zawierają informacje o kompilacji jako czwarty blok liczb (na przykład 5.1.14393.1066 ).Many early modules did not follow the guidelines, and product releases from Microsoft include build information as a 4th block of numbers (for example 5.1.14393.1066). Różnice między wersjami punktu widzenia są ignorowane.From a versioning standpoint, these differences are ignored.

Testowanie przy użyciu repozytorium lokalnegoTest using a local repository

Galeria programu PowerShell nie jest celem do testowania procesu publikowania.The PowerShell Gallery isn't designed to be a target for testing the publishing process. Najlepszym sposobem na przetestowanie kompleksowego procesu publikowania w Galeria programu PowerShell jest skonfigurowanie i użycie własnego repozytorium lokalnego.The best way to test out the end-to-end process of publishing to the PowerShell Gallery is to set up and use your own local repository. Można to zrobić na kilka sposobów, w tym:This can be done in a few ways, including:

  • Skonfiguruj lokalne wystąpienie Galeria programu PowerShell przy użyciu projektu galerii prywatnej PS w serwisie GitHub.Set up a local PowerShell Gallery instance, using the PS Private Gallery project in GitHub. Ten projekt w wersji zapoznawczej pomoże Ci skonfigurować wystąpienie Galeria programu PowerShell, które można kontrolować, i użyć dla testów.This preview project will help you set up an instance of the PowerShell Gallery that you can control, and use for your tests.
  • Skonfiguruj wewnętrzne repozytorium NuGet.Set up an internal Nuget repository. Będzie to wymagało więcej pracy do skonfigurowania, ale będzie można sprawdzić, czy nie ma kilku innych wymagań, szczególnie sprawdzać użycie klucza interfejsu API oraz czy nie występują zależności w miejscu docelowym podczas publikowania.This will require more work to set up, but will have the advantage of validating a few more of the requirements, notably validating use of an API key, and whether or not dependencies are present in the target when you publish.
  • Skonfiguruj udział plików jako repozytorium testowe.Set up a file share as the test repository . Jest to łatwe do skonfigurowania, ale ponieważ jest to udział plików, zanotowane powyżej dane nie będą wykonywane.This is easy to set up, but since it's a file share, the validations noted above will not take place. Jedną z potencjalnych zalet w tym przypadku jest to, że udział plików nie sprawdza wymaganego klucza interfejsu API, dlatego można użyć tego samego klucza, który będzie używany do publikowania w Galeria programu PowerShell.One potential advantage in this case is that the file share doesn't check the required API key, so you can use the same key you would use to publish to the PowerShell Gallery.

Za pomocą dowolnego z tych rozwiązań Register-PSRepository Zdefiniuj nowe repozytorium , którego używasz w -Repository parametrze dla Publish-Module .With any of these solutions, use Register-PSRepository to define a new repository , which you use in the -Repository parameter for Publish-Module.

Jeden dodatkowy punkt dotyczący publikowania testów: każdy pakiet publikowany w Galeria programu PowerShell nie może zostać usunięty bez pomocy zespołu operacyjnego, który potwierdzi, że nic nie zależy od pakietu, który chcesz opublikować.One additional point about test publishing: any package you publish to the PowerShell Gallery can't be deleted without help from the operations team, who will confirm that nothing is dependent upon the package you wish to publish. Z tego powodu nie obsługujemy Galeria programu PowerShell jako celu testowania i skontaktuje się z każdym wydawcą.For that reason, we don't support the PowerShell Gallery as a testing target, and will contact any publisher who does so.

Użyj PowerShellGet do opublikowaniaUse PowerShellGet to publish

Zdecydowanie zaleca się, aby wydawcy używali Publish-Module Publish-Script poleceń cmdlet i podczas pracy z Galeria programu PowerShell.It's strongly recommended that publishers use the Publish-Module and Publish-Script cmdlets when working with the PowerShell Gallery. PowerShellGet został utworzony, aby zapobiec zapamiętaniu ważnych informacji o instalowaniu i publikowaniu w Galeria programu PowerShell.PowerShellGet was created to help you avoid remembering important details about installing from and publishing to the PowerShell Gallery. W przypadku wydawców wybrano pominięcie PowerShellGet i użycie klienta NuGet lub poleceń cmdlet programu PackageManagement , zamiast Publish-Module .On occasion, publishers have chosen to skip PowerShellGet and use the NuGet client, or PackageManagement cmdlets, instead of Publish-Module. Istnieje wiele szczegółów, które można łatwo pominąć, co skutkuje różnymi żądaniami obsługi.There are a number of details that are easily missed, which results in a variety of support requests.

Jeśli nie masz przyczyny, że nie możesz korzystać Publish-Module z Publish-Script programu lub, daj nam znać.If there's a reason that you can't use Publish-Module or Publish-Script, please let us know. Zaplikowanie problemu w repozytorium GitHub usługi PowerShellGet i podaj szczegóły, które powodują wybranie NuGet lub PackageManagement .File an issue in the PowerShellGet GitHub repo, and provide the details that cause you to choose NuGet or PackageManagement .

Najbardziej myślnym podejściem znalezionym w przypadku pakietów opublikowanych w Galeria programu PowerShell jest:The most successful approach we have found for packages published to the PowerShell Gallery is this:

  • Wykonaj wstępne programowanie w witrynie projektu Open Source.Do initial development in an open-source project site. Zespół programu PowerShell używa usługi GitHub.The PowerShell Team uses GitHub.
  • Aby uzyskać stabilny stan kodu, użyj opinii recenzentów i analizatora skryptów programu PowerShell .Use feedback from reviewers and Powershell Script Analyzer to get the code to stable state.
  • Dołącz dokumentację, aby inni wiedzieli, jak korzystać z pracy.Include documentation, so others know how to use your work.
  • Przetestuj akcję publikowania przy użyciu repozytorium lokalnego.Test out the publishing action using a local repository.
  • Opublikuj w Galeria programu PowerShell stabilną lub alfa wersję, pamiętając o uwzględnieniu dokumentacji i linku do witryny projektu.Publish a stable or Alpha release to the PowerShell Gallery, making sure to include the documentation and link to your project site.
  • Zbierz informacje zwrotne i wykonaj iterację kodu w witrynie projektu, a następnie opublikuj stabilne aktualizacje Galeria programu PowerShell.Gather feedback and iterate on the code in your project site, then publish stable updates to the PowerShell Gallery.
  • Dodaj przykłady i testy szkodników w projekcie i module.Add examples and Pester tests in your project and your module.
  • Zdecyduj, czy chcesz podpisać pakiet.Decide if you want to code sign your package.
  • Jeśli uważasz, że projekt jest gotowy do użycia w środowisku produkcyjnym, Opublikuj 1.0.0 wersję do Galeria programu PowerShell.When you feel the project is ready to use in a production environment, publish a 1.0.0 version to the PowerShell Gallery.
  • Kontynuuj zbieranie opinii i Iterowanie w kodzie na podstawie danych wejściowych użytkownika.Continue to gather feedback and iterate on your code based on user input.