about_Functions_Advanced_Methods

  • [アーティクル]

適用対象: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

トピック

about_Functions_Advanced_Methods

概要

CmdletBinding 属性を指定する関数では、コンパイル済みコマンドレットで利用可能なメソッドとプロパティをどのように使用できるかについて説明します。

詳細説明

CmdletBinding 属性を指定する関数は、$pscmdlet 変数を利用してさまざまなメソッドとプロパティにアクセスできます。これらのメソッドには、次のメソッドが含まれます。

- コンパイル済みコマンドレットが作業の実行に使用する入力処理メソッド。

- アクションが実行される前にユーザーのフィードバックを取得するために使用される ShouldProcess メソッドと ShouldContinue メソッド。

- エラー レコードを生成するための ThrowTerminatingError メソッド。

- さまざまな種類の出力を返すいくつかの書き込みメソッド。

PSCmdlet クラスのすべてのメソッドとプロパティは、高度な関数で使用できます。これらのメソッドとプロパティの詳細については、https://go.microsoft.com/fwlink/?LinkId=142139 で MSDN (Microsoft Developer Network) ライブラリの「System.Management.Automation.PSCmdlet」を参照してください。

入力処理メソッド

このセクションで説明する方法は、入力処理メソッドと呼ばれます。関数の場合、これら 3 つのメソッドは関数の Begin、Process、End の各ブロックで表されます。各関数には、これらのブロックの 1 つ以上を含める必要があります。Windows PowerShell® ランタイムは、関数を実行しているときに、これらのブロック内のコードを使用します。(これらのブロックは、CmdletBinding 属性を使用していない関数でも使用できます。)

Begin

このブロックは、関数の前処理をオプションで 1 回だけ実行するために使用されます。Windows PowerShell ランタイムは、パイプライン内の関数のインスタンスごとに 1 回、このブロック内のコードを使用します。

Process

このブロックは、関数のレコードごとの処理を実行するために使用されます。このブロックは、関数への入力に応じて、必要な回数だけ使用されることもあれば、まったく使用されないこともあります。たとえば、関数がパイプラインの最初のコマンドである場合、Process ブロックは 1 回使用されます。関数がパイプラインの最初のコマンドではない場合、Process ブロックは関数がパイプラインから入力を受け取るたびに 1 回使用されます。パイプライン入力がない場合、Process ブロックは使用されません。

関数パラメーターがパイプライン入力を受け入れるように設定されている場合は、このブロックを定義する必要があります。このブロックを定義しない場合は、パラメーターがパイプラインからの入力を受け入れるようになっていても、関数はパイプラインから渡される値を受け取りません。

また、関数が確認要求をサポートしている場合 (Parameter 属性の SupportsShouldProcess パラメーターが $True に設定されている場合) は、Process ブロック内から ShouldProcess メソッドの呼び出しを行う必要があります。

End

このブロックは、関数の後処理をオプションで 1 回だけ実行するために使用されます。

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

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

確認メソッド

ShouldProcess

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

このメソッドの詳細については、https://go.microsoft.com/fwlink/?LinkId=142142 で MSDN ライブラリの「System.Management.Automation.Cmdlet.ShouldProcess」を参照してください。

確認を求める方法の詳細については、https://go.microsoft.com/fwlink/?LinkID=136658 で MSDN ライブラリの「確認の要求」を参照してください。

ShouldContinue

このメソッドは、2 つ目の確認メッセージを要求するために呼び出されます。これは、ShouldProcess メソッドが $true を返すと呼び出されます。このメソッドの詳細については、https://go.microsoft.com/fwlink/?LinkId=142143 で MSDN ライブラリの「System.Management.Automation.Cmdlet.ShouldContinue」を参照してください。

エラー メソッド

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

詳細については、https://go.microsoft.com/fwlink/?LinkId=142144 で MSDN ライブラリの「System.Management.Automation.Cmdlet.ThrowTerminatingError」を参照してください。

書き込みメソッド

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

WriteCommandDetail

WriteCommandDetails メソッドについては、https://go.microsoft.com/fwlink/?LinkId=142155 で MSDN ライブラリの「System.Management.Automation.Cmdlet.WriteCommandDetail」を参照してください。

WriteDebug

関数のトラブルシューティングに使用できる情報を提供するには、関数で WriteDebug メソッドを呼び出します。これにより、ユーザーにデバッグ メッセージが表示されます。詳細については、https://go.microsoft.com/fwlink/?LinkId=142156 で MSDN ライブラリの「System.Management.Automation.Cmdlet.WriteDebug」を参照してください。

WriteError

終了しないエラーが発生し、関数がレコードの処理を続行するように設計されている場合、関数ではこのメソッドを呼び出す必要があります。詳細については、https://go.microsoft.com/fwlink/?LinkId=142157 で MSDN ライブラリの「System.Management.Automation.Cmdlet.WriteError」を参照してください。

注記:

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

WriteObject

このメソッドを使用すると、関数ではパイプラインの次のコマンドにオブジェクトを渡すことができます。ほとんどの場合、これは関数がデータを返すときに使用されるメソッドです。詳細については、https://go.microsoft.com/fwlink/?LinkId=142158 で MSDN ライブラリの「System.Management.Automation.PSCmdlet.WriteObject」を参照してください。

WriteProgress

アクションが完了するまでに時間がかかる関数の場合、このメソッドを使用すると、WriteProgress メソッドを呼び出して進行状況に関する情報を表示できます。たとえば、達成率を表示できます。詳細については、https://go.microsoft.com/fwlink/?LinkId=142160 で MSDN ライブラリの「System.Management.Automation.PSCmdlet.WriteProgress」を参照してください。

WriteVerbose

関数の実行内容に関する詳細を提供するには、関数で WriteVerbose メソッドを呼び出して、ユーザーに詳細なメッセージを表示します。既定では、詳細なメッセージは表示されません。詳細については、https://go.microsoft.com/fwlink/?LinkId=142162 で MSDN ライブラリの「System.Management.Automation.PSCmdlet.WriteVerbose」を参照してください。

WriteWarning

予期しない結果が生じる可能性がある条件に関する情報を提供するには、関数で WriteWarning メソッドを呼び出して、ユーザーに警告メッセージを表示します。既定では、警告メッセージが表示されます。詳細については、https://go.microsoft.com/fwlink/?LinkId=142164 で MSDN ライブラリの「System.Management.Automation.PSCmdlet.WriteWarning」を参照してください。

注記:

WarningPreference 変数を構成するか、または Verbose および Debug コマンド ライン オプションを使用して、警告メッセージを表示することもできます。

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

$PSCmdlet 変数からアクセス可能なその他のメソッドとプロパティについては、https://go.microsoft.com/fwlink/?LinkId=142139 で MSDN ライブラリの「System.Management.Automation.PSCmdlet」を参照してください。

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

関連項目

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Parameters

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute