about_Functions_Advanced_Methods

簡単な説明

属性を指定 CmdletBinding する関数が、コンパイルされたコマンドレットで使用できるメソッドとプロパティを使用する方法について説明します。

長い説明

属性を指定 CmdletBinding する関数は、 $PSCmdlet 変数を通じて多数のメソッドとプロパティにアクセスできます。 これらのメソッドには、次のメソッドが含まれます。

• コンパイルされたコマンドレットが作業を行うために使用する入力処理メソッド。
• ShouldProcessアクションが実行される前にユーザーフィードバックを取得するために使用されるメソッドと ShouldContinue メソッド。
• ThrowTerminatingErrorエラーレコードを生成するメソッド。
• さまざまな種類の出力を返すメソッドがいくつか Write あります。

PSCmdlet クラスのすべてのメソッドとプロパティは、高度な関数で使用できます。 詳細については、「 PSCmdlet」を参照してください。

属性の CmdletBinding 詳細については、「 about_Functions_CmdletBindingAttribute」を参照してください。 コマンドレット bindingattribute クラスについては、「system.string」を参照してください。

入力処理メソッド

このセクションで説明するメソッドは、入力処理メソッドと呼ばれます。 関数の場合、これら3つのメソッドは、関数の、 Process 、および End の各ブロックによって Begin 表されます。 関数でこれらのブロックを使用する必要はありません。

注意

これらのブロックは、 CmdletBinding 属性を使用しない関数でも使用できます。

開始

このブロックは、関数に対してオプションの1回限りの前処理を行うために使用されます。 PowerShell ランタイムは、パイプライン内の関数の各インスタンスに対して、このブロック内のコードを1回使用します。

Process

このブロックは、関数のレコードごとの処理を提供するために使用されます。 ブロックは Process 、他のブロックを定義することなく使用できます。 ブロックの Process 実行回数は、関数の使用方法と、関数が受け取る入力によって異なります。

自動変数 $_ またはは $PSItem 、ブロックで Process 使用するために、パイプライン内の現在のオブジェクトを格納します。 $input自動変数には、関数とスクリプトブロックでのみ使用できる列挙子が含まれています。 詳細については、「about_Automatic_Variables」を参照してください。

• パイプラインの先頭または外部で関数を呼び出すと、ブロックが Process 1 回実行されます。
• パイプライン内では、ブロックは Process 、関数に到達した入力オブジェクトごとに1回実行されます。
• 関数に到達したパイプライン入力が空の場合、 Process ブロックは実行 されません 。
  • ブロックとブロックは Begin 依然と End して実行されます。

重要

関数パラメーターがパイプライン入力を受け入れるように設定されて Process いて、ブロックが定義されていない場合、レコードごとの処理は失敗します。 この場合、関数は、入力に関係なく、1回だけ実行されます。

End

このブロックは、関数に対して省略可能な1回限りの後処理を提供するために使用されます。

次の例は、1回限りの前処理 Process のブロック、複数のレコード処理のブロック、および End 1 回限りの後処理のブロックを含む関数の概要を示してい Begin ます。

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    Begin{}
    Process{}
    End{}
}

注意

またはブロックのいずれかを使用するには End 、 Begin 3 つのブロックをすべて定義する必要があります。 3つすべてのブロックを使用する場合は、すべての PowerShell コードがいずれかのブロックに含まれている必要があります。

確認方法

ShouldProcess

このメソッドは、システムを変更するアクションを実行する前に、ユーザーからの確認を要求するために呼び出されます。 関数は、メソッドによって返されるブール値に基づいて続行できます。 このメソッドを呼び出すことができるのは、関数のブロック内 Process{} からだけです。 また、属性は CmdletBinding 、関数が (前の例で示したように) をサポート ShouldProcess することも宣言する必要があります。

このメソッドの詳細については、「 システムの管理」を参照してください。

確認を要求する方法の詳細については、「 確認の要求」を参照してください。

ShouldContinue

このメソッドは、2番目の確認メッセージを要求するために呼び出されます。 メソッドから ShouldProcess 制御が戻っ $true たときに呼び出す必要があります。 このメソッドの詳細については、「 システムの管理」を参照してください。

エラーメソッド

関数は、エラーが発生したときに2つの異なるメソッドを呼び出すことができます。 終了しないエラーが発生した場合、関数はメソッドを呼び出す WriteError 必要があります。これについては、 Write 「メソッド」セクションを参照してください。 終了エラーが発生し、関数を続行できない場合は、メソッドを呼び出す ThrowTerminatingError 必要があります。 また、ステートメントを使用してエラーを終了し、書き込みエラーコマンドレットを使用 Throw して、終了しないエラーを確認することもできます。

詳細については、「 ThrowTerminatingError」を参照してください。

書き込みメソッド

関数は、次のメソッドを呼び出して、異なる種類の出力を返すことができます。 すべての出力がパイプラインの次のコマンドに送られているわけではないことに注意してください。 などのさまざまな Write コマンドレットを Write-Error 使用することもできます。

WriteCommandDetail

メソッドの WriteCommandDetails 詳細については、「 WriteCommandDetail」を参照してください。

WriteDebug

関数のトラブルシューティングに使用できる情報を提供するには、関数がメソッドを呼び出す WriteDebug ようにします。 メソッドは WriteDebug 、ユーザーにデバッグメッセージを表示します。 詳細については 、「system.string」を参照してください。

WriteError

関数は、終了しないエラーが発生し、関数がレコードの処理を続行するように設計されている場合に、このメソッドを呼び出す必要があります。 詳細については、「 WriteError」を参照してください。

注意

終了エラーが発生した場合、関数は ThrowTerminatingError メソッドを呼び出す必要があります。

WriteObject

WriteObjectメソッドを使用すると、関数は、パイプラインの次のコマンドにオブジェクトを送信できます。 ほとんどの場合、は、 WriteObject 関数がデータを返すときに使用するメソッドです。 詳細については、「 PSCmdlet. WriteObject」を参照してください。

WriteProgress

完了に時間がかかるアクションを含む関数の場合、このメソッドは、進行状況の情報が表示されるように、関数がメソッドを呼び出す WriteProgress ことができるようにします。 たとえば、完了した割合を表示できます。 詳細については、「 PSCmdlet」を参照してください。

WriteVerbose

関数の動作に関する詳細情報を提供するには、メソッドを呼び出し WriteVerbose て、ユーザーに詳細メッセージを表示するようにします。 既定では、詳細メッセージは表示されません。 詳細については、「 PSCmdlet」を参照してください。

WriteWarning

予期しない結果になる可能性のある条件に関する情報を提供するには、関数が WriteWarning メソッドを呼び出して、警告メッセージをユーザーに表示します。 既定では、警告メッセージが表示されます。 詳細については、「 PSCmdlet」を参照してください。

注意

また、変数を構成 $WarningPreference するか、および Debug コマンドラインオプションを使用 Verbose して、警告メッセージを表示することもできます。 変数の $WarningPreference 詳細については、「 about_Preference_Variables」を参照してください。

その他のメソッドとプロパティ

変数を使用して $PSCmdlet アクセスできるその他のメソッドとプロパティの詳細については、「 PSCmdlet」を参照してください。

たとえば、 ParameterSetName プロパティを使用すると、使用されているパラメーターセットを確認できます。 パラメーターセットを使用すると、関数の実行時に指定されたパラメーターに基づいてさまざまなタスクを実行する関数を作成できます。

関連項目

• about_Automatic_Variables
• about_Functions
• about_Functions_Advanced
• about_Functions_Advanced_Parameters
• about_Functions_CmdletBindingAttribute
• about_Functions_OutputTypeAttribute
• about_Preference_Variables