必要な開発ガイドライン

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

このトピックの内容

設計ガイドライン

• 承認済み動詞のみを使用する (RD01)

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

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

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

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

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

コード ガイドライン

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

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

• 入力処理方法 (RC03) をオーバーライドする

• OutputType 属性 (RC04) を指定する

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

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

• Windows PowerShell モジュールを使用してコマンドレットを展開する (RC07)

設計ガイドライン

コマンドレットと他のコマンドレットの間で一貫したユーザー エクスペリエンスを確保するために、コマンドレットを設計するときは、次のガイドラインに従う必要があります。 状況に適用される設計ガイドラインが見つかると、同様のガイドラインについては必ずコード ガイドラインを参照してください。

承認済み動詞のみを使用する (RD01)

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

• System.Management.Automation.VerbsCommon

• System.Management.Automation.VerbsCommunications

• System.Management.Automation.VerbsData

• System.Management.Automation.VerbsDiagnostic

• System.Management.Automation.VerbsLifecycle

• System.Management.Automation.VerbsSecurity

• System.Management.Automation.VerbsOther

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

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

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

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

キャラクター	名前
#	番号記号
,	コンマ
()	かっこ
{}	歯列矯正器
[]	角かっこ
および	アンパサンド
-	ハイフン 注: ハイフンは動詞を名詞から区切るために使用できますが、名詞内または動詞内では使用できません。
/	スラッシュ マーク
\	バックスラッシュ
$	ドル記号
^	キャレット
;	セミコロン
:	コロン
「」	二重引用符
'	単一引用符
<>	っこ
|	縦棒
?	疑問符
@	at sign
`	バック ティック (墓のアクセント)
*	アスタリスク
%	パーセント記号
+	プラス記号
=	等号
~	チルダ

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

Windows PowerShell には、すべてのコマンドレットに共通のパラメーターセットと、特定の状況で追加される追加のパラメーターが用意されています。 独自のコマンドレットを設計するときは、Confirm、Debug、ErrorAction、ErrorVariable、OutBuffer、OutVariable、WarningAction、WarningVariable、WhatIf、UseTransaction、Verbose という名前を使用することはできません。 これらのパラメーターの詳細については、「共通パラメーター名 」を参照してください。

サポート確認要求 (RD04)

システムを変更する操作を実行するコマンドレットの場合は、System.Management.Automation.Cmdlet.ShouldProcess* メソッドを呼び出して確認を要求し、特殊な場合は System.Management.Automation.Cmdlet.ShouldContinue* メソッドを呼び出す必要があります。 (System.Management.Automation.Cmdlet.ShouldContinue* メソッドは、System.Management.Automation.Cmdlet.ShouldProcess* メソッドが呼び出された後にのみ呼び出す必要があります)。

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

注

コマンドレット クラスのコマンドレット属性が、System.Management.Automation.Cmdlet.ShouldProcess* メソッドの呼び出しをコマンドレットがサポートしていることを示しており、コマンドレットが system.Management.Automation.Cmdlet.ShouldProcess* メソッド 呼び出しに失敗した場合、ユーザーはシステムを予期せず変更する可能性があります。

システムの変更には、System.Management.Automation.Cmdlet.ShouldProcess* メソッドを使用します。 ユーザー設定と WhatIf パラメーターは、system.Management.Automation.Cmdlet.ShouldProcess* メソッド 制御します。 これに対し、System.Management.Automation.Cmdlet.ShouldContinue* 呼び出しでは、潜在的に危険な変更に関する追加のチェックが実行されます。 このメソッドは、ユーザー設定または WhatIf パラメーターによって制御されません。 コマンドレットが System.Management.Automation.Cmdlet.ShouldContinue* メソッド 呼び出す場合は、これら 2 つのメソッドの呼び出しをバイパスし、操作を続行する Force パラメーターが必要です。 これは、コマンドレットを非対話型のスクリプトとホストで使用できるため、重要です。

コマンドレットでこれらの呼び出しがサポートされている場合、ユーザーはアクションを実際に実行する必要があるかどうかを判断できます。 たとえば、Stop-Process コマンドレットは、System、Winlogon、Spoolsv プロセスなどの一連の重要なプロセスを停止する前に、System.Management.Automation.Cmdlet.ShouldContinue* メソッドを呼び出します。

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

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

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

• System.Management.Automation.Host.PSHostUserInterface.Prompt*

• System.Management.Automation.Host.PSHostUserInterface.PromptForChoice

• System.Management.Automation.Host.IHostUISupportsMultipleChoiceSelection.PromptForChoice

• System.Management.Automation.Host.PSHostUserInterface.PromptForCredential*

• System.Management.Automation.Host.PSHostUserInterface.ReadLine*

• System.Management.Automation.Host.PSHostUserInterface.ReadLineAsSecureString*

ドキュメント出力オブジェクト (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 クラスをコマンドレット属性で修飾する必要があります。 この属性は、コマンドレットの次の機能を指定します。

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

• 複数のパラメーター セットが指定されている場合に使用される既定のパラメーター セット。 既定のパラメーター セットは、使用するパラメーター セットを決定するのに十分な情報が 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 オブジェクトを参照する System.Management.Automation.Cmdlet.ThrowTerminatingError* メソッドを呼び出す必要があります。 コマンドレットによって例外がキャッチされない場合、Windows PowerShell ランタイム自体は、より少ない情報を含む終了エラーをスローします。

• パイプラインから送信される次のレコード (たとえば、別のプロセスによって生成されたレコード) に対する操作を停止しない終了しないエラーの場合、コマンドレットは、System.Management.Automation.ErrorRecord オブジェクトを参照する System.Management.Automation.Cmdlet.WriteError* メソッドを呼び出す必要があります。 終了しないエラーの例として、特定のプロセスが停止に失敗した場合に発生するエラーがあります。 System.Management.Automation.Cmdlet.WriteError* メソッドを呼び出すと、ユーザーは要求されたアクションを一貫して実行し、失敗した特定のアクションの情報を保持できます。 コマンドレットは、各レコードを可能な限り独立して処理する必要があります。

• System.Management.Automation.Cmdlet.ThrowTerminatingError* および System.Management.Automation.Cmdlet.WriteError* メソッドによって参照される System.Management.Automation.ErrorRecord オブジェクトには、そのコアに例外が必要です。 使用する例外を決定するときは、.NET Framework の設計ガイドラインに従ってください。 エラーが意味的に既存の例外と同じ場合は、その例外を使用するか、その例外から派生します。 それ以外の場合は、System.Exception 型から新しい例外階層または例外階層を直接派生させます。

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

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

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

Windows PowerShell モジュールを使用してコマンドレットを展開する (RC07)

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

こちらもご覧ください

強く推奨される開発ガイドライン

アドバイザリ開発ガイドライン

Windows PowerShell コマンドレット の作成