必要な開発ガイドライン

  • [アーティクル]

コマンドレットを記述するときは、次のガイドラインに従う必要があります。 コマンドレットを設計するためのガイドラインと、コマンドレットコードを記述するためのガイドラインに分けられています。 これらのガイドラインに従っていない場合、コマンドレットは失敗し、コマンドレットを使用するとユーザーのエクスペリエンスが低下する可能性があります。

このトピックの内容

設計ガイドライン

コードのガイドライン

設計ガイドライン

コマンドレットとその他のコマンドレットを使用して一貫したユーザーエクスペリエンスを実現するために、コマンドレットを設計する際には、次のガイドラインに従う必要があります。 状況に当てはまる設計ガイドラインが見つかったら、同様のガイドラインのコードガイドラインを確認してください。

承認された動詞のみを使用する (RD01)

コマンドレットの属性で指定する動詞は、Windows PowerShell によって提供される、認識された動詞のセットからのものである必要があります。 禁止されたシノニムの1つである必要はありません。 次の列挙体で定義されている定数文字列を使用して、コマンドレット動詞を指定します。

承認された動詞名の詳細については、「 コマンドレットの動詞」を参照してください。

ユーザーには、検出可能な一連のコマンドレット名が必要です。 適切な動詞を使用して、ユーザーがコマンドレットの動作を迅速に評価し、システムの機能を簡単に検出できるようにします。 たとえば、次のコマンドラインコマンドは、名前が "start" で始まるシステム上のすべてのコマンドの一覧を取得し get-command start-* ます。 コマンドレットの名詞を使用して、他のコマンドレットとコマンドレットを区別します。 名詞は、操作が実行されるリソースを示します。 操作自体は動詞によって表されます。

コマンドレット名: 使用できない文字 (RD02)

コマンドレットに名前を指定するときは、次の特殊文字は使用しないでください。

文字 名前
# 数値の符号
, コンマ
() かっこ
{} かっこ
[] 角かっこ
& アンパサンド
- ハイフン メモ: ハイフンを使用して、名詞から動詞を区切ることができますが、名詞内または動詞内で使用することはできません。
/ スラッシュ記号
\ 円記号
$ ドル記号
^ キャレット
; セミコロン
: :)
" 二重引用符
' 単一引用符
<> 山かっこ
| 縦棒
? 疑問符
@ アットマーク記号
` バックチック (アクサングラーブ)
* アスタリスク
% パーセント記号
+ プラス記号
= 等号 (=)
~ 否定

使用できないパラメーター名 (RD03)

Windows PowerShell は、すべてのコマンドレットにパラメーターを設定し、特定の状況で追加されるパラメーターを追加します。 独自のコマンドレットを設計する場合、Confirm、Debug、ErrorAction、Erroraction、OutBuffer、Outbuffer、Warnings Action、Warnings Variable、WhatIf、UseTransaction、Verbose の各名前は使用できません。 これらのパラメーターの詳細については、「 共通パラメーター名」を参照してください。

確認要求のサポート (RD04)

システムを変更する操作を実行するコマンドレットについては、確認を要求するために、system.string * メソッドを呼び出す必要があります。また、特殊なケース では、 このメソッドを呼び出します。 (" System ......................................................... ...

これらの呼び出しを行うには、コマンドレット属性のキーワードを設定して、コマンドレットで確認要求をサポートするように指定する必要があり SupportsShouldProcess ます。 この属性の設定の詳細については、「 コマンドレット属性の宣言」を参照してください。

注意

コマンドレットクラスの Cmdlet 属性によって、コマンドレットが システム の呼び出しをサポートしていることが示されている場合、コマンドレットは、system..... . コマンドレット の呼び出しを実行できません。また、コマンドレットは、システムを予期せず変更する可能性があります。

システムを変更する場合は、System... コマンドレット を使用します。 ユーザー設定とパラメーターによって WhatIf 、system.string * メソッドが制御されます。 これに 対して、".. ....................................... このメソッドは、ユーザー設定またはパラメーターによって制御されません WhatIf 。 コマンドレットで、system.string * メソッドを呼び出す場合は、 Force この2つのメソッドの呼び出しをバイパスして操作を続行するパラメーターが必要です。 これは、非対話型のスクリプトやホストでコマンドレットを使用できるようにするために重要です。

コマンドレットがこれらの呼び出しをサポートしている場合、ユーザーはアクションを実際に実行するかどうかを判断できます。 たとえば、 Stop Process コマンドレットは、システム、Winlogon、spoolsv.exe の各プロセスを含む一連の重要なプロセスを停止する前に、system.string * メソッドを呼び出します。

これらのメソッドのサポートの詳細については、「 確認の要求」を参照してください。

対話型セッションの Force パラメーターのサポート (RD05)

コマンドレットを対話的に使用する場合は、プロンプトや入力行の読み取りなど、対話型アクションをオーバーライドする Force パラメーターを常に指定します。 これは、非対話型のスクリプトやホストでコマンドレットを使用できるようにするために重要です。 対話型ホストでは、次のメソッドを実装できます。

ドキュメント出力オブジェクト (RD06)

Windows PowerShellパイプラインに書き込まれるオブジェクトを使用します。 各コマンドレットによって返されるオブジェクトをユーザーが利用するには、返されるオブジェクトを文書化する必要があります。また、返されるオブジェクトのメンバーの使用対象を文書化する必要があります。

コード ガイドライン

コマンドレット コードを記述する場合は、次のガイドラインに従う必要があります。 状況に適用されるコード ガイドラインが見つけたら、同様のガイドラインの設計ガイドラインを参照してください。

コマンドレットまたは PSCmdlet クラスから派生する (RC01)

コマンドレットは 、System.Management.Automation.Cmdlet または System.Management.Automation.PSCmdlet 基本クラスから派生する必要があります。 System.Management.Automation.Cmdlet クラスから派生したコマンドレットは、ランタイムのWindows PowerShellされません。 任意の Microsoft 言語から直接呼び出.NET Frameworkできます。 System.Management.Automation.PSCmdletクラスから派生するコマンドレットは、ランタイムのWindows PowerShellします。 したがって、実行空間内で実行されます。

実装するコマンドレット クラスはすべて、パブリック クラスである必要があります。 これらのコマンドレット クラスの詳細については、「コマンドレットの概要」 を参照してください。

コマンドレット属性の指定 (RC02)

コマンドレットがコマンドレットによって認識Windows PowerShell、その.NET Frameworkクラスを Cmdlet 属性で装飾する必要があります。 この属性は、 コマンドレットの次の機能を指定します。

  • コマンドレットを識別する動詞と名詞のペア。

  • 複数のパラメーター セットが指定されている場合に使用される既定のパラメーター セット。 既定のパラメーター セットは、使用Windows PowerShellパラメーター セットを決定するのに十分な情報が存在しない場合に使用されます。

  • コマンドレットが System.Management.Automation.Cmdlet.ShouldProcess* メソッドの呼び出しをサポートしているかどうかを示します。 このメソッドは、コマンドレットがシステムに変更を行う前に、ユーザーに確認メッセージを表示します。 確認要求の作成方法の詳細については、「確認の要求 」を参照してください。

  • 確認メッセージに関連付けられているアクションの影響レベル (または重大度) を示します。 ほとんどの場合、既定値の Medium を使用する必要があります。 影響レベルがユーザーに表示される確認要求に与える影響の詳細については、「確認の要求」 を参照してください。

コマンドレット属性を宣言する方法の詳細については 、「CmdletAttribute 宣言」を参照してください。

入力処理メソッドをオーバーライドする (RC03)

コマンドレットを環境に参加Windows PowerShell、次の入力処理メソッドの少なくとも 1 つをオーバーライドする必要があります。

System.Management.Automation.Cmdlet.BeginProcessing このメソッドは 1 回呼び出され、前処理機能を提供するために使用されます。

System.Management.Automation.Cmdlet.ProcessRecord このメソッドは複数回呼び出され、レコードバイレコード機能を提供するために使用されます。

System.Management.Automation.Cmdlet.EndProcessing このメソッドは 1 回呼び出され、後処理機能を提供するために使用されます。

OutputType 属性の指定 (RC04)

OutputType 属性 (Windows PowerShell 2.0 で導入) は、コマンドレットがパイプライン.NET Framework返す型を指定します。 コマンドレットの出力の種類を指定すると、コマンドレットによって返されるオブジェクトを他のコマンドレットで検出し、検出しがちになります。 この属性を使用してコマンドレット クラスを装飾する方法の詳細については 、「OutputType 属性宣言」を参照してください。

出力オブジェクトにハンドルを保持しない (RC05)

コマンドレットは 、System.Management.Automation.Cmdlet.WriteObject* メソッドに渡されるオブジェクトに対するハンドルを保持しません。 これらのオブジェクトは、パイプライン内の次のコマンドレットに渡されます。または、スクリプトによって使用されます。 オブジェクトのハンドルを保持すると、2 つのエンティティが各オブジェクトを所有し、エラーが発生します。

エラーを堅牢に処理する (RC06)

管理環境は本質的に、管理しているシステムに対して重要な変更を検出して行います。 そのため、コマンドレットでエラーを正しく処理する必要があります。 エラー レコードの詳細については、「エラー報告」をWindows PowerShellしてください。

System.Management.Automation.ErrorRecordオブジェクトには、ユーザーのエラーをグループ化するエラー カテゴリも必要です。 ユーザーは、シェル変数の値を CategoryView に設定することで、カテゴリに基づいて $ErrorView エラーを表示できます。 可能なカテゴリは 、System.Management.Automation.ErrorCategory 列挙体によって定義 されます。

  • コマンドレットによって新しいスレッドが作成され、そのスレッドで実行されているコードがハンドルされない例外をスローした場合、Windows PowerShell はエラーをキャッチし、プロセスを終了します。

  • オブジェクトのデストラクターにハンドルされない例外を引き起こすコードがある場合、Windows PowerShell はエラーをキャッチし、プロセスを終了します。 これは、オブジェクトがハンドルされない例外を引き起こす Dispose メソッドを呼び出す場合にも発生します。

新しいWindows PowerShellを使用してコマンドレットをデプロイする (RC07)

コマンドレットをパッケージWindows PowerShellデプロイする新しいモジュールを作成します。 モジュールのサポートは、Windows PowerShell 2.0 で導入されています。 コマンドレット クラスを含むアセンブリをバイナリ モジュール ファイルとして直接使用するか (コマンドレットをテストするときに非常に便利です)、またはコマンドレット アセンブリを参照するモジュール マニフェストを作成できます。 (モジュールを使用する場合は、既存のスナップイン アセンブリを追加することもできます)。モジュールの詳細については、「モジュールの作成」をWindows PowerShellしてください。

参照

強くお勧めする開発ガイドライン

お勧めする開発ガイドライン

Windows PowerShell コマンドレットの記述