Freigeben über

PowerShellGallery-Veröffentlichungsrichtlinien und bewährte Methoden

  • Artikel

In diesem Artikel werden die empfohlenen Schritte beschrieben, die von Microsoft Teams verwendet werden, um sicherzustellen, dass die im PowerShell-Katalog veröffentlichten Pakete weit verbreitet sind und Benutzern einen hohen Nutzen bieten, basierend auf der Art und Weise, wie der PowerShell-Katalog Manifestdaten verarbeitet und feedback von großen Anzahl von PowerShell-Katalogbenutzern. Pakete, die nach diesen Richtlinien veröffentlicht werden, werden wahrscheinlicher installiert, vertrauenswürdiger und mehr Benutzer anziehen.

Im Folgenden finden Sie Richtlinien für das, was ein gutes PowerShell-Katalogpaket macht, welche optionalen Manifesteinstellungen am wichtigsten sind, verbessern Ihren Code mit Feedback von anfänglichen Prüfern und Powershell Script Analyzer, Versionsverwaltung Ihres Moduls, Dokumentation, Tests und Beispiele für die Verwendung ihrer freigegebenen Elemente. Ein Großteil dieser Dokumentation folgt den Richtlinien für die Veröffentlichung High Quality DSC Resource Modules.

Informationen zum Veröffentlichen eines Pakets im PowerShell-Katalog finden Sie unter Erstellen und Veröffentlichen eines Pakets.

Feedback zu diesen Richtlinien wird begrüßt. Wenn Sie Feedback haben, öffnen Sie bitte Probleme in unserem GitHub-Dokumentations-Repository.

Bewährte Methoden zum Veröffentlichen von Paketen

Die folgenden bewährten Methoden sind, was die Benutzer von PowerShell-Katalogelementen sagen, ist wichtig und werden in nominaler Prioritätsreihenfolge aufgeführt. Pakete, die diesen Richtlinien folgen, sind viel wahrscheinlicher, dass sie von anderen heruntergeladen und übernommen werden.

  • Verwenden von PSScriptAnalyzer
  • Dokumentation und Beispiele einschließen
  • Reaktion auf Feedback
  • Bereitstellen von Modulen anstelle von Skripts
  • Bereitstellen von Links zu einer Projektwebsite
  • Kennzeichnen Ihres Pakets mit den kompatiblen PSEdition(n) und Plattformen
  • Einschließen von Tests in Ihre Module
  • Einschließen und/oder Verknüpfen mit Lizenzbedingungen
  • Signieren des Codes
  • Befolgen SemVer- Richtlinien für die Versionsverwaltung
  • Verwenden allgemeiner Tags, wie in allgemeinen PowerShell-Katalogtags dokumentiert
  • Testen der Veröffentlichung mithilfe eines lokalen Repositorys
  • Verwenden von PowerShellGet zum Veröffentlichen

Jede dieser Elemente wird in den folgenden Abschnitten kurz behandelt.

Verwenden von PSScriptAnalyzer

PSScriptAnalyzer ist ein kostenloses statisches Codeanalysetool, das auf PowerShell-Code funktioniert. PSScriptAnalyzer identifiziert die am häufigsten auftretenden Probleme im PowerShell-Code und häufig eine Empfehlung zur Behebung des Problems. Das Tool ist einfach zu verwenden und kategorisiert die Probleme als Fehler (schwerwiegend, muss behoben werden), Warnung (muss überprüft werden und sollte behoben werden) und Informationen (wert, um bewährte Methoden zu überprüfen). Alle im PowerShell-Katalog veröffentlichten Pakete werden mithilfe PSScriptAnalyzergescannt, und alle Fehler werden dem Besitzer gemeldet und müssen behoben werden.

Es wird empfohlen, Invoke-ScriptAnalyzer mit -Recurse und -Severity Warnung auszuführen.

Überprüfen Sie die Ergebnisse, und stellen Sie sicher, dass:

  • Alle Fehler werden in Ihrer Dokumentation korrigiert oder behoben.
  • Alle Warnungen werden überprüft und gegebenenfalls behoben.

Benutzer, die Pakete aus dem PowerShell-Katalog herunterladen, werden dringend empfohlen, PSScriptAnalyzer auszuführen und alle Fehler und Warnungen auszuwerten. Benutzer wenden sich sehr wahrscheinlich an Paketbesitzer, wenn sie sehen, dass ein Fehler von PSScriptAnalyzergemeldet wird. Wenn es einen überzeugenden Grund für Ihr Paket gibt, Code beizubehalten, der als Fehler gekennzeichnet ist, fügen Sie diese Informationen zu Ihrer Dokumentation hinzu, um zu vermeiden, dass Sie dieselbe Frage mehrmals beantworten müssen.

Dokumentation und Beispiele einschließen

Dokumentation und Beispiele sind die beste Möglichkeit, um sicherzustellen, dass Benutzer jeden freigegebenen Code nutzen können.

Die Dokumentation ist das hilfreichste, was Sie in Pakete einschließen möchten, die im PowerShell-Katalog veröffentlicht wurden. Benutzer umgehen in der Regel Pakete ohne Dokumentation, da die Alternative darin besteht, den Code zu lesen, um zu verstehen, was das Paket ist und wie es verwendet wird. Es stehen mehrere Artikel zur Bereitstellung von Dokumentationen mit PowerShell-Paketen zur Verfügung, darunter:

  • Richtlinien für die Bereitstellung von Hilfe sind in Hilfe zum Schreiben von Cmdlet-Hilfe.
  • Erstellen von Cmdlet-Hilfen, die für jedes PowerShell-Skript, jede Funktion oder ein Cmdlet am besten geeignet ist. Informationen zum Erstellen von Cmdlet-Hilfen beginnen Sie mit Hilfe zum Schreiben von Cmdlets. Informationen zum Hinzufügen von Hilfe in einem Skript finden Sie unter Informationen zur kommentarbasierten Hilfe.
  • Viele Module enthalten auch Dokumentationen im Textformat, z. B. MarkDown-Dateien. Dies kann besonders hilfreich sein, wenn es eine Projektwebsite in GitHub gibt, bei der Markdown ein stark verwendetes Format ist. Die bewährte Methode besteht darin, GitHub-aromatisierte Markdown-zu verwenden.

Beispiele zeigen Benutzern, wie das Paket verwendet werden soll. Viele Entwickler werden sagen, dass sie sich Beispiele vor der Dokumentation ansehen, um zu verstehen, wie sie etwas verwenden. Die besten Beispiele zeigen die grundlegende Verwendung sowie einen simulierten realistischen Anwendungsfall, und der Code ist gut kommentiert. Beispiele für Module, die im PowerShell-Katalog veröffentlicht wurden, sollten sich im Ordner "Beispiele" unter dem Modulstamm befinden.

Ein gutes Muster für Beispiele finden Sie im PSDscResource-Modul unter dem Ordner Examples\RegistryResource. Es gibt vier Beispielanwendungsfälle mit einer kurzen Beschreibung am Anfang jeder Datei, die dokumentiert, was gezeigt wird.

Verwalten von Abhängigkeiten

Es ist wichtig, Module anzugeben, von denen Ihr Modul im Modulmanifest abhängig ist. Dies ermöglicht es dem Endbenutzer, sich keine Gedanken über die Installation der richtigen Versionen von Modulen zu machen, von denen Ihre abhängig sind. Um abhängige Module anzugeben, sollten Sie das erforderliche Modulfeld im Modulmanifest verwenden. Dadurch werden alle aufgelisteten Module vor dem Importieren des Moduls in die globale Umgebung geladen, es sei denn, sie wurden bereits geladen. Beispielsweise können einige Module bereits von einem anderen Modul geladen werden. Es ist auch möglich, eine bestimmte Version anzugeben, die mithilfe des felds RequiredVersion anstelle des ModuleVersion--Felds geladen werden soll. Wenn Sie ModuleVersion-verwenden, wird die neueste Version geladen, die mindestens mit der angegebenen Version verfügbar ist. Wenn Sie das Feld RequiredVersion nicht verwenden, um eine bestimmte Version anzugeben, ist es wichtig, Versionsupdates für das erforderliche Modul zu überwachen. Es ist besonders wichtig, sich über wichtige Änderungen zu informieren, die sich auf die Benutzererfahrung mit Ihrem Modul auswirken könnten.

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 auf Feedback

Paketbesitzer, die ordnungsgemäß auf Feedback reagieren, werden von der Community sehr geschätzt. Benutzer, die konstruktives Feedback geben, sind wichtig, um darauf zu reagieren, da sie an dem Paket interessiert sind, um zu versuchen, es zu verbessern.

Im PowerShell-Katalog ist eine Feedbackmethode verfügbar:

  • Kontaktbesitzer: Dadurch kann ein Benutzer eine E-Mail an den Paketbesitzer senden. Als Paketbesitzer ist es wichtig, die E-Mail-Adresse zu überwachen, die mit den PowerShell-Katalogpaketen verwendet wird, und auf Probleme zu reagieren, die ausgelöst werden. Der einzige Nachteil dieser Methode ist, dass nur der Benutzer und der Besitzer die Kommunikation sehen, sodass der Besitzer die gleiche Frage oft beantworten muss.

Besitzer, die konstruktives Feedback beantworten, werden von der Community geschätzt. Verwenden Sie die Möglichkeit im Bericht, weitere Informationen anzufordern. Stellen Sie bei Bedarf eine Problemumgehung bereit, oder identifizieren Sie, ob ein Update ein Problem behebt.

Wenn von einem dieser Kommunikationskanäle unangemessenes Verhalten beobachtet wird, verwenden Sie das Feature "Missbrauch melden" des PowerShell-Katalogs, um sich an die Katalogadministratoren zu wenden.

Module im Vergleich zu Skripts

Das Freigeben eines Skripts für andere Benutzer ist großartig und bietet anderen Beispiele für die Lösung von Problemen, die sie möglicherweise haben. Das Problem besteht darin, dass Skripts im PowerShell-Katalog einzelne Dateien ohne separate Dokumentation, Beispiele und Tests sind.

PowerShell-Module verfügen über eine Ordnerstruktur, mit der mehrere Ordner und Dateien in das Paket eingeschlossen werden können. Die Modulstruktur ermöglicht das Einschließen der anderen Pakete, die wir als bewährte Methoden auflisten: Cmdlet-Hilfe, Dokumentation, Beispiele und Tests. Der größte Nachteil besteht darin, dass ein Skript innerhalb eines Moduls verfügbar gemacht und als Funktion verwendet werden muss. Informationen zum Erstellen eines Moduls finden Sie unter Schreiben eines Windows PowerShell-Moduls.

Es gibt Situationen, in denen ein Skript eine bessere Benutzererfahrung bietet, insbesondere bei DSC-Konfigurationen. Die bewährte Methode für DSC-Konfigurationen besteht darin, die Konfiguration als Skript mit einem begleitenden Modul zu veröffentlichen, das die Dokumente, Beispiele und Tests enthält. Das Skript listet das begleitende Modul mithilfe von RequiredModules = @(Name of the Module)auf. Dieser Ansatz kann mit jedem Skript verwendet werden.

Eigenständige Skripts, die den anderen bewährten Methoden folgen, bieten anderen Benutzern einen echten Mehrwert. Das Bereitstellen von kommentarbasierter Dokumentation und ein Link zu einer Projektwebsite wird beim Veröffentlichen eines Skripts im PowerShell-Katalog dringend empfohlen.

Eine Projektwebsite ist der Ort, an dem ein Herausgeber direkt mit den Benutzern seiner PowerShell-Katalogpakete interagieren kann. Benutzer bevorzugen Pakete, die dies bereitstellen, da es ihnen ermöglicht, Informationen über das Paket einfacher zu erhalten. Viele Pakete im PowerShell-Katalog werden in GitHub entwickelt, andere werden von Organisationen mit einer dedizierten Webpräsenz bereitgestellt. Jede davon kann als Projektwebsite betrachtet werden.

Das Hinzufügen eines Links erfolgt durch Einschließen von ProjectURI im PSData-Abschnitt des Manifests wie folgt:

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

Wenn ein ProjectURI bereitgestellt wird, enthält der PowerShell-Katalog einen Link zur Projektwebsite auf der linken Seite der Paketseite.

Kennzeichnen Ihres Pakets mit den kompatiblen PSEdition(n) und Plattformen

Verwenden Sie die folgenden Tags, um Benutzern zu veranschaulichen, welche Pakete gut mit ihrer Umgebung funktionieren:

  • PSEdition_Desktop: Pakete, die mit Windows PowerShell kompatibel sind
  • PSEdition_Core: Pakete, die mit PowerShell 6 und höher kompatibel sind
  • Windows: Pakete, die mit dem Windows-Betriebssystem kompatibel sind
  • Linux: Pakete, die mit Linux-Betriebssystemen kompatibel sind
  • MacOS: Pakete, die mit dem Mac-Betriebssystem kompatibel sind

Indem Sie Ihr Paket mit den kompatiblen Plattformen kategorisieren, wird es in den Suchfiltern des Katalogs im linken Bereich der Suchergebnisse einbezogen. Wenn Sie Ihr Paket auf GitHub hosten, können Sie auch unsere PowerShell Gallery-KompatibilitätsschildeKompatibilitätsschildnutzen.

Tests einschließen

Das Einschließen von Tests mit Open-Source-Code ist für Benutzer wichtig, da sie ihnen die Sicherheit darüber geben, was Sie überprüfen, und Informationen zur Funktionsweise Ihres Codes bereitstellt. Außerdem können Benutzer sicherstellen, dass sie Ihre ursprünglichen Funktionen nicht unterbrechen, wenn sie Ihren Code an ihre Umgebung anpassen.

Es wird dringend empfohlen, Tests zu schreiben, um das Pester-Testframework zu nutzen, das speziell für PowerShell entwickelt wurde. Pester ist in GitHub-, dem PowerShell-Katalogund in Windows 10, Windows Server 2016, WMF 5.0 und WMF 5.1 enthalten.

Die Pester-Projektwebsite in GitHub enthält eine gute Dokumentation zum Schreiben von Pester-Tests, von den ersten Schritten bis hin zu bewährten Methoden.

Die Ziele für die Testabdeckung werden in der dokumentation High Quality Resource Module, mit empfohlener 70% Komponententestcodeabdeckung, herausgerufen.

Alle im PowerShell-Katalog veröffentlichten Pakete müssen die Lizenzbedingungen angeben oder an die lizenz gebunden sein, die in den Nutzungsbedingungen unter Anlage Aenthalten ist. Der beste Ansatz zum Angeben einer anderen Lizenz besteht darin, mithilfe des LicenseURI- in PSData-einen Link zur Lizenz bereitzustellen. Weitere Informationen finden Sie unter Paketmanifest und Katalog-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 des Codes

Die Codesignierung bietet Benutzern die höchste Zuverlässigkeitsstufe für die Person, die das Paket veröffentlicht hat, und dass die Kopie des codes, den sie erwerben, genau das ist, was der Herausgeber veröffentlicht hat. Weitere Informationen zur Codesignierung im Allgemeinen finden Sie unter Einführung in die Codesignatur. PowerShell unterstützt die Überprüfung der Codesignierung über zwei primäre Ansätze:

  • Signieren von Skriptdateien
  • Katalogsignieren eines Moduls

Das Signieren von PowerShell-Dateien ist ein bewährter Ansatz, um sicherzustellen, dass der ausgeführte Code von einer zuverlässigen Quelle erstellt wurde und nicht geändert wurde. Details zum Signieren von PowerShell-Skriptdateien finden Sie im Artikel "Signieren". In der Übersicht kann einer beliebigen .PS1 Datei eine Signatur hinzugefügt werden, die PowerShell beim Laden des Skripts überprüft. PowerShell kann mithilfe der Ausführungsrichtlinie Cmdlets eingeschränkt werden, um die Verwendung signierter Skripts sicherzustellen.

Katalogsignaturmodule sind ein Feature, das PowerShell in Version 5.1 hinzugefügt wird. Das Signieren eines Moduls wird im Artikel Katalog-Cmdlets behandelt. In der Übersicht erfolgt die Katalogsignierung durch Erstellen einer Katalogdatei, die einen Hashwert für jede Datei im Modul enthält, und anschließend das Signieren dieser Datei.

Die PowerShellGet-Publish-Module, Install-Moduleund Update-Module Cmdlets überprüfen die Signatur, um sicherzustellen, dass sie gültig ist, und vergewissern Sie sich dann, dass der Hashwert für jedes Paket dem entspricht, was sich im Katalog befindet. Save-Module überprüft keine Signatur. Wenn eine frühere Version des Moduls auf dem System installiert ist, wird Install-Module bestätigen, dass die Signaturautorität für die neue Version dem entspricht, was zuvor installiert wurde. Install-Module und Update-Module verwenden die Signatur in einer .PSD1 Datei, wenn das Paket nicht katalogsigniert ist. Die Katalogsignierung funktioniert mit, ersetzt jedoch keine Signaturskriptdateien. PowerShell überprüft Katalogsignaturen nicht zum Ladezeitpunkt des Moduls.

Befolgen von SemVer-Richtlinien für die Versionsverwaltung

SemVer ist eine öffentliche Konvention, die beschreibt, wie eine Version strukturiert und geändert wird, um eine einfache Interpretation von Änderungen zu ermöglichen. Die Version für Ihr Paket muss in die Manifestdaten einbezogen werden.

  • Die Version sollte wie in 0.1.1 oder 4.11.192als drei numerische Blöcke strukturiert werden, die durch Punkte getrennt sind.
  • Versionen, die mit 0 beginnen, geben an, dass das Paket noch nicht produktionsbereit ist, und die erste Zahl sollte nur mit 0 beginnen, wenn dies die einzige verwendete Nummer ist.
  • Änderungen an der ersten Zahl (1.9.9999 in 2.0.0) geben wichtige und grundlegende Änderungen zwischen den Versionen an.
  • Änderungen an der zweiten Zahl (1.1 zu 1.2) geben Änderungen auf Featureebene an, z. B. das Hinzufügen neuer Cmdlets zu einem Modul.
  • Änderungen an der dritten Zahl deuten auf ungebrochene Änderungen hin, z. B. neue Parameter, aktualisierte Beispiele oder neue Tests.
  • Wenn Sie Versionen auflisten, sortiert PowerShell die Versionen als Zeichenfolgen, sodass 1.01.0 als größer als 1.001.0behandelt werden.

PowerShell wurde erstellt, bevor SemVer veröffentlicht wurde. Daher bietet sie Unterstützung für die meisten, aber nicht alle Elemente von SemVer, insbesondere:

  • Es unterstützt keine Vorabversionszeichenfolgen in Versionsnummern. Dies ist nützlich, wenn ein Herausgeber eine Vorschauversion einer neuen Hauptversion bereitstellen möchte, nachdem eine Version 1.0.0bereitgestellt wurde. Dies wird in einer zukünftigen Version des PowerShell-Katalogs und PowerShellGet-Cmdlets unterstützt.
  • PowerShell und der PowerShell-Katalog ermöglichen Versionszeichenfolgen mit 1, 2 und 4 Segmenten. Viele frühe Module befolgten nicht die Richtlinien, und Produktversionen von Microsoft enthalten Buildinformationen als 4. Zahlenblock (z. B. 5.1.14393.1066). Aus Versionsverwaltungssicht werden diese Unterschiede ignoriert.

Testen mithilfe eines lokalen Repositorys

Der PowerShell-Katalog ist kein Ziel zum Testen des Veröffentlichungsprozesses. Die beste Möglichkeit, den End-to-End-Prozess der Veröffentlichung im PowerShell-Katalog zu testen, besteht darin, Ihr eigenes lokales Repository einzurichten und zu verwenden. Dies kann auf verschiedene Arten erfolgen, darunter:

  • Richten Sie eine lokale PowerShell-Kataloginstanz mithilfe des PS Private Gallery-Projekts in GitHub ein. Dieses Vorschauprojekt hilft Ihnen beim Einrichten einer Instanz des PowerShell-Katalogs, die Sie steuern und für Ihre Tests verwenden können.
  • Richten Sie ein internes Nuget-Repositoryein. Dies erfordert mehr Arbeit zum Einrichten, hat aber den Vorteil, einige weitere Anforderungen zu validieren, insbesondere die Überprüfung der Verwendung eines API-Schlüssels und ob Abhängigkeiten beim Veröffentlichen im Ziel vorhanden sind.
  • Richten Sie eine Dateifreigabe als Test-Repository-ein. Dies ist einfach einzurichten, aber da es sich um eine Dateifreigabe handelt, werden die oben genannten Überprüfungen nicht durchgeführt. Ein potenzieller Vorteil in diesem Fall ist, dass die Dateifreigabe nicht den erforderlichen API-Schlüssel überprüft, sodass Sie denselben Schlüssel verwenden können, den Sie zum Veröffentlichen im PowerShell-Katalog verwenden würden.

Verwenden Sie mit einer dieser Lösungen Register-PSRepository, um ein neues Repositoryzu definieren, das Sie im parameter -Repository für Publish-Moduleverwenden.

Ein weiterer Punkt zur Testveröffentlichung: Jedes Paket, das Sie im PowerShell-Katalog veröffentlichen, kann nicht gelöscht werden, ohne Hilfe vom Betriebsteam, der bestätigt, dass nichts von dem Paket abhängig ist, das Sie veröffentlichen möchten. Aus diesem Grund unterstützen wir den PowerShell-Katalog nicht als Testziel und wenden sich an jeden Herausgeber, der dies tut.

Verwenden von PowerShellGet zum Veröffentlichen

Es wird dringend empfohlen, dass Herausgeber beim Arbeiten mit dem PowerShell-Katalog die cmdlets Publish-Module und Publish-Script verwenden. PowerShellGet- wurde erstellt, um wichtige Details zum Installieren und Veröffentlichen im PowerShell-Katalog zu vermeiden. Gelegentlich haben Sich Herausgeber entschieden, PowerShellGet- zu überspringen und den NuGet--Client zu verwenden, oder PackageManagement Cmdlets anstelle von Publish-Module. Es gibt eine Reihe von Details, die leicht übersehen werden, was zu einer Vielzahl von Supportanfragen führt.

Wenn es einen Grund gibt, dass Sie Publish-Module oder Publish-Scriptnicht verwenden können, teilen Sie uns bitte mit. Geben Sie ein Problem im PowerShellGet- GitHub-Repository an, und geben Sie die Details an, die dazu führen, dass Sie NuGet- oder PackageManagement-auswählen.

Der erfolgreichste Ansatz, den wir für Pakete gefunden haben, die im PowerShell-Katalog veröffentlicht wurden, ist dies:

  • Führen Sie die anfängliche Entwicklung auf einer Open-Source-Projektwebsite aus. Das PowerShell-Team verwendet GitHub.
  • Verwenden Sie Feedback von Bearbeitern und PowerShell Script Analyzer, um den Code in stabilen Zustand zu erhalten.
  • Schließen Sie Dokumentation ein, damit andere wissen, wie Sie Ihre Arbeit verwenden können.
  • Testen Sie die Veröffentlichungsaktion mithilfe eines lokalen Repositorys.
  • Veröffentlichen Sie eine stabile oder Alpha-Version im PowerShell-Katalog, und stellen Sie sicher, dass Sie die Dokumentation und den Link zu Ihrer Projektwebsite einschließen.
  • Sammeln Sie Feedback, und durchlaufen Sie den Code auf Ihrer Projektwebsite, und veröffentlichen Sie dann stabile Updates im PowerShell-Katalog.
  • Fügen Sie Beispiele und Pester-Tests in Ihrem Projekt und Ihrem Modul hinzu.
  • Entscheiden Sie, ob Sie ihr Paket codieren möchten.
  • Wenn Sie das Gefühl haben, dass das Projekt in einer Produktionsumgebung verwendet werden kann, veröffentlichen Sie eine 1.0.0 Version im PowerShell-Katalog.
  • Sammeln Sie weiterhin Feedback, und durchlaufen Sie Ihren Code basierend auf der Benutzereingabe.