次の方法で共有

PowerShellGallery 発行ガイドラインとベスト プラクティス

この記事では、PowerShell ギャラリーでマニフェスト データを処理する方法と、多数の PowerShell ギャラリー ユーザーからのフィードバックに基づいて、PowerShell ギャラリーに発行されたパッケージが広く採用され、ユーザーに高い価値を提供するために Microsoft チームが使用する推奨手順について説明します。 これらのガイドラインに従って公開されたパッケージは、インストールされ、信頼され、より多くのユーザーを引き付ける可能性が高くなります。

以下に、優れた PowerShell ギャラリー パッケージの条件、最も重要なオプションのマニフェスト設定、初期レビュー担当者と Powershell Script Analyzer からのフィードバックによるコードの改善、モジュールのバージョン管理、ドキュメント、テスト、共有したものの使用方法の例に関するガイドラインを示します。 このドキュメントの多くは、 高品質の DSC リソース モジュールを発行するためのガイドラインに従っています。

PowerShell ギャラリーにパッケージを発行する仕組みについては、「 パッケージの作成と発行」を参照してください。

これらのガイドラインに関するフィードバックをお待ちしております。 フィードバックがある場合は、 GitHub ドキュメント リポジトリで問題を開いてください。

パッケージの発行に関するベスト プラクティス

次のベスト プラクティスは、PowerShell ギャラリー項目のユーザーが重要と言うことであり、名目上の優先順位で一覧表示されます。 これらのガイドラインに従うパッケージは、他のユーザーがダウンロードして採用する可能性がはるかに高くなります。

  • PSScriptAnalyzer を使用する
  • ドキュメントと例を含める
  • フィードバックに応答する
  • スクリプトではなくモジュールを提供する
  • プロジェクト サイトへのリンクを指定する
  • 互換性のある PSEdition とプラットフォームを使用してパッケージにタグを付け
  • モジュールにテストを含める
  • ライセンス条項を含める、またはリンクする
  • コードに署名する
  • バージョン管理に関する SemVer ガイドラインに従う
  • 共通の PowerShell ギャラリー タグに記載されているように、共通タグを使用する
  • ローカル リポジトリを使用して発行をテストする
  • PowerShellGet を使用して発行する

これらのそれぞれについて、以下のセクションで簡単に説明します。

PSScriptAnalyzer を使用する

PSScriptAnalyzer は、PowerShell コードで動作する無料の静的コード分析ツールです。 PSScriptAnalyzer は、PowerShell コードで見られる最も一般的な問題を特定し、多くの場合、問題の修正方法に関する推奨事項を示します。 このツールは使いやすく、問題をエラー (重大、対処する必要があります)、警告 (確認する必要があり、対処する必要があります)、情報 (ベスト プラクティスを確認する価値がある) として分類します。 PowerShell ギャラリーに発行されたすべてのパッケージは PSScriptAnalyzer を使用してスキャンされ、エラーは所有者に報告され、対処する必要があります。

ベストプラクティスは、-Recurseと-Severity警告を付けてInvoke-ScriptAnalyzerを実行することです。

結果を確認し、次のことを確認します。

  • すべてのエラーは、ドキュメントで修正または対処されます。
  • すべての警告が確認され、該当する場合に対処されます。

PowerShell ギャラリーからパッケージをダウンロードするユーザーは、 PSScriptAnalyzer を実行し、すべてのエラーと警告を評価することを強くお勧めします。 ユーザーは、 PSScriptAnalyzer によって報告されたエラーがあることを確認した場合、パッケージ所有者に連絡する可能性が非常に高いです。 パッケージがエラーとしてフラグ付けされたコードを保持する説得力のある理由がある場合は、ドキュメントにその情報を追加して、同じ質問に何度も答える必要がないようにします。

ドキュメントと例を含める

ドキュメントと例は、ユーザーが共有コードを利用できるようにするための最良の方法です。

ドキュメントは、PowerShell ギャラリーに発行されたパッケージに含めるのに最も役立ちます。 ユーザーは通常、ドキュメントなしでパッケージをバイパスします。代わりに、コードを読んでパッケージの内容と使用方法を理解します。 PowerShell パッケージでドキュメントを提供する方法には、次のようないくつかの記事があります。

  • ヘルプを提供するためのガイドラインについては、「 コマンドレット ヘルプの書き方」を参照してください。
  • コマンドレット ヘルプの作成。これは、PowerShell スクリプト、関数、またはコマンドレットに最適なアプローチです。 コマンドレット ヘルプの作成方法については、「 コマンドレット ヘルプの記述方法」を参照してください。 スクリプト内にヘルプを追加するには、「 コメントベースのヘルプについて」を参照してください。
  • 多くのモジュールには、MarkDown ファイルなどのテキスト形式のドキュメントも含まれています。 これは、GitHub にプロジェクト サイトがあり、Markdown が頻繁に使用される形式である場合に特に役立ちます。 ベストプラクティスは、 GitHub フレーバーの Markdown を使用することです。

例では、パッケージの使用方法をユーザーに示します。 多くの開発者は、ドキュメントの前に例を見て、何かを使用する方法を理解していると言うでしょう。 最適な種類の例では、基本的な使用方法に加えて、シミュレートされた現実的なユース ケースが示され、コードは適切にコメントされています。 PowerShell ギャラリーに発行されるモジュールの例は、モジュール ルートの下の Examples フォルダーにある必要があります。

例の適切なパターンは、Examples\RegistryResource フォルダーの下の PSDscResource モジュールにあります。 各ファイルの上部には、デモンストレーション対象を文書化する簡単な説明を含む 4 つのサンプル ユース ケースがあります。

依存関係の管理

モジュール マニフェストで、モジュールが依存しているモジュールを指定することが重要です。 これにより、エンド ユーザーは、依存関係を持つ適切なバージョンのモジュールのインストールについて心配する必要はありません。 依存モジュールを指定するには、モジュール マニフェストで必要なモジュール フィールドを使用する必要があります。 これにより、モジュールが既に読み込まれていない限り、モジュールをインポートする前に、一覧表示されているモジュールがグローバル環境に読み込まれます。 たとえば、一部のモジュールは別のモジュールによって既に読み込まれている可能性があります。 また、ModuleVersion フィールドではなく RequiredVersion フィールドを使用して、読み込む特定のバージョンを指定することもできます。 ModuleVersion を使用すると、指定されたバージョンの最小値で利用可能な最新バージョンが読み込まれます。 RequiredVersion フィールドを使用しない場合、特定のバージョンを指定するには、必要なモジュールのバージョン更新を監視することが重要です。 モジュールのユーザー エクスペリエンスに影響を与える可能性がある重大な変更に注意することが特に重要です。

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"})

フィードバックに応答する

フィードバックに適切に応答するパッケージ所有者は、コミュニティから高い評価を受けています。 建設的なフィードバックを提供するユーザーは、パッケージの改善に十分な関心を持つため、対応することが重要です。

PowerShell ギャラリーには、次の 1 つのフィードバック方法があります。

  • 所有者に問い合わせる: これにより、ユーザーはパッケージ所有者に電子メールを送信できます。 パッケージ所有者は、PowerShell ギャラリー パッケージで使用されるメール アドレスを監視し、発生した問題に対応することが重要です。 この方法の欠点の 1 つは、ユーザーと所有者だけが通信を表示するため、所有者が同じ質問に何度も答える必要があることです。

フィードバックに建設的に応答する所有者は、コミュニティから高く評価されています。 レポートの営業案件を使用して、詳細情報を要求します。 必要に応じて、回避策を提供するか、更新プログラムによって問題が修正されるかどうかを特定します。

これらの通信チャネルのいずれかから不適切な動作が見られる場合は、PowerShell ギャラリーの Report Abuse 機能を使用してギャラリー管理者に問い合わせてください。

モジュールとスクリプト

スクリプトを他のユーザーと共有することは素晴らしいことです。また、他のユーザーに問題を解決する方法の例を提供します。 問題は、PowerShell ギャラリー内のスクリプトは、個別のドキュメント、例、テストがない単一のファイルであるということです。

PowerShell モジュールには、複数のフォルダーとファイルをパッケージに含めるフォルダー構造があります。 モジュール構造を使用すると、ベスト プラクティスとしてリストされている他のパッケージ (コマンドレットのヘルプ、ドキュメント、例、テスト) を含めることができます。 最大の欠点は、モジュール内のスクリプトを公開して関数として使用する必要があることです。 モジュールの作成方法については、「 Windows PowerShell モジュールの作成」を参照してください。

スクリプトを使用すると、特に DSC 構成を使用して、ユーザーのエクスペリエンスが向上する場合があります。 DSC 構成のベスト プラクティスは、ドキュメント、例、テストを含む付属のモジュールを含むスクリプトとして構成を発行することです。 スクリプトは、 RequiredModules = @(Name of the Module)を使用して付随するモジュールを一覧表示します。 この方法は、任意のスクリプトで使用できます。

他のベスト プラクティスに従うスタンドアロン スクリプトは、他のユーザーに真の価値を提供します。 PowerShell ギャラリーにスクリプトを発行する場合は、コメントベースのドキュメントとプロジェクト サイトへのリンクを提供することを強くお勧めします。

プロジェクト サイトは、発行元が PowerShell ギャラリー パッケージのユーザーと直接やり取りできる場所です。 ユーザーは、パッケージに関する情報をより簡単に取得できるため、これを提供するパッケージを優先します。 PowerShell ギャラリーの多くのパッケージは GitHub で開発されており、他のパッケージは専用の Web プレゼンスを持つ組織によって提供されています。 これらはそれぞれプロジェクト サイトと見なすことができます。

リンクの追加は、次のようにマニフェストの PSData セクションに ProjectURI を含めることで行われます。

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

ProjectURI が提供されると、PowerShell ギャラリーには、パッケージ ページの左側にあるプロジェクト サイトへのリンクが含まれます。

互換性のある PSEdition とプラットフォームを使用してパッケージにタグを付け

次のタグを使用して、環境で適切に動作するパッケージをユーザーに示します。

  • PSEdition_Desktop: Windows PowerShell と互換性のあるパッケージ
  • PSEdition_Core: PowerShell 6 以降と互換性のあるパッケージ
  • Windows: Windows オペレーティング システムと互換性のあるパッケージ
  • Linux: Linux オペレーティング システムと互換性のあるパッケージ
  • MacOS: Mac オペレーティング システムと互換性のあるパッケージ

互換性のあるプラットフォームでパッケージにタグを付けることで、検索結果の左側のウィンドウにあるギャラリー検索フィルターにパッケージが含まれます。 GitHub でパッケージをホストしている場合、パッケージにタグを付けるときに、PowerShell ギャラリー互換性シールドの互換性シールドの例を利用することもできます。

テストを含める

テストをオープンソース コードで含めるのは、ユーザーにとって重要です。検証内容に関する保証が提供され、コードのしくみに関する情報が提供されるためです。 また、ユーザーが自分の環境に合わせてコードを変更した場合に、元の機能を中断しないようにすることもできます。

テストは、PowerShell 専用に設計された Pester テスト フレームワークを利用するように記述することを強くお勧めします。 Pester は GitHub、 PowerShell ギャラリーで入手でき、Windows 10、Windows Server 2016、WMF 5.0、WMF 5.1 に同梱されています。

GitHub の Pester プロジェクト サイトには、開始からベスト プラクティスまで、Pester テストの作成に関する優れたドキュメントが含まれています。

テスト カバレッジのターゲットは、 高品質リソース モジュールのドキュメントで示されており、70% の単体テスト コード カバレッジが推奨されます。

PowerShell ギャラリーに発行されるすべてのパッケージは、ライセンス条項を指定するか、別紙 A の使用条件に含まれるライセンスに拘束される必要があります。別のライセンスを指定する最善の方法は、PSData の LicenseURI を使用してライセンスへのリンクを提供することです。 詳細については、「 パッケージ マニフェストとギャラリー 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'

コードに署名する

コード署名により、ユーザーはパッケージを発行したユーザーに対して最高レベルの保証が提供され、取得したコードのコピーは発行元がリリースしたものになります。 コード署名全般の詳細については、「 コード署名の概要」を参照してください。 PowerShell では、次の 2 つの主要な方法を使用したコード署名の検証がサポートされています。

  • スクリプト ファイルの署名
  • モジュールへのカタログ署名

PowerShell ファイルへの署名は、実行されるコードが信頼できるソースによって生成され、変更されていないことを確認するための確立されたアプローチです。 PowerShell スクリプト ファイルに署名する方法の詳細については、「 署名について」 の記事を参照してください。 概要では、スクリプトの読み込み時に PowerShell が検証する任意の .PS1 ファイルに署名を追加できます。 PowerShell は、署名されたスクリプトの使用を保証するために、 実行ポリシー コマンドレットを使用して制限できます。

カタログ署名モジュールは、バージョン 5.1 で PowerShell に追加された機能です。 モジュールに署名する方法については、「 カタログ コマンドレット」 の記事を参照してください。 概要では、カタログ署名を行うには、モジュール内のすべてのファイルのハッシュ値を含むカタログ ファイルを作成し、そのファイルに署名します。

PowerShellGetPublish-Module、Install-Module、および Update-Module コマンドレットは、署名が有効であることを確認し、各パッケージのハッシュ値がカタログ内の値と一致することを確認します。 Save-Module は署名を検証しません。 以前のバージョンのモジュールがシステムにインストールされている場合、 Install-Module 新しいバージョンの署名機関が以前にインストールされたものと一致することを確認します。 Install-Module パッケージがカタログ署名されていない場合は、 Update-Module.PSD1 ファイルの署名を使用します。 カタログ署名は機能しますが、署名スクリプト ファイルは置き換えられません。 PowerShell では、モジュールの読み込み時にカタログ署名が検証されません。

バージョン管理に関する SemVer ガイドラインに従う

SemVer は、変更を簡単に解釈できるようにバージョンを構造化および変更する方法を記述するパブリック コンベンションです。 パッケージのバージョンは、マニフェスト データに含める必要があります。

  • バージョンは、 0.1.1 や 4.11.192 のように、ピリオドで区切られた 3 つの数値ブロックとして構成する必要があります。
  • 0で始まるバージョンは、パッケージがまだ本番環境に対応していないことを示し、最初の番号は、使用される番号が唯一の場合にのみ0で始まる必要があります。
  • 最初の数字 (1.9.9999 から 2.0.0) の変更は、バージョン間の主要な変更と重大な変更を示します。
  • 2 番目の数字 (1.1 から 1.2) への変更は、モジュールへの新しいコマンドレットの追加など、機能レベルの変更を示します。
  • 3 番目の数値への変更は、新しいパラメーター、更新されたサンプル、新しいテストなど、重大ではない変更を示します。
  • バージョンを一覧表示する場合、PowerShell はバージョンを文字列として並べ替えるため、 1.01.0 は 1.001.0 より大きいものとして扱われます。

PowerShell は SemVer が公開される前に作成されているため、SemVer のすべての要素 (具体的にはサポートされていません) が提供されます。

  • バージョン番号のプレリリース文字列はサポートされていません。 これは、発行元がバージョン 1.0.0を提供した後、新しいメジャー バージョンのプレビュー リリースを配信する場合に便利です。 これは、PowerShell ギャラリーと PowerShellGet コマンドレットの将来のリリースでサポートされる予定です。
  • PowerShell と PowerShell ギャラリーでは、1、2、4 セグメントのバージョン文字列を使用できます。 初期のモジュールの多くはガイドラインに従っておらず、Microsoft の製品リリースには、ビルド情報が 4 番目の数字ブロック ( 5.1.14393.1066 など) として含まれています。 バージョン管理の観点からは、これらの違いは無視されます。

ローカル リポジトリを使用してテストする

PowerShell ギャラリーは、発行プロセスをテストするためのターゲットとして設計されていません。 PowerShell ギャラリーに発行するエンド ツー エンドのプロセスをテストする最善の方法は、独自のローカル リポジトリを設定して使用することです。 これは、次のようないくつかの方法で実行できます。

  • GitHub の PS Private Gallery プロジェクト を使用して、ローカルの PowerShell ギャラリー インスタンスを設定します。 このプレビュー プロジェクトは、制御してテストに使用できる PowerShell ギャラリーのインスタンスを設定するのに役立ちます。
  • 内部 Nuget リポジトリを設定します。 セットアップにはより多くの作業が必要になりますが、いくつかの要件を検証する利点があります。特に、API キーの使用を検証し、公開時に依存関係がターゲットに存在するかどうかが確認されます。
  • ファイル共有をテスト リポジトリとして設定します。 これは簡単に設定できますが、ファイル共有であるため、上記の検証は行われません。 この場合の潜在的な利点の 1 つは、ファイル共有が必要な API キーをチェックしないため、PowerShell ギャラリーへの発行に使用するのと同じキーを使用できることです。

これらのソリューションのいずれかで、Register-PSRepository を使用して新しいリポジトリを定義し、Publish-Moduleの -Repository パラメーターで使用します。

テスト発行に関するもう 1 つのポイント: PowerShell ギャラリーに発行するすべてのパッケージは、発行するパッケージに依存しないことを確認する運用チームの支援なしでは削除できません。 そのため、テスト ターゲットとして PowerShell ギャラリーはサポートされておらず、その発行元に連絡します。

PowerShellGet を使用して発行する

発行元は、PowerShell ギャラリーを操作するときに、 Publish-Module コマンドレットと Publish-Script コマンドレットを使用することを強くお勧めします。 PowerShellGet は、PowerShell ギャラリーからのインストールと PowerShell ギャラリーへの発行に関する重要な詳細を覚えないようにするために作成されました。 場合によっては、発行元が PowerShellGet をスキップして、Publish-Module の代わりに NuGet クライアントまたは PackageManagement コマンドレットを使用することを選択しています。 見逃しやすい詳細が多数あり、さまざまなサポート要求が発生します。

Publish-ModuleやPublish-Scriptが使えない理由がある場合は、お申し付けください。 PowerShellGet GitHub リポジトリで問題を報告し、NuGet または PackageManagement を選択する原因となる詳細を指定します。

PowerShell ギャラリーに発行されたパッケージに対して見つかった最も成功したアプローチは次のとおりです。

  • オープンソース プロジェクト サイトで初期開発を行います。 PowerShell チームは GitHub を使用します。
  • レビュー担当者と PowerShell スクリプト アナライザー からのフィードバックを使用して、コードを安定した状態にします。
  • 他のユーザーが作業の使い方を知ることができるように、ドキュメントを含めます。
  • ローカル リポジトリを使用して発行アクションをテストします。
  • PowerShell ギャラリーに安定版またはアルファ 版のリリースを発行し、ドキュメントとプロジェクト サイトへのリンクを必ず含めます。
  • フィードバックを収集し、プロジェクト サイトのコードを反復処理した後、PowerShell ギャラリーに安定した更新プログラムを発行します。
  • プロジェクトとモジュールに例と Pester テストを追加します。
  • パッケージにコード署名するかどうかを決定します。
  • プロジェクトを運用環境で使用する準備ができたら、 1.0.0 バージョンを PowerShell ギャラリーに発行します。
  • 引き続きフィードバックを収集し、ユーザー入力に基づいてコードを反復処理します。
  • Last updated on