この文書は、Windows PowerShellのヘルプ機能で表示される内容を再構成したものです。

トピック
    about_Functions_Advanced_Methods

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  確認メソッド

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

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

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

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

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

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

  書き込みメソッド

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

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

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

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

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

    WriteObject
      このメソッドを使用すると、関数はオブジェクトをパイプラインの次のコマンドに
      送ることができます。ほとんどの場合、関数がデータを返すときにこのメソッドを
      使用します。詳細については、MSDN ライブラリの「Cmdlet.WriteObject Method (
      Cmdlet.WriteObject メソッド)」(http://go.microsoft.com/fwlink/?LinkId=1421
      58) を参照してください。
      
    WriteProgress
      処理の完了までに時間がかかる関数の場合、このメソッドを使用すると、関数は W
      riteProgress メソッドを呼び出して、進行状況情報を表示することができます。
      たとえば、完了した部分をパーセントで表示することができます。詳細については、
      MSDN ライブラリの「Cmdlet.WriteProgress Method (Cmdlet.WriteProgress メソ
      ッド)」(http://go.microsoft.com/fwlink/?LinkId=142160) を参照してください。
      
    WriteVerbose
      関数の動作について詳細な情報を得るには、関数から WriteVerbose メソッドを
      呼び出して、詳細メッセージをユーザーに表示します。既定では、詳細メッセー
      ジは表示されません。詳細については、MSDN ライブラリの「Cmdlet.WriteVerbo
      se Method (Cmdlet.WriteVerbose メソッド)」(http://go.microsoft.com/fwlin
      k/?LinkId=142162) を参照してください。

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

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

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

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

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

関連項目
    about_Functions_Advanced
    about_Functions_CmdletBindingAttributes
    about_Functions_Advanced_Parameters
	

記事で解説しているパソコンの環境
　基本ソフト：　Windows 7
　キーワード：　Windows PowerShell、ヘルプ、HelpFile、about_functions_advanced_methods