about_Functions_Advanced_Methods

[アーティクル]
09/24/2009
トピック
    about_Functions_Advanced_Methods

簡易説明
    CmdletBinding 属性を指定する関数が、コンパイル済みコマンドレットから利用できるメソッドお
    よびプロパティを使用できるようにする方法について説明します。

詳細説明
    CmdletBinding 属性を指定する関数は、$pscmdlet 変数を介して多くのメソッドおよびプロパテ
    ィにアクセスできます。これには、次のメソッドが含まれます。


        - コンパイル済みコマンドレットが操作のために使用する入力処理メソッド

        - 操作が実行される前にユーザー フィードバックを取得するために使用される 
          ShouldProcess メソッドと ShouldContinue メソッド

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

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

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


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


  入力処理メソッド

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

      
    Begin
      このブロックは、省略可能な 1 回限りの前処理を関数に提供します。Windows PowerShell ラ
      ンタイムは、パイプライン内の関数の各インスタンスについて、このブロック内のコードを 1 回使
      用します。


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

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

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

    End
      このブロックは、省略可能な 1 回限りの後処理を関数に提供します。

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

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


  確認メソッド

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

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

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


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


  エラー メソッド

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

    詳細については、MSDN ライブラリの「Cmdlet.ThrowTerminatingError Method 
    (Cmdlet.ThrowTerminatingError メソッド)」
    (https://go.microsoft.com/fwlink/?LinkId=142144) を参照してください。
    


  書き込みメソッド

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


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


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


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

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


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


    WriteProgress
      処理の完了までに時間がかかる関数の場合、このメソッドを使用すると、関数は WriteProgress 
      メソッドを呼び出して、進行状況情報を表示することができます。たとえば、完了した部分をパー
      セントで表示することができます。詳細については、MSDN ライブラリの「Cmdlet.WriteProgress 
      Method (Cmdlet.WriteProgress メソッド)」(https://go.microsoft.com/fwlink/?LinkId=14
      2160) を参照してください。
      


    WriteVerbose
      関数の動作について詳細な情報を得るには、関数から WriteVerbose メソッドを呼び出して、詳細
      メッセージをユーザーに表示します。既定では、詳細メッセージは表示されません。詳細について
      は、MSDN ライブラリの「Cmdlet.WriteVerbose Method (Cmdlet.WriteVerbose メソッド)」
      (https://go.microsoft.com/fwlink/?LinkId=142162) を参照してください。

    WriteWarning
      予期しない結果の原因となる条件について情報を得るには、関数から WriteWarning メソッドを
      呼び出して、警告メッセージをユーザーに表示します。既定では、警告メッセージは表示されます。
      詳細については、MSDN ライブラリの「Cmdlet.WriteWarning Method (Cmdlet.WriteWarn
      ing メソッド)」(https://go.microsoft.com/fwlink/?LinkId=142164) を参照してください。
      

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


  その他のメソッドおよびプロパティ

      $PSCmdlet 変数を介してアクセスできるその他のメソッドおよびプロパティの詳細については、
      MSDN ライブラリの「PSCmdlet Class (PSCmdlet クラス)」
      (https://go.microsoft.com/fwlink/?LinkId=142139) を参照してください。

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


関連項目
    about_Functions_Advanced
    about_Functions_CmdletBindingAttributes
    about_Functions_Advanced_Parameters
次の方法で共有

about_Functions_Advanced_Methods

その他のリソース
