Veröffentlichungsrichtlinien und Best Practices für den PowerShell-KatalogPowerShellGallery Publishing Guidelines and Best Practices

In diesem Artikel erfahren Sie, welche Schritte die Microsoft-Teams empfehlen, damit Ihre im PowerShell-Katalog veröffentlichten Elemente von möglichst vielen Benutzern verwendet werden und diesen einen hohen Mehrwert bieten. Diese Empfehlungen basieren auf der Verarbeitung von Manifestdaten durch den PowerShell-Katalog sowie auf dem Feedback zahlreicher PowerShell-Katalogbenutzer.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. Pakete, die gemäß den hier beschriebenen Richtlinien veröffentlicht werden, werden eher installiert, als vertrauenswürdig eingestuft und erzielen ein größeres Benutzerinteresse.Packages that are published following these guidelines will be more likely to be installed, trusted, and attract more users.

Die nachfolgenden Richtlinien definieren, wodurch sich ein gutes PowerShell-Katalogpaket auszeichnet, welche optionalen Manifesteinstellungen besonders wichtig sind, wie Sie Ihren Code mithilfe von Feedback von Rezensenten und PowerShell Script Analyzer verbessern und wie Sie die Versionen Ihres Moduls, der zugehörigen Dokumentation sowie von Tests und Anwendungsbeispielen verwalten.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. Ein Großteil dieser Dokumentation folgt den Richtlinien für das Veröffentlichen von hochwertigen DSC-Ressourcenmodulen.Much of this documentation follows the guidelines for publishing High Quality DSC Resource Modules.

Informationen zu den Mechanismen für das Veröffentlichen eines Pakets im PowerShell-Katalog finden Sie unter Erstellen und Veröffentlichen eines Pakets.For the mechanics of publishing a package to the PowerShell Gallery, see Creating and Publishing a Package.

Wir freuen uns auf Ihr Feedback zu diesen Richtlinien.Feedback on these guidelines is welcomed. Wenn Sie Anmerkungen haben, öffnen Sie ein Issue in unserem GitHub-Dokumentationsrepository.If you do have feedback, please open issues in our GitHub documentation repository.

Bewährte Methoden zum Veröffentlichen von PaketenBest practices for publishing packages

Die folgenden Best Practices für PowerShell-Katalogelemente definieren die Punkte, die von Katalogbenutzern als wichtig eingestuft werden, aufgeführt nach der genannten Priorität.The following best practices are what the users of PowerShell Gallery items say is important, and are listed in nominal priority order. Pakete, die diesen Richtlinien entsprechen, werden eher heruntergeladen und von den Benutzern angenommen.Packages that follow these guidelines are far more likely to be downloaded and adopted by others.

  • Verwenden Sie PSScriptAnalyzerUse PSScriptAnalyzer
  • Stellen Sie eine Dokumentation und Beispiele bereitInclude documentation and examples
  • Antworten Sie auf FeedbackBe responsive to feedback
  • Stellen Sie anstelle von Skripts Module bereitProvide modules rather than scripts
  • Stellen Sie einen Link zu einer Projektwebsite bereitProvide links to a project site
  • Versehen Sie Ihr Paket mit Tags der kompatiblen PowerShell-Edition(en) und PlattformenTag your package with the compatible PSEdition(s) and platforms
  • Schließen Sie Tests in Ihre Module einInclude tests with your modules
  • Schließen Sie Lizenzbedingungen (bzw. einen Link auf diese) einInclude and/or link to license terms
  • Signieren Sie Ihren CodeSign your code
  • Folgen Sie bei der Versionsverwaltung den SemVer-RichtlinienFollow SemVer guidelines for versioning
  • Verwenden Sie allgemeine Tags, wie in „Common PowerShell Gallery Tags“ dokumentiert.Use common tags, as documented in Common PowerShell Gallery tags
  • Testen der Veröffentlichung mit einem lokalen RepositoryTest publishing using a local repository
  • Verwenden von PowerShell für die VeröffentlichungUse PowerShellGet to publish

Jede dieser Richtlinien wird in den nachfolgenden Abschnitten kurz erläutert.Each of these is covered briefly in the sections below.

Verwenden Sie PSScriptAnalyzerUse PSScriptAnalyzer

PSScriptAnalyzer ist ein kostenloses Analysetool für statischen Code, das für PowerShell-Code eingesetzt werden kann.PSScriptAnalyzer is a free static code analysis tool that works on PowerShell code. PSScriptAnalyzer identifiziert die häufigsten Probleme in PowerShell-Code und stellt in vielen Fällen eine Empfehlung zur Lösung des Problems bereit.PSScriptAnalyzer will identify the most common issues seen in PowerShell code, and often a recommendation for how to fix the issue. Das Tool lässt sich ganz einfach bedienen und unterteilt die Probleme in Fehler (schwerwiegend, müssen behoben werden), Warnungen (müssen überprüft und sollten behoben werden) und Informationsmeldungen (sollten im Rahmen von Best Practices überprüft werden).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). Alle im PowerShell-Katalog veröffentlichte Pakete werden mithilfe von PSScriptAnalyzer überprüft. Gefundene Fehler werden dem Besitzer gemeldet und müssen beseitigt werden.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.

Als Best Practice wird Invoke-ScriptAnalyzer mit -Recurse und -Severity mit der Einstellung „Warning“ ausgeführt.The best practice is to run Invoke-ScriptAnalyzer with -Recurse and -Severity Warning.

Überprüfen Sie die Ergebnisse, und stellen Sie Folgendes sicher:Review the results, and ensure that:

  • Alle Fehler wurden behoben oder in Ihrer Dokumentation vermerkt und erläutert.All Errors are corrected or addressed in your documentation.
  • Alle Warnungen wurden überprüft und nach Möglichkeit behoben.All Warnings are reviewed, and addressed where applicable.

Benutzern, die Pakete aus dem PowerShell-Katalog herunterladen, wird dringend empfohlen, PSScriptAnalyzer auszuführen und alle Fehler und Warnungen auszuwerten.Users who download packages from the PowerShell Gallery are strongly encouraged to run PSScriptAnalyzer and evaluate all Errors and Warnings. Benutzer setzen sich sehr wahrscheinlich mit den Paketbesitzern in Verbindung, wenn PSScriptAnalyzer einen Fehler meldet.Users are very likely to contact package owners if they see that there's an error reported by PSScriptAnalyzer. Wenn ein triftiger Grund dafür spricht, als fehlerhaft markierten Code in Ihrem Paket beizubehalten, fügen Sie diese Information zu Ihrer Dokumentation hinzu. So müssen Sie nicht wiederholt dieselbe Frage beantworten.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.

Stellen Sie eine Dokumentation und Beispiele bereitInclude documentation and examples

Benutzer können freigegebenen Code optimal nutzen, wenn eine Dokumentation und Beispiele bereitgestellt werden.Documentation and examples are the best way to ensure users can take advantage of any shared code.

Die Dokumentation ist die nützlichste Informationsquelle, die für ein im PowerShell-Katalog veröffentlichtes Paket bereitgestellt werden kann.Documentation is the most helpful thing to include in packages published to the PowerShell Gallery. Benutzer meiden im Allgemeinen Pakete ohne Dokumentation, da die Alternative darin besteht, den Code lesen zu müssen, um das Paket und seine Verwendung zu verstehen.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. In MSDN finden Sie verschiedene Artikel zur Bereitstellung von Dokumentation für PowerShell-Pakete, darunter diese:There are several articles available about how to provide documentation with PowerShell packages, including:

  • Richtlinien zum Bereitstellen von Hilfe finden Sie im Artikel How to Write Cmdlet Help (Schreiben von Hilfe zu Cmdlets).Guidelines for providing help are in How to Write Cmdlet Help.
  • Das Erstellen von Hilfetexten zu Cmdlets ist der beste Ansatz für beliebige PowerShell-Skripts, -Funktionen oder -Cmdlets.Creating cmdlet help, which is the best approach for any PowerShell script, function, or cmdlet. Informationen dazu, wie Sie eine Cmdlet-Hilfe schreiben, finden Sie unter How to Write Cmdlet Help (Schreiben von Hilfe zu Cmdlets).For information about how to create cmdlet help, start with How to Write Cmdlet Help. Informationen dazu, wie Sie innerhalb eines Skripts Hilfe hinzufügen, finden Sie unter Informationen zur kommentarbasierten Hilfe.To add help within a script, see About Comment Based Help.
  • Viele Module enthalten Dokumentation in Textformat, z.B. als MarkDown-Dateien.Many modules also include documentation in text format, such as MarkDown files. Dies kann besonders nützlich sein, wenn eine Projektwebsite in GitHub vorhanden ist, wo Markdowndateien ein häufig verwendetes Format sind.This can be particularly helpful when there's a project site in GitHub, where Markdown is a heavily used format. Als Best Practice sollte GitHub Flavored Markdown (GFM) verwendet werden.The best practice is to use GitHub-flavored Markdown.

Beispiele zeigen dem Benutzer, wie das Paket verwendet werden sollte.Examples show users how the package is intended to be used. Viele Entwickler sehen sich die Beispiele noch vor der Dokumentation an, um die Verwendungsweise eines Elements zu verstehen.Many developers will say that they look at examples before documentation to understand how to use something. Gute Beispiele zeigen die grundlegende Verwendung sowie einige simulierte realistische Anwendungsfälle, und der Code ist gut kommentiert.The best types of examples show basic use, plus a simulated realistic use case, and the code is well-commented. Beispiele für im PowerShell-Katalog veröffentlichte Module sollten in einem Ordner „Examples“ im Modulstamm enthalten sein.Examples for modules published to the PowerShell Gallery should be in an Examples folder under the module root.

Ein gutes Muster für Beispiele finden Sie im PSDscResource-Modul im Ordner Examples\RegistryResource.A good pattern for examples can be found in the PSDscResource module under the Examples\RegistryResource folder. Dort sind vier Beispielanwendungsfälle mit einer kurzen Beschreibung zu Beginn jeder Datei enthalten, die das Gezeigte dokumentieren.There are four sample use cases with a brief description at the top of each file that documents what is being demonstrated.

Verwalten von AbhängigkeitenManage Dependencies

Es ist wichtig, im Modulmanifest die Module anzugeben, von denen Ihr Modul abhängig ist.It's important to specify modules that your module is dependent on in the Module Manifest. Auf diese Weise müssen sich die Endbenutzer keine Sorgen um die Installation der richtigen Versionen von Modulen machen, von denen Ihr Modul abhängt.This allows the end user to not have to worry about installing the proper versions of modules that yours take a dependency on. Um die Modulabhängigkeiten anzugeben, verwenden Sie das Feld für erforderliche Module im Modulmanifest.To specify dependent modules, you should use the required module field in the module manifest. So werden vor dem Import Ihres Moduls alle aufgelisteten Module in die globale Umgebung geladen, sofern nicht bereits geschehen.This will load any listed modules into the global environment prior to importing your module unless they've already been loaded. Einige Module könnten beispielsweise bereits durch ein anderes Modul geladen worden sein.For example, some modules may already be loaded by a different module. Anstelle des ModuleVersion-Felds kann auch das RequiredVersion-Feld verwendet werden, um eine bestimmte Version anzugeben, die geladen werden soll.It's also possible to specify a specific version to load using the RequiredVersion field rather than the ModuleVersion field. Bei Verwendung des ModuleVersion-Felds wird die neueste verfügbare Version unter Berücksichtigung der angegebenen Mindestversion geladen.When using ModuleVersion, it will load the newest version available with a minimum of the version specified. Wenn das RequiredVersion-Feld nicht zum Angeben einer bestimmten Version verwendet wird, ist es wichtig, das erforderliche Modul auf Versionsupdates zu überwachen.When not using the RequiredVersion field, to specify a specific version it's important to monitor version updates to the required module. Insbesondere müssen Breaking Changes berücksichtigt werden, die die Benutzerfreundlichkeit Ihres Moduls beeinträchtigen könnten.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"})

Antworten Sie auf FeedbackRespond to feedback

Paketbesitzer, die angemessen auf Feedback reagieren, werden in der Community sehr geschätzt.Package owners who respond properly to feedback are highly valued by the community. Es ist wichtig, Benutzern zu antworten, die konstruktives Feedback geben, da diese Benutzer Sie dabei unterstützen können, das Paket zu verbessern.Users who provide constructive feedback are important to respond to, as they're interested enough in the package to try to help improve it.

Im PowerShell-Katalog sind zwei Feedbackmethoden verfügbar:There are two feedback methods available in the PowerShell Gallery:

  • Besitzer kontaktieren: Über diese Option kann ein Benutzer eine E-Mail an den Paketbesitzer senden.Contact Owner: This allows a user to send an email to the package owner. Als Paketbesitzer müssen Sie dafür Sorge tragen, dass die für PowerShell-Katalogpakete verwendete E-Mail-Adresse regelmäßig überwacht wird und gemeldete Probleme beantwortet werden.As a package owner, is important to monitor the email address used with the PowerShell Gallery packages, and respond to issues that are raised. Ein Nachteil dieser Methode besteht darin, dass die Kommunikation nur zwischen Benutzer und Besitzer erfolgt, sodass der Besitzer dieselbe Frage möglicherweise wiederholt beantworten muss.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.
  • Kommentare: Im unteren Bereich der Paketseite befindet sich ein Kommentarfeld.Comments: At the bottom of the package page is a Comment field. Der Vorteil dieses Systems liegt darin, dass andere Benutzer die Kommentare und Antworten sehen können. Auf diese Weise muss eine einzelne Frage nicht wiederholt beantwortet werden.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. Paketbesitzern wird dringend empfohlen, die Kommentare für jedes Paket nachzuverfolgen.As a package owner, it's strongly recommended that you follow the comments made for each package. Ausführliche Informationen hierzu finden Sie unter Bereitstellen von Feedback über soziale Netzwerke oder Kommentare.See Providing Feedback via Social Media or Comments for details on how to do that.

Besitzer, die konstruktiv auf Feedback reagieren, werden von der Community sehr geschätzt.Owners who respond to feedback constructively are appreciated by the community. Nutzen Sie die Gelegenheit im Bericht, um weitere Informationen anzufordern.Use the opportunity in the report to request more information. Stellen Sie bei Bedarf eine Problemumgehung bereit, oder finden Sie heraus, ob ein Update das Problem beheben kann.If needed, provide a workaround, or identify if an update fixes a problem.

Falls in einem dieser Kommunikationskanäle ein unangemessenes Verhalten zu beobachten ist, verwenden Sie das Feature „Missbrauch melden“ im PowerShell-Katalog, um sich an die PowerShell-Katalogadministratoren zu wenden.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.

Module und Skripts im VergleichModules Versus Scripts

Das Freigeben eines Skripts für andere Benutzer ist grundsätzlich eine gute Sache und ermöglicht es, Beispiele für die Beseitigung möglicher Probleme bereitzustellen.Sharing a script with other users is great, and provides others with examples of how to solve problems they may have. Der Nachteil von Skripts im PowerShell-Katalog liegt darin, dass es sich um einzelne Dateien ohne separate Dokumentation, Beispiele und Tests handelt.The issue is that scripts in the PowerShell Gallery are single files without separate documentation, examples, and tests.

PowerShell-Module bieten eine Ordnerstruktur, die es erlaubt, mehrere Ordner und Dateien in das Paket einzuschließen.PowerShell Modules have a folder structure that allows multiple folders and files to be included with the package. Die Modulstruktur ermöglicht das Bereitstellen weiterer Pakete, die wir als Best Practices auflisten: Cmdlet-Hilfe, Dokumentation, Beispiele und Tests.The module structure enables including the other packages we list as best practices: cmdlet help, documentation, examples, and tests. Der größte Nachteil besteht darin, dass ein Skript innerhalb eines Moduls als Funktion verfügbar gemacht und verwendet werden muss.The biggest disadvantage is that a script inside a module must be exposed and used as a function. Informationen zum Erstellen eines Moduls finden Sie unter Writing a Windows PowerShell Module (Schreiben eines Windows PowerShell-Moduls).For information on how to create a module, see Writing a Windows PowerShell Module.

Es gibt Situationen, in denen ein Skript benutzerfreundlicher ist, dies gilt insbesondere bei DSC-Konfigurationen.There are situations where a script provides a better experience for the user, particularly with DSC configurations. Die bewährte Methode für DSC-Konfigurationen besteht darin, die Konfiguration als Skript zu veröffentlichen, gemeinsam mit einem Begleitmodul, das die Dokumentation, Beispiele und Tests enthält.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. Das Skript listet das Begleitmodul mithilfe von RequiredModules = @(Name of the Module) auf.The script lists the accompanying module using RequiredModules = @(Name of the Module). Dieser Ansatz kann für jedes Skript verwendet werden.This approach can be used with any script.

Eigenständige Skripts, die den weiteren Best Practices entsprechen, bieten anderen Benutzern einen echten Nutzen.Standalone scripts that follow the other best practices provide real value to other users. Beim Veröffentlichen eines Skripts im PowerShell-Katalog wird dringend empfohlen, eine kommentarbasierte Dokumentation und einen Link zu einer Projektwebsite bereitzustellen.Providing comment-based documentation and a link to a Project Site are highly recommended when publishing a script to the PowerShell Gallery.

Auf einer Projektwebsite kann der Herausgeber direkt mit den Benutzern seiner PowerShell-Katalogpakete interagieren.A Project Site is where a publisher can interact directly with the users of their PowerShell Gallery packages. Benutzer bevorzugen Pakete mit einer Projektwebsite, weil es einfacher ist, Informationen zum Paket zu erhalten.Users prefer packages that provide this, as it allows them to get information about the package more easily. Viele Pakete im PowerShell-Katalog werden in GitHub entwickelt, andere werden von Organisationen mit einer dedizierten Webpräsenz bereitgestellt.Many packages in the PowerShell Gallery are developed in GitHub, others are provided by organizations with a dedicated web presence. Beides kann als eine Projektwebsite betrachtet werden.Each of these can be considered a project site.

Ein Link kann durch Einschließen eines ProjectURI-Werts im PSData-Abschnitt des Manifests hinzugefügt werden: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'

Wenn Sie einen ProjectURI angeben, wird im PowerShell-Katalog links auf der Paketseite ein Link zur Projektwebsite angezeigt.When a ProjectURI is provided, the PowerShell Gallery will include a link to the Project Site on the left side of the package page.

Versehen Sie Ihr Paket mit Tags der kompatiblen PowerShell-Edition(en) und PlattformenTag your package with the compatible PSEdition(s) and platforms

Verwenden Sie die folgenden Tags, um Benutzern anzuzeigen, welche Pakete sich für deren Umgebung gut eignen:Use the following tags to demonstrate to users which packages will work well with their environment:

  • PSEdition_Desktop: Pakete, die mit Windows PowerShell kompatibel sind.PSEdition_Desktop: Packages that are compatible with Windows PowerShell
  • PSEdition_Core: Pakete, die mit PowerShell Core kompatibel sind.PSEdition_Core: Packages that are compatible with PowerShell Core
  • Windows: Pakete, die mit dem Windows-Betriebssystem kompatibel sind.Windows: Packages that are compatible with the Windows Operating System
  • Linux: Pakete, die mit dem Linux-Betriebssystem kompatibel sind.Linux: Packages that are compatible with Linux Operating Systems
  • MacOS: Pakete, die mit MacOS kompatibel sind.MacOS: Packages that are compatible with the Mac Operating System

Wenn Sie das Paket mit den kompatiblen Plattformen markieren, wird es in die Katalogsuchfilter im linken Bereich der Suchergebnisse einbezogen.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. Wenn Sie Ihr Paket auf GitHub hosten, profitieren Sie durch die Markierung außerdem von unserem PowerShell-Katalog-Kompatibilitätsschutz Kompatibilitätsschutz.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.

Schließen Sie Tests einInclude tests

Das Einschließen von Tests mit Open Source-Code ist wichtig für die Benutzer, weil diese so sicher sein können, dass Ihr Code überprüft wurde. Zudem können Sie Informationen zur Funktionsweise des Codes bereitstellen.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. Darüber hinaus können die Benutzer sich darauf verlassen, dass die ursprüngliche Funktionalität durch eine Anpassung Ihres Codes an die Benutzerumgebung nicht beeinträchtigt wird.It also allows users to ensure they don't break your original functionality if they modify your code to fit their environment.

Es wird dringend empfohlen, Tests zu erstellen, um von den Vorteilen des Pester-Testframeworks zu profitieren, das speziell für PowerShell entworfen wurde.It's strongly recommended that tests be written to take advantage of the Pester test framework, which has been designed specifically for PowerShell. Pester ist in GitHub und dem PowerShell-Katalog verfügbar und gehört zum Lieferumfang von Windows 10, Windows Server 2016, WMF 5.0 und 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.

Die Pester-Projektwebsite in GitHub umfasst eine gute Dokumentation zum Schreiben von Pester-Tests – von den ersten Schritten bis hin zu den Best Practices.The Pester project site in GitHub includes good documentation on writing Pester tests, from getting started to best practices.

Die Ziele für die Testabdeckung werden in der Dokumentation zu hochwertigen Ressourcenmodulen benannt, hierbei wird für Komponententests eine Codeabdeckung von 70 % empfohlen.The targets for test coverage are called out in the High Quality Resource Module documentation, with 70% unit test code coverage recommended.

Alle Pakete, die im PowerShell-Katalog veröffentlicht werden, müssen Lizenzbedingungen angeben oder der Lizenz unterliegen, die in den Nutzungsbedingungen unter Anhang A enthalten sind. Die beste Vorgehensweise für das Angeben einer anderen Lizenz besteht darin, mithilfe des LicenseURI in PSData einen Link zur Lizenz bereitzustellen.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. Weitere Informationen finden Sie unter Paketmanifest und Katalogbenutzeroberfläche.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'

Signieren Sie Ihren CodeSign your code

Durch Signieren des Codes bieten Sie Benutzern höchstmögliche Sicherheit in Bezug auf den Paketherausgeber – die Benutzer können darauf vertrauen, dass die erworbene Kopie des Codes exakt dem Code entspricht, den der Herausgeber veröffentlicht hat.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. Allgemeine Informationen zum Signieren von Code finden Sie in der Einführung in das Codesignieren.To learn more about code signing generally, see Introduction to Code Signing. PowerShell unterstützt in Bezug auf das Signieren von Code zwei primäre Ansätze:PowerShell supports validation of code signing through two primary approaches:

  • Signieren von SkriptdateienSigning script files
  • Katalogsignierung von ModulenCatalog signing a module

Das Signieren von PowerShell-Dateien ist ein bewährtes Vorgehen, mit dem sichergestellt wird, dass der ausgeführte Code aus einer zuverlässigen Quelle stammt und nicht verändert wurde.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. Details zum Signieren von PowerShell-Skriptdateien werden im Artikel Informationen zu Signaturen beschrieben.Details on how to sign PowerShell script files is covered in the About Signing article. Eine Signatur kann jeder .PS1-Datei hinzugefügt werden, die PowerShell beim Laden des Skripts überprüft.In overview, a signature can be added to any .PS1 file that PowerShell validates when the script is loaded. Mithilfe der Cmdlets für Ausführungsrichtlinien kann PowerShell auf die Verwendung von signierten Skripts beschränkt werden.PowerShell can be constrained using the Execution Policy cmdlets to ensure use of signed scripts.

Die Katalogsignierung von Modulen ist ein Feature, das PowerShell in Version 5.1 hinzugefügt wurde.Catalog signing modules is a feature added to PowerShell in version 5.1. Das Signieren eines Moduls wird im Artikel Katalog-Cmdlets erläutert.How to sign a module is covered in the Catalog Cmdlets article. Allgemein ausgedrückt wird bei der Katalogsignierung eine Katalogdatei erstellt, die einen Hashwert für jede Datei im Modul enthält, und anschließend wird diese Datei signiert.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.

Die PowerShellGet-Cmdlets Publish-Module, Install-Module und Update-Module überprüfen die Signatur auf Gültigkeit und bestätigen dann, dass der Hashwert für jedes Paket den Daten im Katalog entspricht.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 überprüft keine Signaturen.Save-Module doesn't validate a signature. Wenn eine vorherige Version des Moduls im System installiert ist, wird mit Install-Module bestätigt, dass die Signaturstelle für die neue Version derjenigen der vorherigen Installation entspricht.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 und Update-Module verwenden die Signatur in einer .PSD1-Datei, wenn das Paket nicht durch den Katalog signiert wurde.Install-Module and Update-Module will use the signature on a .PSD1 file if the package isn't catalog signed. Die Katalogsignierung kann zusammen mit dem Signieren von Skriptdateien verwendet werden, ersetzt diese Methode aber nicht.Catalog signing works with, but doesn't replace signing script files. PowerShell führt beim Laden von Modulen keine Überprüfung von Katalogsignaturen durch.PowerShell doesn't validate catalog signatures at module load time.

Folgen Sie bei der Versionsverwaltung den SemVer-RichtlinienFollow SemVer guidelines for versioning

SemVer ist eine öffentliche Konvention, die beschreibt, wie eine Version strukturiert und geändert wird, um eine einfache Interpretation von Änderungen zu ermöglichen.SemVer is a public convention that describes how to structure and change a version to allow easy interpretation of changes. Die Version für Ihr Paket muss in den Manifestdaten enthalten sein.The version for your package must be included in the manifest data.

  • Die Version sollte aus drei numerischen Blöcken bestehen, die durch Punkte getrennt sind, z. B. 0.1.1 oder 4.11.192.The version should be structured as three numeric blocks separated by periods, as in 0.1.1 or 4.11.192.
  • Mit 0 beginnende Versionsnummern weisen darauf hin, dass das Paket noch nicht bereit für die Produktion ist, und die erste Zahl darf nur mit 0 beginnen, wenn dies die einzige verwendete Zahl ist.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.
  • Änderungen an der ersten Zahl (1.9.9999 zu 2.0.0) weisen auf wichtige Änderungen und Breaking Changes zwischen den Versionen hin.Changes in the first number (1.9.9999 to 2.0.0) indicate major and breaking changes between the versions.
  • Änderungen an der zweiten Zahl (1.1 zu 1.2) weisen auf Änderungen auf Featureebene hin, z. B. neue Cmdlets, die dem Modul hinzugefügt wurden.Changes to the second number (1.1 to 1.2) indicate feature-level changes, such as adding new cmdlets to a module.
  • Änderungen an der dritten Zahl weisen auf Änderungen hin, bei denen es sich nicht um Breaking Changes handelt, z. B. neue Parameter, aktualisierte Beispiele oder neue Tests.Changes to the third number indicate non-breaking changes, such as new parameters, updated samples, or new tests.
  • Beim Auflisten von Versionen sortiert PowerShell die Versionen als Zeichenfolgen, deshalb wird 1.01.0 als größer als 1.001.0 eingestuft.When listing versions, PowerShell will sort the versions as strings, so 1.01.0 will be treated as greater than 1.001.0.

PowerShell wurde vor Herausgabe der SemVer-Richtlinien entwickelt und bietet daher Unterstützung für die meisten, aber nicht alle Elemente von SemVer. Hierbei gilt insbesondere Folgendes:PowerShell was created before SemVer was published, so it provides support for most but not all elements of SemVer, specifically:

  • In Versionsnummern werden keine Zeichenfolgen für Vorabreleases unterstützt.It doesn't support prerelease strings in version numbers. Dies ist nützlich, wenn ein Herausgeber ein Vorschaurelease einer neuen Hauptversion bereitstellen möchte, nachdem eine Version 1.0.0 veröffentlicht wurde.This is useful when a publisher wishes to deliver a preview release of a new major version after providing a version 1.0.0. Diese Option wird in einer zukünftigen Version des PowerShell-Katalogs und der PowerShellGet-Cmdlets unterstützt.This will be supported in a future release of the PowerShell Gallery and PowerShellGet cmdlets.
  • PowerShell und der PowerShell-Katalog lassen Versionszeichenfolgen mit 1, 2 und 4 Segmenten zu.PowerShell and the PowerShell Gallery allow version strings with 1, 2, and 4 segments. Viele frühere Module entsprachen nicht den Richtlinien, und Produktversionen von Microsoft enthalten Buildinformationen als 4. Zahlenblock (z. B. 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). Vom Standpunkt der Versionsverwaltung aus werden diese Unterschiede ignoriert.From a versioning standpoint, these differences are ignored.

Testen mit einem lokalen RepositoryTest using a local repository

Der PowerShell-Katalog ist nicht als Ziel zum Testen des Veröffentlichungsprozesses konzipiert.The PowerShell Gallery isn't designed to be a target for testing the publishing process. Die beste Methode, um den End-to-End-Prozess der Veröffentlichung im PowerShell-Katalog zu testen, ist das Einrichten und Verwenden Ihres eigenen lokalen Repositorys.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. Dies kann auf verschiedene Arten erfolgen, einschließlich folgender:This can be done in a few ways, including:

  • Richten Sie mithilfe des PS Private Gallery-Projekts in GitHub eine lokale Instanz des PowerShell-Katalogs ein.Set up a local PowerShell Gallery instance, using the PS Private Gallery project in GitHub. Dieses Vorschauprojekt wird Sie beim Einrichten einer Instanz des PowerShell-Katalogs unterstützen, die Sie steuern und für Ihre Tests benutzen können.This preview project will help you set up an instance of the PowerShell Gallery that you can control, and use for your tests.
  • Richten Sie ein internes NuGet-Repository ein.Set up an internal Nuget repository. Dieses einzurichten erfordert mehr Arbeit. Es hat jedoch den Vorteil, dass einige zusätzliche Anforderungen damit überprüft werden können. Dazu zählt insbesondere die Überprüfung der Verwendung eines API-Schlüssels und ob beim Veröffentlichen Abhängigkeiten im Ziel vorhanden sind.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.
  • Richten Sie eine Dateifreigabe als Testrepository ein.Set up a file share as the test repository. Die Einrichtung ist einfach, aber da es sich dabei um eine Dateifreigabe handelt, werden die oben aufgeführten Überprüfungen nicht ausgeführt.This is easy to set up, but since it's a file share, the validations noted above will not take place. Ein möglicher Vorteil in diesem Fall ist, dass die Dateifreigabe den benötigten API-Schlüssel nicht überprüft, sodass Sie denselben Schlüssel verwenden können, den Sie auch bei der Veröffentlichung im PowerShell-Katalog verwenden würden.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.

Definieren Sie bei all diesen Lösungen mithilfe von Register-PSRepository ein neues Repository, das Sie im -Repository-Parameter für Publish-Module verwenden.With any of these solutions, use Register-PSRepository to define a new repository, which you use in the -Repository parameter for Publish-Module.

Ein weiterer Punkt beim Testen von Veröffentlichungen: Ein Paket, das Sie im PowerShell-Katalog veröffentlichen, kann nicht ohne die Hilfe des Betriebsteams wieder gelöscht werden. Dieses muss bestätigen, dass kein anderes Element von dem Paket abhängig ist, das Sie veröffentlichen möchten.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. Aus diesem Grund unterstützen wir den PowerShell-Katalog nicht als Testziel und werden jeden Herausgeber kontaktieren, der dies tut.For that reason, we don't support the PowerShell Gallery as a testing target, and will contact any publisher who does so.

Verwenden von PowerShell für die VeröffentlichungUse PowerShellGet to publish

Herausgebern wird beim Arbeiten mit dem PowerShell-Katalog dringend die Verwendung der Cmdlets Publish-Module und Publish-Script empfohlen.It's strongly recommended that publishers use the Publish-Module and Publish-Script cmdlets when working with the PowerShell Gallery. PowerShellGet wurde entwickelt, damit Sie sich nicht alle wichtigen Informationen zur Installation aus dem und Veröffentlichung im PowerShell-Katalog merken müssen.PowerShellGet was created to help you avoid remembering important details about installing from and publishing to the PowerShell Gallery. Gelegentlich nutzen Herausgeber PowerShellGet nicht und verwenden den NuGet-Client oder auch PackageManagement-Cmdlets anstelle von Publish-Module.On occasion, publishers have chosen to skip PowerShellGet and use the NuGet client, or PackageManagement cmdlets, instead of Publish-Module. Es gibt viele Informationen, die leicht übersehen werden, wodurch eine Vielzahl von Supportanfragen aufkommt.There are a number of details that are easily missed, which results in a variety of support requests.

Wenn es einen Grund dafür gibt, dass Sie Publish-Module oder Publish-Script nicht verwenden können, informieren Sie uns darüber.If there's a reason that you can't use Publish-Module or Publish-Script, please let us know. Öffnen Sie ein Issue im GitHub-Repository für PowerShellGet, und geben Sie an, warum Sie sich für NuGet oder PackageManagement entschieden haben.File an issue in the PowerShellGet GitHub repo, and provide the details that cause you to choose NuGet or PackageManagement.

Als erfolgreichster Ansatz für das Veröffentlichen von Paketen im PowerShell-Katalog hat sich der folgende bewährt:The most successful approach we have found for packages published to the PowerShell Gallery is this:

  • Führen Sie die Erstentwicklung auf einer Open-Source-Projektwebsite durch.Do initial development in an open-source project site. Das PowerShell-Team verwendet GitHub.The PowerShell Team uses GitHub.
  • Nutzen Sie das Feedback von Testern sowie PowerShell Script Analyzer, um den Code in einen stabilen Zustand zu überführen.Use feedback from reviewers and Powershell Script Analyzer to get the code to stable state.
  • Schließen Sie eine Dokumentation ein, damit andere Benutzer wissen, wie Ihr Code verwendet wird.Include documentation, so others know how to use your work.
  • Testen Sie die Veröffentlichung, indem Sie ein lokales Repository verwenden.Test out the publishing action using a local repository.
  • Veröffentlichen Sie eine stabile oder Alphaversion im PowerShell-Katalog. Schließen Sie in diese Version die Dokumentation und einen Link zu Ihrer Projektwebsite ein.Publish a stable or Alpha release to the PowerShell Gallery, making sure to include the documentation and link to your project site.
  • Sammeln Sie Feedback, und durchlaufen Sie Ihren Code auf der Projektwebsite. Veröffentlichen Sie anschließend stabile Updates im PowerShell-Katalog.Gather feedback and iterate on the code in your project site, then publish stable updates to the PowerShell Gallery.
  • Fügen Sie Ihrem Projekt und Ihrem Modul Beispiele und Pester-Tests hinzu.Add examples and Pester tests in your project and your module.
  • Entscheiden Sie, ob Sie Ihrem Paket eine Codesignatur hinzufügen möchten.Decide if you want to code sign your package.
  • Wenn Sie der Meinung sind, dass das Projekt bereit zur Verwendung in einer Produktionsumgebung ist, veröffentlichen Sie eine 1.0.0-Version im PowerShell-Katalog.When you feel the project is ready to use in a production environment, publish a 1.0.0 version to the PowerShell Gallery.
  • Sammeln Sie weiter Feedback, und durchlaufen Sie Ihren Code anhand der Hinweise und Kommentare von Benutzern.Continue to gather feedback and iterate on your code based on user input.