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 は関数のブロックにコードを end 配置します。 ただし、これらの名前付きブロックのいずれかを使用する場合、またはブロックを定義する dynamicparam 場合は、すべてのコードを名前付きブロックに配置する必要があります。

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

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    begin{}
    process{}
    end{}
}

Note

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

begin

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

process

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

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

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

重要

関数パラメーターがパイプライン入力を受け入れるように設定されていて、ブロックが 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 回限りの後処理を提供するために使用されます。

確認方法

ShouldProcess

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

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

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

ShouldContinue

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

エラー メソッド

エラーが発生した場合、関数は 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」を参照してください。

Note

終了エラーが発生した場合、関数は 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」を参照してください。

Note

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

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

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

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

関連項目