about_Functions_Advanced_Methods

[アーティクル]
06/21/2023

簡単な説明

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

長い説明

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

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

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

属性の CmdletBinding 詳細については、「 about_Functions_CmdletBindingAttribute」を参照してください。 CmdletBindingAttribute クラスについては、「System.Management.Automation.Cmdlet.CmdletBindingAttribute」を参照してください。

入力処理メソッド

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

注意

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

開始

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

Process

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

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

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

重要

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

End

このブロックは、関数のオプションの 1 回限りの後処理を提供するために使用されます。

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

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

注意

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

確認方法

ShouldProcess

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

このメソッドの詳細については、「 System.Management.Automation.Cmdlet.ShouldProcess」を参照してください。

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

ShouldContinue

このメソッドは、2 番目の確認メッセージを要求するために呼び出されます。メソッドがを返すときに ShouldProcess 呼び出す $true必要があります。このメソッドの詳細については、「 System.Management.Automation.Cmdlet.ShouldContinue」を参照してください。

Error メソッド

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

詳細については、「 System.Management.Automation.Cmdlet.ThrowTerminatingError」を参照してください。

書き込みメソッド

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

WriteCommandDetail

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

WriteDebug

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

WriteError

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

注意

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

WriteObject

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

WriteProgress

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

WriteVerbose

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

WriteWarning

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

注意

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

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

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

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

Share via