トピック
about_Functions
簡易説明
Windows PowerShell で関数を作成および使用する方法について説明します。
詳細説明
関数とは、名前を割り当てられたステートメント リストのことです。関数を実行する場合は、関数名を入
力します。リスト内のステートメントは、コマンド プロンプトで入力した場合と同じように実行されます。
コマンドレットと同様、関数にはパラメーターを指定できます。パラメーターは、名前付きパラメーター、
位置指定パラメーター、スイッチ パラメーター、または動的パラメーターにすることができます。関数パラ
メーターは、コマンド ラインまたはパイプラインから読み取ることができます。
関数は値を返すことができ、その値は、表示、変数への代入、または他の関数やコマンドレットに渡すことが可能です。
関数のステートメント リストには、さまざまなステートメント リストを、Begin、Process、および
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 に代入されます。値を指定すると、関数では
その値が使用されます。
位置指定パラメーター
位置指定パラメーターとは、パラメーター名のないパラメーターのことです。Windows 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 (プロバイダー)