ja-JP/about_Functions_Advanced_Methods.help.txt
|
TOPIC 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 ブロックに意味的に似ています。リソースのクリーンアップは、次のシナリオ で強制されます。 1. パイプラインの実行が終了エラーなしで正常に完了したとき 1. 終了エラーによりパイプラインの実行が中断されたとき 1. Select-Object -First によってパイプラインが停止されたとき 1. Ctrl+c または StopProcessing() によってパイプラインが停止されている とき clean ブロックは、Success ストリームに書き込まれた出力をすべて破棄しま す。 注意: clean ブロックの追加は破壊的変更です。clean はキーワードとして解 析されるため、利用者はスクリプトブロックの最初のステートメントとして clean という名前のコマンドを直接呼び出すことができなくなります。ただし、 これが問題になる可能性は低いです。コマンドは呼び出し演算子 (& clean) を 使用して引き続き呼び出すことができます。 確認メソッド ShouldProcess このメソッドは、関数がシステムを変更するアクションを実行する前に利用者 に確認を求めるために呼び出されます。関数は、メソッドが返すブール値に基 づいて続行できます。このメソッドは、関数の process {} ブロック内からの み呼び出すことができます。CmdletBinding 属性も、関数が ShouldProcess を サポートすることを宣言する必要があります (前の例で示したとおり)。 このメソッドの詳細については、 System.Management.Automation.Cmdlet.ShouldProcess を参照してください。 確認を求める方法の詳細については、Requesting Confirmation を参照してくだ さい。 ShouldContinue このメソッドは、2 回目の確認メッセージを求めるために呼び出されます。 ShouldProcess メソッドが $true を返すときに呼び出すべきです。このメソッ ドの詳細については、 System.Management.Automation.Cmdlet.ShouldContinue を参照してください。 エラーメソッド 関数は、エラーが発生したときに 2 つの異なるメソッドを呼び出すことができ ます。非終了エラーが発生した場合、関数は Write メソッドのセクションで説 明する WriteError メソッドを呼び出すべきです。終了エラーが発生して関数が 続行できない場合、ThrowTerminatingError メソッドを呼び出すべきです。終 了エラーには throw ステートメントを、非終了エラーには Write-Error コマン ドレットを使用することもできます。 詳細については、 System.Management.Automation.Cmdlet.ThrowTerminatingError を参照してく ださい。 Write メソッド 関数は、次のメソッドを呼び出してさまざまな種類の出力を返すことができま す。すべての出力がパイプライン内の次のコマンドに送られるわけではないこ とに注意してください。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 を参照してください。 注: $WarningPreference 変数を構成するか、Verbose および Debug コマンド ラインオプションを使用して警告メッセージを表示することもできます。 $WarningPreference 変数の詳細については、about_Preference_Variables を 参照してください。 その他のメソッドとプロパティ $PSCmdlet 変数を通じてアクセスできるその他のメソッドとプロパティの詳細 については、System.Management.Automation.PSCmdlet を参照してください。 たとえば、ParameterSetName プロパティを使用すると、使用されているパラメ ーターセットを確認できます。パラメーターセットを使用すると、関数の実行時 に指定されたパラメーターに基づいて、異なるタスクを実行する関数を作成でき ます。 関連項目 about_Automatic_Variables about_Functions about_Functions_Advanced about_Functions_Advanced_Parameters about_Functions_CmdletBindingAttribute about_Functions_OutputTypeAttribute about_Preference_Variables ---- 原文: PowerShell-Docs (CC BY 4.0) の翻訳 / PSHelpJaJP |