about_Functions_Advanced_Methods

簡単な説明

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 ブロックによって表されます。 PowerShell 7.3 では、clean ブロックプロセスメソッドが追加されています。

関数でこれらのブロックを使用する必要はありません。名前付きブロックを使用しない場合、PowerShell は関数の end ブロックにコードを配置します。ただし、これらの名前付きブロックのいずれかを使用するか、dynamicparam ブロックを定義する場合は、すべてのコードを名前付きブロックに配置する必要があります。

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

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$true)]
    param ($Parameter1)
    begin{}
    process{}
    end{}
    clean{}
}

手記

これらのブロックは、CmdletBinding 属性を使用する関数だけでなく、すべての関数に適用されます。

`begin`

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

`process`

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

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

パイプラインの先頭または外側で関数を呼び出すと、process ブロックが 1 回実行されます。
パイプライン内では、process ブロックは、関数に到達する入力オブジェクトごとに 1 回実行されます。
関数に到達したパイプライン入力が空の場合、process ブロック は実行。
- begin、end、および clean ブロックは引き続き実行されます。

大事な

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

パイプライン入力を受け入れ、CmdletBindingを使用する関数を作成する場合、process ブロックでは、$_ または $PSItemではなく、パイプライン入力に定義したパラメーター変数を使用する必要があります。例えば：

function Get-SumOfNumbers {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, Position=0, ValueFromPipeline)]
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
       foreach ($n in $Numbers) {
           $retValue += $n
       }
    }

    end { $retValue }
}

PS> Get-SumOfNumbers 1, 2, 3, 4
10
PS> 1,2,3,4 | Get-SumOfNumbers
10

`end`

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

`clean`

clean ブロックは PowerShell 7.3 で追加されました。

clean ブロックは、ユーザーが begin、process、および end ブロックにまたがるリソースをクリーンアップするのに便利な方法です。意味的には、スクリプト関数またはスクリプトコマンドレットの他のすべての名前付きブロックをカバーする finally ブロックに似ています。リソースのクリーンアップは、次のシナリオに適用されます。

エラーを終了せずにパイプラインの実行が正常に終了した場合
終了エラーが原因でパイプラインの実行が中断された場合
パイプラインが Select-Object -First によって停止されたとき
Ctrl + c してパイプラインを停止する場合

クリーンブロックは、Success ストリームに書き込まれた出力をすべて破棄します。

注意

clean ブロックの追加は重大な変更です。 cleanはキーワードとして解析されるため、ユーザーは scriptblock の最初のステートメントとして clean という名前のコマンドを直接呼び出すのを防ぎます。ただし、問題になる可能性はありません。コマンドは、呼び出し演算子 (& clean) を使用して引き続き呼び出すことができます。

確認方法

ShouldProcess

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

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

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

ShouldContinue

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

エラーメソッド

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

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

書き込みメソッド

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

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を参照してください。

手記

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

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

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

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

こちらも参照ください

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-01-18