PowerShell HelpFile - about_functions
 記事記号:[me1535] 初版:2011/May/10

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

トピック
    about_Functions

簡易説明
    Windows PowerShell で関数を作成および使用する方法について説明します。

詳細説明
    関数とは、名前を割り当てられたステートメント リストのことです。関数を実行する
    場合は、関数名を入力します。リスト内のステートメントは、コマンド プロンプトで
    入力した場合と同じように実行されます。

    コマンドレットと同様、関数にはパラメーターを指定できます。パラメーターは、名
    前付きパラメーター、位置指定パラメーター、スイッチ パラメーター、または動的パ
    ラメーターにすることができます。関数パラメーターは、コマンド ラインまたはパイ
    プラインから読み取ることができます。

    関数は値を返すことができ、その値は、表示、変数への代入、または他の関数やコマ
    ンドレットに渡すことが可能です。

    関数のステートメント リストには、さまざまなステートメント リストを、Begin、Pr
    ocess、および End キーワードと共に含めることができます。これらのステートメン
    ト リストは、パイプラインからの入力をさまざまに処理します。

    フィルターとは、Filter キーワードを使用する特殊な関数のことです。

    関数も、コマンドレットと同様に動作します。C# プログラミングを使用しなくても、
    コマンドレットと同様に動作する関数を作成することができます。詳細については、
    「about_Functions_Advanced」を参照してください。

  構文
      関数の構文を次に示します。

          function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]  
          {
              param([type]$parameter1 [,[type]$parameter2])

              dynamicparam {<statement list>}
  
              begin {<statement list>}
              process {<statement list>}
              end {<statement list>}
          }

      関数には次の項目が含まれます。

          - Function キーワード
          - スコープ (省略可能)
          - 選択した名前
          - 任意の数の名前付きパラメーター (省略可能)
          - 中かっこ ({}) で囲まれた 1 つ以上の Windows PowerShell コマンド

      Dynamicparam キーワードおよび関数の動的パラメーターの詳細については、
      「about_Functions_Advanced_Parameters」を参照してください。

  簡単な関数
      関数を役に立つものにするには、複雑にする必要はありません。次の関数は、現在
      のシステムの System アカウントに属していない環境変数を取得します。

          function other_env 
          { 
             get-wmiObject win32_environment | 
                where {$_.username -ne "<System>"}
          }

      この関数を実行するには、「other_env」と入力します。

      便利な小さい関数を集めて、ツールボックスを作成することができます。これらの
      関数は、「about_Profiles」およびこのトピックの後半で説明する指示に従って、
      Windows PowerShell プロファイルに追加します。

  パラメーターを持つ関数
      名前付きパラメーター、位置指定パラメーター、スイッチ パラメーター、動的パラ
      メーターなど、パラメーターは関数と共に使用することができます。関数の動的パ
      ラメーターの詳細については、「about_Functions_Advanced_Parameters」を参照し
      てください。

  名前付きパラメーター
      名前付きパラメーターは、任意の数だけ定義することができます。このトピックの
      後半で説明するように、名前付きパラメーターの既定値を含めることができます。

      次の例の構文に示すように、Param キーワードを使用して、パラメーターを中かっ
      この内側で定義することができます。
    
          function <name> { 
               param ([type]$parameter1[,[type]$parameter2])
               <statement list> 
          }


      次の例の構文に示すように、Param キーワードを使用しないで、パラメーターを中
      かっこの外側で定義することもできます。

          function <name> [([type]$parameter1[,[type]$parameter2])] {
              <statement list>
          }

      この 2 つの方法に違いはありません。好ましい方法を使用してください。

      関数を実行すると、パラメーターに指定した値は、そのパラメーター名を格納する
      変数に代入されます。この変数の値は関数で使用できます。

      次の例は、Small_files という関数です。この関数には、$size というパラメータ
      ーがあります。$size パラメーターの値に満たない小さいファイルがすべて表示さ
      れます (ディレクトリは除外されます)。

          function small_files {
              param ($size)
              Get-ChildItem c:\ | where {
                  $_.length -lt $size -and !$_.PSIsContainer} 
          }

      関数では、$size 変数を使用できます。この変数は、パラメーターに定義されてい
      る名前です。

      この関数を使用するには、次のコマンドを入力します。
 
          C:\PS> function small_files ?size 50


      名前付きパラメーターの値は、パラメーター名なしでも入力できます。たとえば、
      次のコマンドでは、Size パラメーターを指定するコマンドと同じ結果が得られます。

          C:\PS> function small_files 50


      パラメーターの既定値を定義するには、次の Small_files の例に示すように、パ
      ラメーター名の後に等号と値を入力します。

          function small_files ($size = 100) {
              Get-ChildItem c:\ | where {
                  $_.length -lt $size -and !$_.PSIsContainer} 
          }


      値なしで「small_files」と入力すると、100 が $size に代入されます。値を指定
      すると、関数ではその値が使用されます。

  位置指定パラメーター
      位置指定パラメーターとは、パラメーター名のないパラメーターのことです。Wind
      ows PowerShell では、各パラメーター値と関数内のパラメーターを関連付けるた
      めに、パラメーター値が使用されます。

      位置指定パラメーターを使用する場合は、関数名の後に 1 つ以上の値を入力します。
      位置指定パラメーター値は、$args 配列変数に代入されます。関数名の後の値は、
      $args 配列の 1 番目の位置 $args[0] に代入されます。

      次の Extension 関数は、.txt ファイル名拡張子を、指定するファイル名に付けま
      す。

          function extension {
              $name = $args[0] + ".txt"
              $name
          }

          C:\PS> extension myTextFile
          myTextFile.txt
   
      関数には、複数の位置指定パラメーターを指定できます。次の例では、関数名と共
      に入力された値を表示しています。

          function repeat { foreach ($arg in $args) { "The input is $arg" } }

          C:\PS>repeat one 
          The input is one

          C:\PS> repeat one two three
          The input is one
          The input is two 
          The input is three

      この関数では、値をいくつでも使用できます。各値は、$args 配列の位置に代入さ
      れます。

  スイッチ パラメーター
      スイッチとは、値を必要としないパラメーターのことです。代わりに、関数名に続
      けてスイッチ パラメーターの名前を入力します。

      スイッチ パラメーターを定義するには、次の例に示すように、パラメーター名の
      前に「[switch]」と入力します。

          function switchExample {
              param ([switch]$on)
              if ($on) { "Switch on" }
              else { "Switch off" }
          }

      関数名の後に On スイッチ パラメーターを入力した場合、"Switch on" と表示さ
      れます。スイッチ パラメーターがない場合は、"Switch off" と表示されます。

          C:\PS> SwitchExample -on
          Switch on

          C:\PS> SwitchExample
          Switch off

      次の例に示すように、関数を実行する場合、スイッチにブール値を代入することも
      できます。

          C:\PS> SwitchExample -on:$true
          Switch on

          C:\PS> SwitchExample -on:$false
          Switch off

  関数へのオブジェクトのパイプ
      どの関数もパイプラインから入力を受け取ることができます。Begin、Process、お
      よび End キーワードを使用すると、パイプラインからの入力を関数で処理する方
      法を指定することができます。次の例の構文では、この 3 つのキーワードを使用
      します。

          function <name> {
              begin {<statement list>}
              process {<statement list>}
              end {<statement list>}
          }

      Begin ステートメント リストは、関数の開始時に 1 回のみ実行されます。

      Process ステートメント リストは、パイプライン内の各オブジェクトについて 1 
      回実行されます。Process ブロックの実行中は、一度にパイプライン オブジェク
      トが 1 つずつ $_ 自動変数に代入されます。

      関数がパイプライン内のすべてのオブジェクトを受け取った後、End ステートメン
      ト リストは 1 回実行されます。Begin、Process、または End キーワードを使用
      しない場合、すべてのステートメントは、End ステートメント リストの場合と同
      様に処理されます。

      次の関数では、Process キーワードを使用します。パイプラインからの例が表示さ
      れます。

          function pipelineFunction
          { 
              process {"The value is: $_"}
          }

      この関数を実行するには、次の例のように、コンマで区切った数字の配列を入力し
      ます。

          C:\PS> 1,2,4 | pipelineFunction
          The value is: 1
          The value is: 2
          The value is: 4

      パイプラインで関数を使用する場合は、パイプを介して関数に渡されるオブジェク
      トが $input 自動変数に代入されます。パイプラインからオブジェクトが取り出さ
      れる前に、Begin キーワードを持つステートメントが実行されます。関数がパイプ
      ラインからすべてのオブジェクトを受け取った後は、End キーワードを持つステー
      トメントが実行されます。

      次の例は、Begin キーワードと End キーワードを持った $input 自動変数を示し
      ています。

          function PipelineBeginEnd 
          {
              begin {"Begin: The input is $input"}
              end {"End:   The input is $input" }
          }

      パイプラインを使用してこの関数が実行されると、次の結果が表示されます。

          C:\PS> 1,2,4 | PipelineBeginEnd
          Begin: The input is
          End:   The input is 1 2 4

      Begin ステートメントが実行されるとき、関数にはパイプラインからの入力があり
      ません。関数が値を取得した後に、End ステートメントが実行されます。

      関数に Process キーワードがある場合、関数は $input のデータを読み取ります。
      次の例には、Process ステートメント リストがあります。

          function PipelineInput
          {
              process {"Processing:  $_ " }
              end {"End:   The input is: $input" }
          }

      この例では、パイプを介して関数に渡される各オブジェクトは、Process ステート
      メント リストに送られます。Process ステートメントは、一度に 1 オブジェクト
      ずつ、各オブジェクトについて実行されます。関数が End キーワードに達すると、
      $input 自動変数は空になります。

          C:\PS> 1,2,4 | PipelineInput
          Processing: 1
          Processing: 2
          Processing: 4
          End:   The input is:

  フィルター
      フィルターとは、パイプライン内の各オブジェクトについて実行される一種の関数
      のことです。フィルターは、すべてのステートメントが Process ブロック内にある
      関数と似ています。

      フィルターの構文は次のとおりです。

          filter [<scope:>]<name> {<statement list>}

      次のフィルターは、パイプラインからログ エントリを受け取り、エントリ全体また
      はエントリのメッセージ部分のみを表示します。

          filter ErrorLog ([switch]$message)
          {
              if ($message) { out-host -inputobject $_.Message }
              else { $_ }   
          }

  関数のスコープ
      関数は、自身が作成されたスコープ内に存在します。

      関数がスクリプトの一部である場合、この関数は、このスクリプト内のステートメ
      ントから利用できます。既定では、コマンド プロンプトからはスクリプト内の関
      数は利用できません。

      関数のスコープは指定することができます。たとえば、次の例では、関数がグロー
      バル スコープに追加されます。
 
          function global:get-dependentsvs { get-service |
             where {$_.dependentservices} }

      関数がグローバル スコープにある場合、この関数は、スクリプト、関数、および
      コマンド ラインで使用できます。

      通常、関数ではスコープが作成されます。関数に作成される変数などの項目は、関
      数のスコープ内にのみ存在します。

      Windows PowerShell でのスコープの詳細については、「about_Scope」を参照して
      ください。
        
  Function: ドライブを使用した、関数の検索および管理
      Windows PowerShell のすべての関数およびフィルターは、Function: ドライブに
      自動的に保存されます。このドライブは、Windows PowerShell の Function プロ
      バイダーによって公開されます。

      Function: ドライブを参照する場合、コンピューターの C または D ドライブを参
      照する場合と同様、Function の後にコロンを入力します。

      次のコマンドは、Windows PowerShell の現在のセッションのすべての関数を表示
      します。

          C:\PS>  dir function:

      関数のコマンドは、関数の定義プロパティのスクリプト ブロックとして保存され
      ます。たとえば、Windows PowerShell に付属の Help 関数のコマンドを表示する
      には、次のように入力します。

          (dir function:help).definition

      Function: ドライブの詳細については、「関数」を参照してください。

  新規セッションの関数の再利用
      Windows PowerShell のコマンド プロンプトで関数を入力すると、関数は現在のセ
      ッションの一部になります。この関数は、セッションが終了するまで利用できます。

      すべての Windows PowerShell セッションで関数を使用するには、関数を Windows 
      PowerShell プロファイルに追加します。プロファイルの詳細については、「about
      _Profiles」を参照してください。

      関数を Windows PowerShell スクリプト ファイルに保存することもできます。テキ
      スト ファイルに関数を記述し、このファイルに .ps1 ファイル名拡張子を付けて保
      存します。

  関数のヘルプの作成
    Get-Help コマンドレットは、関数、コマンドレット、プロバイダー、およびスクリプ
    トのヘルプを取得します。関数のヘルプを取得するには、Get-Help に続けて関数名を
    入力します。

    たとえば、MyDisks 関数のヘルプを取得するには、次のように入力します。

        get-help MyDisks

    次の 2 つの方法のうちいずれかを使用すると、関数のヘルプを作成することができ
    ます。

    --  関数のコメントベースのヘルプ

        コメントで特殊なキーワードを使用すると、ヘルプ トピックを作成できます。
        関数のコメントベースのヘルプを作成するには、コメントを関数本体の始めまた
        は終わり、あるいは function キーワードの前の行に配置する必要があります。
        コメントベースのヘルプの詳細については、「about_Comment_Based_Help」を参
        照してください。

    --  関数の XML ベースのヘルプ

        通常コマンドレットに作成するタイプのように、XML ベースのヘルプ トピックを
        作成します。ヘルプ トピックを複数の言語にローカライズする場合は、XML ベー
        スのヘルプが必要です。

        関数と XML ベースのヘルプ トピックを関連付けるには、.ExternalHelp ヘルプ 
        コメント キーワードを使用します。ExternalHelp キーワードの詳細については、
        「about_Comment_Based_Help」を参照してください。XML ベースのヘルプの詳細
        については、MSDN の「How to Write Cmdlet Help (コマンドレット ヘルプの記
        述方法)」を参照してください。

関連項目
    about_Automatic_Variables 
    about_Comment_Based_Help
    about_Functions_Advanced 
    about_Functions_CmdletBindingAttribute
    about_Parameters
    about_Profiles
    about_Scopes
    about_Script_Blocks
    Function (プロバイダー)
	
記事で解説しているパソコンの環境
 基本ソフト: Windows 7
 キーワード: Windows PowerShell、ヘルプ、HelpFile、about_functions
ご利用数: 1915784
感想・要望・問い合わせは こちら