PowerShellGallery 発行ガイドラインとベスト プラクティス
この記事では、PowerShell ギャラリーでマニフェスト データを処理する方法と、多数の PowerShell ギャラリー ユーザーからのフィードバックに基づいて、PowerShell ギャラリーに発行されたパッケージが広く採用され、ユーザーに高い価値を提供するために Microsoft チームが使用する推奨手順について説明します。 これらのガイドラインに従って公開されたパッケージは、インストールされ、信頼され、より多くのユーザーを引き付ける可能性が高くなります。
次に示すガイドラインは、優れた PowerShell ギャラリー パッケージを作成する方法、オプションのマニフェスト設定が最も重要なもの、初期レビュー担当者からのフィードバックを使用してコードを改善し、Powershell Script Analyzer
PowerShell ギャラリーへのパッケージの発行のしくみについては、「パッケージの作成と発行」を参照してください。
これらのガイドラインに関するフィードバックをお待ちしております。 フィードバックがある場合は、GitHub ドキュメント リポジトリで問題を開いてください。
パッケージの発行に関するベスト プラクティス
次のベスト プラクティスは、PowerShell ギャラリー項目のユーザーが重要と言うことであり、名目上の優先順位で一覧表示されます。 これらのガイドラインに従うパッケージは、他のユーザーがダウンロードして採用する可能性がはるかに高くなります。
- PSScriptAnalyzer を使用する
- ドキュメントと例を含める
- フィードバックに応答する
- スクリプトではなくモジュールを提供する
- プロジェクト サイトへのリンクを指定する
- 互換性のある PSEdition とプラットフォームを使用してパッケージにタグを付け
- モジュールにテストを含める
- ライセンス条項を含める、またはリンクする
- コードに署名する
- バージョン管理 SemVer ガイドラインに従う
- 共通の PowerShell ギャラリー タグに記載されているように、共通タグを使用する
- ローカル リポジトリを使用して発行をテストする
- PowerShellGet を使用して発行する
これらのそれぞれについて、以下のセクションで簡単に説明します。
PSScriptAnalyzer を使用する
PSScriptAnalyzer は、PowerShell コードで動作する無料の静的コード分析ツールです。 PSScriptAnalyzer
ベスト プラクティスは、-Recurse と -Severity 警告を使用して Invoke-ScriptAnalyzer を実行する方法です。
結果を確認し、次のことを確認します。
- すべてのエラーは、ドキュメントで修正または対処されます。
- すべての警告が確認され、該当する場合に対処されます。
PowerShell ギャラリーからパッケージをダウンロードするユーザーは、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 の
テスト カバレッジのターゲットは、高品質リソース モジュールのドキュメントに記載されており、70% 単体テスト コード カバレッジが推奨されています。
ライセンス条項を含める、またはリンクする
PowerShell ギャラリーに発行されるすべてのパッケージは、ライセンス条項を指定するか、
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 スクリプト ファイルに署名する方法の詳細については、 の署名に関する .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で始まる必要があります (これが使用されている唯一の番号の場合)。- 最初の番号 (
2.0.0に1.9.9999) の変更は、バージョン間の大きな変更と重大な変更を示します。 - 2 番目の数値 (
1.2に1.1) への変更は、モジュールに新しいコマンドレットを追加するなど、機能レベルの変更を示します。 - 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 プライベート ギャラリー プロジェクト を使用して、ローカルの 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 や Publish-Scriptを使用できない理由がある場合は、お知らせください。
推奨されるワークフロー
PowerShell ギャラリーに発行されたパッケージに対して見つかった最も成功したアプローチは次のとおりです。
- オープンソース プロジェクト サイトで初期開発を行います。 PowerShell チームは GitHub を使用します。
- レビュー担当者からのフィードバックと PowerShell Script Analyzer
使用して、コードを安定した状態にします。 - 他のユーザーが作業の使い方を知ることができるように、ドキュメントを含めます。
- ローカル リポジトリを使用して発行アクションをテストします。
- PowerShell ギャラリーに安定版またはアルファ 版のリリースを発行し、ドキュメントとプロジェクト サイトへのリンクを必ず含めます。
- フィードバックを収集し、プロジェクト サイトのコードを反復処理した後、PowerShell ギャラリーに安定した更新プログラムを発行します。
- プロジェクトとモジュールに例と Pester テストを追加します。
- パッケージにコード署名するかどうかを決定します。
- 運用環境でプロジェクトを使用する準備ができたと感じる場合は、
1.0.0バージョンを PowerShell ギャラリーに発行します。 - 引き続きフィードバックを収集し、ユーザー入力に基づいてコードを反復処理します。
PowerShell Gallery
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示