Galerii PowerShellGallery publikowania wskazówki i najlepsze rozwiązaniaPowerShellGallery Publishing Guidelines and Best Practices

W tym temacie opisano zalecane kroki używana przez zespoły firmy Microsoft w zapewnienie pakiety opublikowane w galerii programu PowerShell są przyjmowane powszechnie i zapewniać wysoką wartość użytkownikom, oparte na sposób galerii programu PowerShell służy do obsługi manifestu danych i informacji zwrotnych z dużą liczby użytkowników w galerii programu PowerShell.This topic 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, które są publikowane następujące wskazówki będą najprawdopodobniej można zainstalować za zaufany i Przyciąganie uwagi 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.

Przedstawiony poniżej znajdują się wytyczne dotyczące co sprawia, że dobre pakietu galerii programu PowerShell, które opcjonalne ustawienia manifestu są dla Ciebie najważniejsze, ulepszanie kodu za pomocą informacji zwrotnych od początkowego recenzentów i analizatora skryptu programu Powershell, przechowywanie wersji modułu, dokumentacji, testy i przykłady dotyczące używania, zostały udostępnione.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 & examples for how to use what you have shared. Większość niniejszej dokumentacji następujące wytyczne dotyczące publikowania modułów zasoby DSC w usłudze wysokiej jakości.Much of this documentation follows the guidelines for publishing High Quality DSC Resource Modules.

Aby uzyskać mechanika publikowania pakietu w galerii programu PowerShell, zobacz tworzenie i publikowanie pakietu.For the mechanics of publishing a package to the PowerShell Gallery, see Creating and Publishing a Package.

Przyjęte jest opinie na temat tych wytycznych.Feedback on these guidelines is welcomed. Jeśli chcesz przesłać opinię, otwórz problemy w naszym repozytorium dokumentacji w witrynie 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ższe najlepsze rozwiązania są co powiedzieć użytkownikom elementów galerii programu PowerShell, ważne jest i są wymienione w kolejności priorytetu symboliczną cenę.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 należy wykonać te wytyczne są znacznie bardziej prawdopodobna do pobrania i przyjętych przez innych użytkowników.Packages that follow these guidelines are far more likely to be downloaded and adopted by others.

  • Użyj PSScriptAnalyzerUse PSScriptAnalyzer
  • Dokumentacja i przykładyInclude documentation and examples
  • Szybkość reakcji na opinieBe responsive to feedback
  • Podaj modułów zamiast skryptówProvide modules rather than scripts
  • Zawierają linki do witryny projektuProvide links to a project site
  • Uwzględnić testy za pomocą modułyInclude tests with your modules
  • Obejmują i/lub łącze do postanowień licencyjnychInclude and/or link to license terms
  • Zarejestruj swój kodSign your code
  • Postępuj zgodnie z SemVer wytyczne dotyczące wersjiFollow SemVer guidelines for versioning
  • Za pomocą typowych tagów, zgodnie z opisem w galerii programu PowerShell typowych tagówUse common tags, as documented in Common PowerShell Gallery tags
  • Publikowanie testu przy użyciu repozytorium lokalnegoTest publishing using a local repository
  • Publikowanie przy użyciu funkcji PowerShellGetUse PowerShellGet to publish

Każda z tych omówiono pokrótce w poniższych sekcjach.Each of these is covered briefly in the sections below.

Użyj PSScriptAnalyzerUse PSScriptAnalyzer

PSScriptAnalyzer jest narzędzie do analizy kodu statycznego bezpłatne, działające w kod programu PowerShell.PSScriptAnalyzer is a free static code analysis tool that works on PowerShell code. PSScriptAnalyzer zidentyfikuje najbardziej typowych problemów, które są widoczne w kod programu PowerShell, a także 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 łatwa w użyciu i problemach, jak błędy kategoryzuje (poważny, muszą być kierowane), ostrzegawczy (muszą być analizowane i powinny być kierowane) i informacje (warto wyewidencjonowywanie najlepsze rozwiązania dotyczące).The tool is easy to use, and categorizes the issues as Errors (severe, must be addressed), Warning (need to be reviewed & should be addressed), and Information (worth checking out for best practices). Wszystkie pakiety opublikowane w galerii programu PowerShell ma zostać przeprowadzone skanowanie za pomocą PSScriptAnalyzer oraz wszelkie błędy będzie zgłaszana z powrotem do właściciela i należy rozwiązać kwestie.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 uruchamianie 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ą naprawione lub które zostały rozwiązane w dokumentacjiAll Errors are corrected or addressed in your documentation
  • Wszystkie ostrzeżenia są przeglądane i rozwiązany, jeśli ma to zastosowanieAll Warnings are reviewed, and addressed where applicable

Użytkownicy, którzy zakupili pakiety z galerii programu PowerShell są zdecydowanie zaleca się uruchamiania PSScriptAnalyzer i ocenić wszystkie błędy i ostrzeżenia.Users who acquire packages from the PowerShell Gallery are strongly encouraged to run PSScriptAnalyzer and evaluate all Errors and Warnings. Użytkownicy są bardzo prawdopodobne, skontaktuj się z pomocą właścicieli pakietu, zobaczą, że jest błąd zgłoszony przez PSScriptAnalyzer.Users are very likely to contact package owners if they see that there is an error reported by PSScriptAnalyzer. W przypadku istotny powód do pakietu zachować kod, który jest oznaczany jako błąd, należy dodać te informacje w dokumentacji, aby uniknąć konieczności Odpowiedz na pytanie, tym samym wiele razy.If there is 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.

Dokumentacja i przykładyInclude documentation and examples

Dokumentacja i przykłady są najlepszym sposobem, aby upewnić się, że użytkownicy mogą wykorzystać udostępnionego kodu.Documentation and examples are the best way to ensure users can take advantage of any shared code.

Dokumentacja jest najbardziej przydatne rzeczy, które mają zostać objęte pakiety opublikowane w galerii programu PowerShell.Documentation is the most helpful thing to include in packages published to the PowerShell Gallery. Użytkownicy zazwyczaj będzie pomijać pakietów bez dokumentacji, alternatywą jest odczytać kodu, aby zrozumieć, co to jest pakiet i jak z niej korzystać.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. Brak dostępnych kilka artykułów o tym, jak do zapewnienia dokumentacji z pakietami programu PowerShell, w tym:There are several articles available about how to provide documentation with PowerShell packages, including:

  • Wytyczne dotyczące zapewnianie pomocy znajdują się w sposobu pisania pomoc dotyczącą polecenia CmdletGuidelines for providing help are in How to Write Cmdlet Help
  • Tworzenie pomocy dotyczącej poleceń cmdlet, które jest najlepszym rozwiązaniem dla dowolnego skryptu programu PowerShell, funkcji lub polecenia cmdlet.Creating cmdlet help, which is the best approach for any PowerShell script, function, or cmdlet. Aby uzyskać informacje o sposobie tworzenia pomocy dotyczącej poleceń cmdlet, rozpoczynać się sposobu pisania pomoc dotyczącą polecenia Cmdlet.For information about how to create cmdlet help, start with How to Write Cmdlet Help. Aby dodać pomoc w ramach skryptów, zobacz o pomoc na podstawie komentarz.To add help within a script, see About Comment Based Help.
  • Wiele modułów także dokumentacji w formacie tekstowym, takich jak pliki MarkDown.Many modules also include documentation in text format, such as MarkDown files. Może to być szczególnie przydatne w przypadku witryny projektu w usłudze Github, w którym języka znaczników Markdown jest intensywnie używanych w formacie.This can be particularly helpful when there is a project site in Github, where Markdown is a heavily used format. Najlepszym rozwiązaniem jest użycie Markdown połączonego z usługą GithubThe best practice is to use Github-flavored Markdown

Przykłady przedstawiają użytkownikom, jak pakiet jest przeznaczony do użycia.Examples show users how the package is intended to be used. Wielu deweloperów na ekranie zostanie wyświetlona informacja wyglądają na przykłady przed dokumentację, aby dowiedzieć się, jak używać języków.Many developers will say that they look at examples before documentation to understand how to use something. Najlepszy typ przykłady Pokaż podstawowe zastosowanie oraz przypadek użycia realistyczne symulowanego i kod jest dobrze komentarzem.The best type of examples show basic use, plus a simulated realistic use case, and the code is well-commented. Przykłady dla modułów opublikowanych w galerii programu PowerShell powinna być w folderze Przykłady w katalogu głównym modułu.Examples for modules published to the PowerShell Gallery should be in an Examples folder under the module root.

Wzorzec dobre przykłady można znaleźć w modułu PSDscResource w folderze Examples\RegistryResource.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ótki opis w górnej części każdego pliku dokumentuje, co jest demonstrowany.There are four sample use cases with a brief description at the top of each file that documents what is being demonstrated.

Odpowiadanie na opinięRespond to feedback

Pakiet właścicieli, którzy prawidłowo odpowiadania na opinie są bardzo cenione przez społeczności.Package owners who respond properly to feedback are highly valued by the community. Użytkownicy, którzy zwyczajowo opinii są ważne, aby odpowiedzieć, jak zainteresowane w pakiecie w celu ulepszania jej.Users who provide constructive feedback are important to respond to, as they are interested enough in the package to try to help improve it.

Dostępne są dwie metody opinii w galerii programu PowerShell:There are two feedback methods available in the PowerShell Gallery:

  • Skontaktuj się z pomocą właściciela: Umożliwia użytkownikowi Wyślij wiadomość e-mail do właściciele pakietu.Contact Owner: This allows a user to send an email to the package owner(s). Jako właściciel pakietu ważne jest, aby monitorować adres e-mail używany w pakiety galerii programu PowerShell i reagowanie na problemy, które są wywoływane.As an package owner, is important to monitor the email address used with the PowerShell Gallery packages, and respond to issues that are raised. Jedną wadą tej metody jest to, czy tylko użytkowników i właściciel nigdy nie zobaczą komunikacji, aby właściciel może być konieczne Odpowiedz na pytanie, tym samym wiele razy.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.
  • Uwagi: W dolnej części strony pakietu jest pole Komentarz.Comments: At the bottom of the package page is a Comment field. Zaletą tego systemu jest, że użytkownicy widzieli, komentarze i odpowiedzi, co zmniejsza liczbę przypadków, gdy otrzymasz odpowiedzi na każde pytanie w jednym.The advantage to this system is that other users can see the comments and responses, which reduces the number of times any single question must be answered. Jako właściciel pakietu zdecydowanie zaleca się postępowanie zgodnie z komentarzy dla każdego pakietu.As a package owner, it is strongly recommended that you Follow the comments made for each package. Zobacz zapewnianie opinii za pośrednictwem mediów społecznościowych i komentarzy szczegółowe informacje na temat jak to zrobić.See Providing Feedback via Social Media or Comments for details on how to do that.

Właściciele, którzy konstruktywnie odpowiadania na opinie są Doceniamy przez społeczność.Owners who respond to feedback constructively are appreciated by the community. Użycia szansy sprzedaży w raporcie, aby uzyskać więcej informacji, jeśli to konieczne, podaj obejście tego problemu i ustalić, czy aktualizacja rozwiązuje problem.Use the opportunity in the report to request more information if needed, provide a workaround, or identify if an update fixes a problem.

W przypadku niewłaściwe zachowanie zaobserwowane przy użyciu dowolnego z tych kanałów komunikacyjnych funkcja Zgłoś nadużycie z galerii programu PowerShell umożliwia kontaktować z administratorami w galerii.If there is 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 i skryptyModules Versus Scripts

Udostępniania innym użytkownikom skryptu jest doskonałym i udostępniają inne przykłady sposobów do 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 galerii programu PowerShell są pojedynczych plików bez oddzielna dokumentacja, przykłady i testy.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 zezwala na wiele folderów i plików, które będą dołączone do pakietu.PowerShell Modules have a folder structure that allows multiple folders and files to be included with the package. Umożliwia struktury, łącznie z innymi pakietami na listę jako najlepsze rozwiązania: polecenia cmdlet pomocy, dokumentacji, przykładów i testów.The module structure enables including the other packages we list as best practices: cmdlet help, documentation, examples, and tests. Największych wadą jest to, że skrypt wewnątrz modułu musi być udostępniane i pełnią funkcję.The biggest disadvantage is that a script inside a module must be exposed and used as a function. Aby uzyskać informacje na temat 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órym skrypt zapewnia lepsze środowisko użytkownika, szczególnie przy użyciu konfiguracji 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 publikowanie konfigurację jako skrypt za pomocą towarzyszący modułu, który zawiera dokumentacja, 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 wyświetla towarzyszącym modułu przy użyciu RequiredModules = @(nazwa modułu).The script lists the accompanying module using RequiredModules = @(Name of the Module). Takie podejście może służyć w przypadku dowolnego skryptu.This approach can be used with any script.

Skrypty autonomicznych, które najlepsze praktyki Podaj rzeczywistą wartość do innych użytkowników.Standalone scripts that follow the other best practices provide real value to other users. Udostępniając oparta na komentarzach dokumentacji i link do witryny projektu jest zdecydowanie zalecane w przypadku publikowania skryptu w galerii programu PowerShell.Providing comment-based documentation and a link to a Project Site are highly recommended when publishing a script to the PowerShell Gallery.

Witryny projektu jest, w którym wydawcy mogą wchodzić w interakcje bezpośrednio użytkownikom ich pakiety galerii programu PowerShell.A Project Site is where a publisher can interact directly with the users of their PowerShell Gallery packages. Użytkownicy preferują pakietów, które dostarczają tego, ponieważ pozwala ono je łatwiej uzyskać informacje o pakiecie.Users prefer packages that provide this, as it allows them to get information about the package more easily. Liczba pakietów w galerii programu PowerShell są tworzone w usłudze GitHub, inne są dostarczane przez organizacje, które prowadzą dedykowanej 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 jest uznawana za witryny projektu.Each of these can be considered a project site.

Dodawanie łącza odbywa się przy tym ProjectURI w sekcji PSData w manifeście 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 została podana, galerii programu PowerShell będzie zawierać link do witryny projektu z lewej strony 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.

Uwzględnić testyInclude tests

W tym testy przy użyciu kodu typu open-source ważne jest, aby użytkownicy, ponieważ umożliwia ona pewności co weryfikowania i zawiera informacje o sposobie 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 także użytkownikom upewnić się, że ich nie przerwanie własne funkcje oryginalnego mogą modyfikować kodu dopasowany ich środowiska.It also allows users to ensure they do not break your original functionality if they modify your code to fit their environment.

Zdecydowanie zaleca się, że testy zapisywane na korzystanie z zalet usług Pester struktura testów, który został zaprojektowany specjalnie dla programu PowerShell.It is strongly recommended that tests be written to take advantage of the Pester test framework, which has been designed specifically for PowerShell. Pester jest dostępna w GitHub, galerii programu PowerShelli jest dostarczany w systemu Windows 10, Windows Server 2016, WMF 5.0 i platformy 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.

Usług Pester witryny projektu w usłudze GitHub obejmuje dobra dokumentacja na temat pisania testów usług Pester od wprowadzenia 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 pokrycie testu są wywoływane w dokumentacji wysokiej jakości zasobu modułu, pokrycie kodu, zaleca się testu jednostki 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 galerii programu PowerShell, należy określić postanowienia licencyjne lub związanie licencjami w warunki użytkowania w obszarze "Załączniku A".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". Najlepszym rozwiązaniem w celu określenia innej licencji jest Podaj link, aby uzyskać licencję za pomocą LicenseURI w PSData.The best approach to specifying a different license is to provide a link to the license using the LicenseURI in PSData. Przykład można znaleźć w temacie zalecane manifeście pola.You can find an example in the Recommended Manifest Fields topic.

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'

Zarejestruj swój kodSign your code

Podpisywanie kodu zapewnia użytkownikom najwyższy poziom zabezpieczeń Wydawca pakietu, a kopię kodu zdobycia jest dokładnie wydane wydawcy.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ólnie 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 za pomocą dwóch metod podstawowego kodu:PowerShell supports validation of code signing through two primary approaches:

  • Podpisywanie plików skryptuSigning script files
  • Moduł podpisywania w kataloguCatalog signing a module

Podpisywanie plików programu PowerShell jest sprawdzone podejście do zapewnienia wykonywany kod został wyprodukowany przez wiarygodnego źródła, która nie została zmodyfikowana.Signing PowerShell files is a well-established approach to ensuring that the code being executed was produced by a reliable source, and has not been modified. Szczegółowe informacje na temat podpisywania plików skryptów programu PowerShell są omówione w temat podpisywania tematu.Details on how to sign PowerShell script files is covered in the About Signing topic. W obszarze Przegląd można dodać do żadnej sygnatury. Plik PS1, który sprawdza programu PowerShell, po załadowaniu skryptu.In overview, a signature can be added to any .PS1 file that PowerShell validates when the script is loaded. Może być ograniczona dla programu PowerShell przy użyciu zasady wykonywania poleceń cmdlet w celu zapewnienia wykorzystania podpisane skrypty.PowerShell can be constrained using the Execution Policy cmdlets to ensure use of signed scripts.

Wykaz podpisywania modułów to funkcja, dodany do programu PowerShell w wersji 5.1.Catalog signing modules is a feature added to PowerShell in version 5.1. Jak zarejestrować moduł został omówiony w polecenia cmdlet wykazu tematu.How to sign a module is covered in the Catalog Cmdlets topic. W obszarze Przegląd podpisywania katalogu odbywa się przez utworzenie pliku wykazu, który zawiera wartość skrótu dla każdego pliku w module, a dopiero następnie utworzenie tego pliku.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. Publikowanie modułu PowerShellGet, install-module, save-module i polecenia cmdlet update-module będzie sprawdzić podpis, aby upewnić się, że jest on prawidłowy, a następnie upewnij się, że jest zgodna wartość skrótu dla każdego pakietu, co znajduje się w katalogu.The PowerShellGet publish-module, install-module, save-module, and update-module cmdlets will check the signature to ensure it is valid, then confirm that the hash value for each package matches what is in the catalog. Jeśli poprzednią wersję modułu jest zainstalowany w systemie, install-module potwierdzi, że urząd odpowiedzialny za podpisywanie dla nowej wersji odpowiada co została wcześniej zainstalowana.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. Podpisywanie katalogu współpracuje z, ale nie zastępuje podpisywania plików skryptów.Catalog signing works with, but does not replace signing script files. Program PowerShell nie można zweryfikować sygnatur katalogu w czasie ładowania modułu.PowerShell does not validate catalog signatures at module load time.

Postępuj zgodnie z wytycznymi SemVer pod kątem przechowywania wersjiFollow SemVer guidelines for versioning

SemVer jest publiczny Konwencji, która zawiera instrukcje dotyczące struktury i zmienić wersję, aby umożliwić łatwe interpretacji zmian.SemVer is a public convention that describes how to structure and change a version to allow easy intepretation of changes. Wersja pakietu muszą być zawarte w danych manifestu.The version for your package must be included in the manifest data.

  • Wersja powinny mieć strukturę jako 3 bloki numeryczne, oddzielone kropkami, jak 0.1.1 lub 4.11.192The version should be structured as 3 numeric blocks separated by periods, as in 0.1.1 or 4.11.192
  • Wersje, począwszy od "0" wskazują, że pakiet nie jest jeszcze już gotowe do produkcji i pierwszy numer należy tylko zaczynają się od "0", jeśli jest to numer tylko używaneVersions starting with "0" indicate that the package is not yet production ready, and the first number should only begin with "0" if that is the only number used
  • Zmiany w pierwszy numer (1.9.9999 2.0.0) wskazują główne i istotne zmian między wersjamiChanges in the first number (1.9.9999 to 2.0.0) indicate major and breaking changes between the versions
  • Zmiany w drugą liczbę (elementu 1.01 1,02) wskazują zmiany poziomu funkcji, takich jak dodawanie nowych poleceń cmdlet do modułuChanges to the second number (1.01 to 1.02) indicate feature-level changes, such as adding new cmdlets to a module
  • Zmiany numerowi trzeci wskazywać zmian niepowodujących niezgodności, takie jak nowe parametry, przykłady zaktualizowane lub nowe testyChanges to the third number indicate non-breaking changes, such as new parameters, updated samples, or new tests
  • Podczas wyświetlania wersji, programu PowerShell pozwala na sortowanie wersje jako ciągi, więc 1.01.0 będą traktowane jako większy niż 1.001.0When 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 SemVer został opublikowany, udostępnia obsługę większości, ale nie wszystkie elementy 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:

  • Wstępna ciągów nie obsługuje numerów wersji.It does not support prerelease strings in version numbers. Jest to przydatne, gdy wydawca chce dostarczać wersję zapoznawczą nowej wersji głównej po podaniu 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. Będzie to możliwe w przyszłej wersji poleceń cmdlet narzędzia z galerii programu PowerShell i modułu PowerShellGet.This will be supported in a future release of the PowerShell Gallery and PowerShellGet cmdlets.
  • Program PowerShell i galerii programu PowerShell umożliwiają ciągów w wersji 1, 2 i 4 segmentów.PowerShell and the PowerShell Gallery allow version strings with 1, 2, and 4 segments. Wiele modułów wczesne nie korzystał z wytycznymi i wersje produktu od firmy Microsoft zawierają informacje o kompilacji, ponieważ 4 blokowanie 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). Z punktu widzenia versioning te różnice 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 przeznaczony do obiektu docelowego dla testowania proces publikowania.The PowerShell Gallery is not designed to be a target for testing the publishing process. Jest najlepszym sposobem przetestowania end-to-end procesu publikowania w galerii programu PowerShell do konfigurowania i używania 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 galerii programu PowerShell, za pomocą projektu galerią prywatną PS w usłudze Github.Set up a local PowerShell Gallery instance, using the PS Private Gallery project in Github. Ten projekt w wersji zapoznawczej pomoże poświęcona jest konfigurowaniu wystąpienia galerii programu PowerShell, które możesz kontrolować i używany do 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.
  • Konfigurowanie wewnętrznego repozytorium Nuget.Set up an internal Nuget repository. Wymaga więcej pracy do skonfigurowania, ale ma tę zaletę, sprawdzanie poprawności kilka innych wymagań, szczególnie sprawdzania poprawności korzystanie z klucza interfejsu API i czy nie zależności znajdują się w 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.
  • Konfigurowanie udziału plików jako test "repozytorium".Set up a file share as the test “repository”. Jest to łatwe do skonfigurowania, ale ponieważ jest udział plików, sprawdzanie poprawności przedstawionych powyżej zaczną obowiązywać.This is easy to set up, but since it is a file share, the validations noted above will not take place. Jedną z zalet potencjalnych w tym przypadku jest, że udział plików nie sprawdza (wymagane) klucz interfejsu API, dzięki czemu można używać tego samego klucza jak publikowanie w galerii programu PowerShell.One potential advantage in this case is that the file share does not check the (required) API key, so you can use the same key you would to publish to the PowerShell Gallery.

Za pomocą dowolnego z tych rozwiązań Użyj Register-PSRepository, aby zdefiniować nowe "repozytorium", które będzie używane we właściwości - repozytorium Publish-Module.With any of these solutions, use Register-PSRepository to define a new "repository", which you use in the -Repository property for Publish-Module.

Jeden dodatkowy punkt o publikowaniu testu: nie można usunąć dowolny pakiet, publikowanie w galerii programu PowerShell bez pomocy działu operacyjnego, która potwierdzi, że nic nie jest zależny od pakietu, którą chce opublikować.One additional point about test publishing: any package you publish to the PowerShell Gallery cannot 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 firma Microsoft nie obsługują galerii programu PowerShell jako obiekt docelowy testowania i skontaktuje się z dowolnego wydawcy, który wykonuje tę funkcję.For that reason, we do not support the PowerShell Gallery as a testing target, and will contact any publisher who does so.

Publikowanie przy użyciu funkcji PowerShellGetUse PowerShellGet to publish

Zdecydowanie zaleca się, że wydawcy używają poleceń cmdlet Publish-Module i Publish-Script podczas pracy z galerii programu PowerShell.It is strongly recommended that publishers use the Publish-Module and Publish-Script cmdlets when working with the PowerShell Gallery. Moduł PowerShellGet został utworzony, aby pomóc w uniknięciu zapamiętywanie ważne informacje dotyczące instalowania z i publikowanie w galerii programu PowerShell.PowerShellGet has been created to help you avoid remembering important details about installing from and publishing to the PowerShell Gallery. Czasami wydawców wybrano opuszczenia PowerShellGet i użycia klienta programu NuGet, lub polecenia cmdlet funkcji 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 szereg szczegółowe informacje, które są łatwo przeoczyć, co skutkuje szereg żądania pomocy technicznej.There are a number of details that are easily missed, which results in a variety of support requests.

W przypadku przyczyna, że nie możesz użyć Publish-Module ani Publish-Script, Daj nam znać.If there is a reason that you cannot use Publish-Module or Publish-Script, please let us know. Prześlij zgłoszenie w repozytorium PowerShellGet GitHub i podaj szczegółowe informacje, które można wybrać NuGet lub PackageManagement spowodować.File an issue in the PowerShellGet GitHub repo, and provide the details that cause you to choose NuGet or PackageManagement.

Najbardziej podejście, które znaleźliśmy pakiety opublikowane w galerii programu PowerShell są następujące:The most successful approach we have found for packages published to the PowerShell Gallery is this:

  • Początkowy Programowanie w lokacji projekt open source.Do initial development in a an open-source project site. Zespół programu PowerShell używa usługi Github.The PowerShell Team uses Github.
  • Użyj opinie recenzentów i analizatora skryptu programu Powershell można pobrać kodu do czasu trwania stanu stabilnego stanuUse feedback from reviewers and Powershell Script Analyzer to get the code to stable state
  • Obejmuje dokumentacji, więc innych wie, jak korzystać pracyInclude documentation, so others know how to use your work
  • Przetestuj publikowania akcję przy użyciu repozytorium lokalnego.Test out the publishing action using a local repository.
  • Publikowanie wersji stałe lub alfa w galerii programu PowerShell, upewniając się uwzględnić w dokumentacji i link do witryny projektuPublish a stable or Alpha release to the PowerShell Gallery, making sure to include the documentation and link to your project site
  • Zbieraj opinie i iteracji dla kodu w witrynie usługi project, a następnie opublikować stabilną aktualizacje w galerii programu PowerShellGather feedback and iterate on the code in your project site, then publish stable updates to the PowerShell Gallery
  • Dodaj przykłady oraz usług Pester testów w projekcie i modułuAdd examples and Pester tests in your project and your module
  • Określenie, czy kodowi Zaloguj się do pakietuDecide if you want to code sign your package
  • Jeśli uważasz, że projekt jest gotowa do użycia w środowisku produkcyjnym, należy opublikować 1.0.0 wersji w galerii programu PowerShellWhen you feel the project is ready to use in a production environment, publish a 1.0.0 version to the PowerShell Gallery
  • Przejdź do zbierania opinii i powtarzanie czynności w kodzie, w oparciu o dane wejściowe użytkownikaContinue to gather feedback and iterate on your code based on user input