
記事記号:[me1537] 初版:2011/May/10

トピック
about_Functions_Advanced_Methods
簡易説明
CmdletBinding 属性を指定する関数が、コンパイル済みコマンドレットから利用でき
るメソッドおよびプロパティを使用できるようにする方法について説明します。
詳細説明
CmdletBinding 属性を指定する関数は、$pscmdlet 変数を介して多くのメソッドおよ
びプロパティにアクセスできます。これには、次のメソッドが含まれます。
- コンパイル済みコマンドレットが操作のために使用する入力処理メソッド
- 操作が実行される前にユーザー フィードバックを取得するために使用される
ShouldProcess メソッドと ShouldContinue メソッド
- エラー レコードを生成する ThrowTerminatingError メソッド
- さざまな種類の出力を返すいくつかの書き込みメソッド
- さざまな種類の出力を返すいくつかの書き込みメソッド
PSCmdlet クラスのすべてのメソッドおよびプロパティは、高度な関数から利用できま
す。これらのメソッドおよびプロパティの詳細については、MSDN (Microsoft Develop
er Network) ライブラリで System.Management.Automation.PSCmdlet (http://go.mic
rosoft.com/fwlink/?LinkId=142139) を参照してください。
入力処理メソッド
ここで説明するメソッドは、入力処理メソッドと呼ばれます。関数の場合、これら
の 3 つのメソッドは、関数の Begin、Process、および End ブロックで表されます。
各関数には、これらのブロックを 1 つ以上含める必要があります。Windows PowerS
hell ランタイムは、関数の実行時にこれらのブロック内のコードを使用します (こ
れらのブロックは、CmdletBinding 属性を使用しない関数からも利用できます)。
Begin
このブロックは、省略可能な 1 回限りの前処理を関数に提供します。Windows Pow
erShell ランタイムは、パイプライン内の関数の各インスタンスについて、このブ
ロック内のコードを 1 回使用します。
Process
このブロックは、レコードごとの処理を関数に提供します。関数への入力に応じて、
このブロックは何回も使用したり、まったく使用しないこともできます。たとえば、
パイプラインの最初のコマンドが関数である場合、Process ブロックは 1 回使用
されます。パイプラインの最初のコマンドが関数でない場合、Process ブロックは、
関数がパイプラインから入力を受け取るたびに 1 回使用されます。パイプライン入
力がない場合、Process ブロックは使用されません。
関数パラメーターがパイプライン入力を受け取るように設定されている場合は、こ
のブロックを定義する必要があります。このブロックが定義されておらず、パイプ
ラインからの入力をパラメーターが受け取る場合、関数は、パイプラインを介して
関数に渡される値を実行しません。
また、関数が確認要求をサポートしている場合 (パラメーター属性の SupportsSho
uldProcess パラメーターが $True に設定されている場合)、ShouldProcess メソッ
ドの呼び出しは、Process ブロック内から実行する必要があります。
End
このブロックは、省略可能な 1 回限りの後処理を関数に提供します。
次の例は、1 回限りの前処理用の Begin ブロック、複数回のレコード処理用の Pr
ocess ブロック、および 1 回限りの後処理用の End ブロックを含む関数のアウト
ラインを示しています。
Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)] Param
($Parameter1)
Begin{}
Process{}
End{}
}
確認メソッド
ShouldProcess
このメソッドは、システムを変更する操作を関数が実行する前にユーザーからの確
認を要求する場合に呼び出されます。この関数は、メソッドによって返されるブー
ル値に基づいて続行されます。このメソッドは、関数の Process{} ブロック内か
らのみ呼び出すことができます。また、CmdletBinding 属性は、関数が ShouldPro
cess をサポートしていることを (前の例に示すように) 宣言する必要があります。
このメソッドの詳細については、MSDN ライブラリの「Cmdlet.ShouldProcess Method
(Cmdlet.ShouldProcess メソッド)」(http://go.microsoft.com/fwlink/?LinkId=14
2142) を参照してください。
確認を要求する方法の詳細については、MSDN ライブラリの「Requesting Confirmat
ion (確認の要求)」(http://go.microsoft.com/fwlink/?LinkID=136658) を参照し
てください。
ShouldContinue
このメソッドは、2 番目の確認メッセージを要求する場合に呼び出されます。Shou
ldProcess メソッドが $true を返す場合に呼び出してください。このメソッドの
詳細については、MSDN ライブラリの「Cmdlet.ShouldContinue Method (Cmdlet.Sh
ouldContinue メソッド)」(http://go.microsoft.com/fwlink/?LinkId=142143) を
参照してください。
エラー メソッド
エラーが発生した場合、関数は 2 つの異なるメソッドを呼び出すことができます。
未終了エラーが発生した場合、関数は WriteError メソッドを呼び出す必要がありま
す。このメソッドについては、「書き込みメソッド」セクションで説明します。終了
エラーが発生し、関数を続行できない場合、関数は ThrowTerminatingError メソッ
ドを呼び出す必要があります。終了エラーには Throw ステートメントを、未終了エ
ラーには Write-Error コマンドレットを使用することもできます。
詳細については、MSDN ライブラリの「Cmdlet.ThrowTerminatingError Method
(Cmdlet.ThrowTerminatingError メソッド)」
(http://go.microsoft.com/fwlink/?LinkId=142144) を参照してください。
書き込みメソッド
関数は次のメソッドを呼び出して、さざまな種類の出力を返すことができます。す
べての出力が、パイプラインの次のコマンドに送られるわけではありません。Writ
e-Error など、さまざまな Write コマンドレットを使用することもできます。
WriteCommandDetail
WriteCommandDetails メソッドの詳細については、MSDN ライブラリの
「Cmdlet.WriteCommandDetail Method (Cmdlet.WriteCommandDetail メソッド)」
(http://go.microsoft.com/fwlink/?LinkId=142155) を参照してください。
WriteDebug
関数のトラブルシューティングに使用できる情報を得るには、関数から WriteDebu
g メソッドを呼び出してください。デバッグ メッセージがユーザーに表示されます。
詳細については、MSDN ライブラリの「Cmdlet.WriteDebug Method (Cmdlet.WriteD
ebug メソッド)」(http://go.microsoft.com/fwlink/?LinkId=142156) を参照して
ください。
WriteError
未終了エラーが発生した場合、関数がレコードの処理を続行するように作成されて
いるときは、関数はこのメソッドを呼び出す必要があります。詳細については、MS
DN ライブラリの「Cmdlet.WriteError Method (Cmdlet.WriteError メソッド)」
(http://go.microsoft.com/fwlink/?LinkId=142157) を参照してください。
注: 終了エラーが発生した場合、関数は ThrowTerminatingError メソッドを呼び
出す必要があります。
WriteObject
このメソッドを使用すると、関数はオブジェクトをパイプラインの次のコマンドに
送ることができます。ほとんどの場合、関数がデータを返すときにこのメソッドを
使用します。詳細については、MSDN ライブラリの「Cmdlet.WriteObject Method (
Cmdlet.WriteObject メソッド)」(http://go.microsoft.com/fwlink/?LinkId=1421
58) を参照してください。
WriteProgress
処理の完了までに時間がかかる関数の場合、このメソッドを使用すると、関数は W
riteProgress メソッドを呼び出して、進行状況情報を表示することができます。
たとえば、完了した部分をパーセントで表示することができます。詳細については、
MSDN ライブラリの「Cmdlet.WriteProgress Method (Cmdlet.WriteProgress メソ
ッド)」(http://go.microsoft.com/fwlink/?LinkId=142160) を参照してください。
WriteVerbose
関数の動作について詳細な情報を得るには、関数から WriteVerbose メソッドを
呼び出して、詳細メッセージをユーザーに表示します。既定では、詳細メッセー
ジは表示されません。詳細については、MSDN ライブラリの「Cmdlet.WriteVerbo
se Method (Cmdlet.WriteVerbose メソッド)」(http://go.microsoft.com/fwlin
k/?LinkId=142162) を参照してください。
WriteWarning
予期しない結果の原因となる条件について情報を得るには、関数から WriteWarn
ing メソッドを呼び出して、警告メッセージをユーザーに表示します。既定では、
警告メッセージは表示されます。詳細については、MSDN ライブラリの「Cmdlet.
WriteWarning Method (Cmdlet.WriteWarning メソッド)」(http://go.microsoft
.com/fwlink/?LinkId=142164) を参照してください。
注: WarningPreference 変数を設定するか、または Verbose および Debug コマ
ンド ライン オプションを使用しても、警告メッセージを表示することがで
きます。
その他のメソッドおよびプロパティ
$PSCmdlet 変数を介してアクセスできるその他のメソッドおよびプロパティの詳
細については、MSDN ライブラリの「PSCmdlet Class (PSCmdlet クラス)」
(http://go.microsoft.com/fwlink/?LinkId=142139) を参照してください。
たとえば、ParameterSetName プロパティを使用すると、使用されているパラメ
ーター セットを表示できます。パラメーター セットを使用すると、指定したパ
ラメーターに基づいて、関数の実行時にさまざまなタスクを実行する関数を作成
することができます。
関連項目
about_Functions_Advanced
about_Functions_CmdletBindingAttributes
about_Functions_Advanced_Parameters

基本ソフト: Windows 7
キーワード: Windows PowerShell、ヘルプ、HelpFile、about_functions_advanced_methods