about_Functions
簡単な説明
PowerShell で関数を作成して使用する方法について説明します。
詳細な説明
関数は、割り当てる名前を持つ PowerShell ステートメントの一覧です。 関数を実行するときは、関数名を入力します。 リスト内のステートメントは、コマンド プロンプトで入力したかのように実行されます。
関数は、次のような単純なことができます。
function Get-PowerShellProcess { Get-Process pwsh }
関数が定義されたら、組み込みのコマンドレットと同様に使用できます。 たとえば、新しく定義された Get-PowerShellProcess
関数を呼び出すには、次のようにします。
Get-PowerShellProcess
NPM(K) PM(M) WS(M) CPU(s) Id SI ProcessName
------ ----- ----- ------ -- -- -----------
110 78.72 172.39 10.62 10936 1 pwsh
関数は、コマンドレットやアプリケーションと同じくらい複雑な場合もあります。
コマンドレットと同様に、関数にはパラメーターを指定できます。 パラメーターには、名前、位置、スイッチ、または動的パラメーターを指定できます。 関数パラメーターは、コマンド ラインまたはパイプラインから読み取ることができます。
関数は、表示、変数への割り当て、または他の関数またはコマンドレットに渡すことができる値を返すことができます。 return
キーワードを使用して戻り値を指定することもできます。 return
キーワードは、関数から返される他の出力には影響しません。 ただし、 return
キーワードは、その行で関数を終了します。 詳細については、「 about_Return」を参照してください。
関数のステートメント リストには、キーワード begin
、 process
、 end
を含むさまざまな種類のステートメント リストを含めることができます。 これらのステートメントリストは、パイプラインからの入力を異なる方法で処理します。
filter キーワードは、パイプライン内の各オブジェクトで実行される関数の型を作成するために使用されます。 フィルターは、 process
ブロック内のすべてのステートメントを含む関数に似ています。
関数はコマンドレットのように動作することもできます。 C#
プログラミングを使用せずに、コマンドレットと同じように動作する関数を作成できます。 詳細については、「 about_Functions_Advanced」を参照してください。
重要
スクリプト ファイルとスクリプト ベースのモジュール内では、関数を呼び出す前に定義する必要があります。
構文
関数の構文を次に示します。
function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
begin {<statement list>}
process {<statement list>}
end {<statement list>}
}
function [<scope:>]<name>
{
param([type]$parameter1 [,[type]$parameter2])
dynamicparam {<statement list>}
begin {<statement list>}
process {<statement list>}
end {<statement list>}
}
関数には、次の項目が含まれています。
function
キーワード- スコープ (省略可能)
- 選択した名前
- 任意の数の名前付きパラメーター (省略可能)
- 中かっこで囲まれた 1 つ以上の PowerShell コマンド
{}
関数の dynamicparam
キーワードと動的パラメーターの詳細については、 about_Functions_Advanced_Parametersを参照してください。
入力処理メソッド
このセクションで説明するメソッドは、入力処理方法と呼ばれます。 関数の場合、これら 3 つのメソッドは、関数の begin
、 process
、および end
ブロックによって表されます。
関数でこれらのブロックを使用する必要はありません。 名前付きブロックを使用しない場合、PowerShell は関数の end
ブロックにコードを配置します。 ただし、これらの名前付きブロックのいずれかを使用するか、 dynamicparam
ブロックを定義する場合は、すべてのコードを名前付きブロックに配置する必要があります。
次の例は、1 回限りの前処理用の begin
ブロック、複数レコード処理用の process
ブロック、および 1 回限りの後処理用の end
ブロックを含む関数の概要を示しています。
Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
Param ($Parameter1)
begin{}
process{}
end{}
}
begin
このブロックは、関数のオプションの 1 回限りの前処理を提供するために使用されます。 PowerShell ランタイムは、パイプライン内の関数のインスタンスごとに、このブロック内のコードを 1 回使用します。
process
このブロックは、関数のレコードごとの処理を提供するために使用されます。 他のブロックを定義せずに、 process
ブロックを使用できます。 process
ブロック実行の数は、関数の使用方法と、関数が受け取る入力によって異なります。
自動変数 $_
または $PSItem
には、 process
ブロックで使用するパイプライン内の現在のオブジェクトが含まれています。 $input
自動変数には、関数とスクリプト ブロックでのみ使用できる列挙子が含まれています。
詳細については、「about_Automatic_Variables」を参照してください。
- パイプラインの先頭または外側で関数を呼び出すと、
process
ブロックが 1 回実行されます。 - パイプライン内では、
process
ブロックは、関数に到達する入力オブジェクトごとに 1 回実行されます。 - 関数に到達したパイプライン入力が空の場合、
process
ブロック 実行されません 。begin
、end
、およびclean
ブロックは引き続き実行されます。
重要
パイプライン入力を受け入れるように関数パラメーターが設定されていて、 process
ブロックが定義されていない場合、レコードごとの処理は失敗します。 この場合、関数は入力に関係なく 1 回だけ実行されます。
end
このブロックは、関数のオプションの 1 回限りの後処理を提供するために使用されます。
単純な関数
関数を複雑にする必要はありません。 最も単純な関数の形式は次のとおりです。
function <function-name> {statements}
たとえば、次の関数は、 管理者として実行 オプションを使用して PowerShell を起動します。
function Start-PSAdmin {Start-Process PowerShell -Verb RunAs}
この関数を使用するには、次のように入力します。 Start-PSAdmin
関数にステートメントを追加するには、各ステートメントを個別の行に入力するか、セミコロン ;
を使用してステートメントを区切ります。
たとえば、次の関数は、開始日より後に変更された現在のユーザーのディレクトリ内のすべての .jpg
ファイルを検索します。
function Get-NewPix
{
$start = Get-Date -Month 1 -Day 1 -Year 2010
$allpix = Get-ChildItem -Path $env:UserProfile\*.jpg -Recurse
$allpix | Where-Object {$_.LastWriteTime -gt $Start}
}
便利な小さな関数のツールボックスを作成できます。 このトピックの後の about_Profiles で説明されているように、これらの関数を PowerShell プロファイルに追加します。
関数名
関数には任意の名前を割り当てることができますが、他のユーザーと共有する関数は、すべての PowerShell コマンドに対して確立されている名前付け規則に従う必要があります。
関数名は動詞と名詞のペアで構成する必要があります。動詞は関数が実行するアクションを識別し、名詞はコマンドレットがアクションを実行する項目を識別します。
関数では、すべての PowerShell コマンドで承認されている標準動詞を使用する必要があります。 これらの動詞は、コマンド名の一貫性を保ち、ユーザーが理解しやすくするのに役立ちます。
標準的な PowerShell 動詞の詳細については、「 Approved Verbs」を参照してください。
パラメーターを持つ関数
名前付きパラメーター、位置指定パラメーター、スイッチ パラメーター、動的パラメーターなど、関数でパラメーターを使用できます。 関数の動的パラメーターの詳細については、 about_Functions_Advanced_Parametersを参照してください。
名前付きパラメーター
任意の数の名前付きパラメーターを定義できます。 このトピックで後述するように、名前付きパラメーターの既定値を含めることができます。
次のサンプル構文に示すように、 param
キーワードを使用して中かっこ内のパラメーターを定義できます。
function <name> {
param ([type]$parameter1 [,[type]$parameter2])
<statement list>
}
次のサンプル構文に示すように、 Param
キーワードを指定せずに中かっこの外側にパラメーターを定義することもできます。
function <name> [([type]$parameter1[,[type]$parameter2])] {
<statement list>
}
この代替構文の例を次に示します。
function Add-Numbers([int]$one, [int]$two) {
$one + $two
}
最初の方法が推奨されますが、これら 2 つの方法に違いはありません。
関数を実行すると、パラメーターに指定した値が、パラメーター名を含む変数に割り当てられます。 その変数の値は、関数で使用できます。
次の例は、 Get-SmallFiles
と呼ばれる関数です。 この関数には、 $Size
パラメーターがあります。 この関数は、 $Size
パラメーターの値より小さいすべてのファイルを表示し、ディレクトリを除外します。
function Get-SmallFiles {
Param($Size)
Get-ChildItem $HOME | Where-Object {
$_.Length -lt $Size -and !$_.PSIsContainer
}
}
この関数では、パラメーターに定義されている名前である $Size
変数を使用できます。
この関数を使用するには、次のコマンドを入力します。
Get-SmallFiles -Size 50
パラメーター名を指定せずに名前付きパラメーターの値を入力することもできます。 たとえば、次のコマンドは、 Size パラメーターに名前を付けるコマンドと同じ結果になります。
Get-SmallFiles 50
パラメーターの既定値を定義するには、次の Get-SmallFiles
例に示すように、パラメーター名の後に等号と値を入力します。
function Get-SmallFiles ($Size = 100) {
Get-ChildItem $HOME | Where-Object {
$_.Length -lt $Size -and !$_.PSIsContainer
}
}
値を指定せずに Get-SmallFiles
を入力すると、 $size
に 100 が割り当てられます。 値を指定すると、関数はその値を使用します。
必要に応じて、パラメーターの説明に PSDefaultValue 属性を追加し、PSDefaultValue の Help プロパティを指定することで、パラメーターの既定値を説明する簡単なヘルプ文字列を指定できます。 Get-SmallFiles
関数の Size パラメーターの既定値 (100) を説明するヘルプ文字列を指定するには、次の例に示すように、PSDefaultValue 属性を追加します。
function Get-SmallFiles {
param (
[PSDefaultValue(Help = '100')]
$Size = 100
)
Get-ChildItem $HOME | Where-Object {
$_.Length -lt $Size -and !$_.PSIsContainer
}
}
PSDefaultValue 属性クラスの詳細については、「PSDefaultValue Attribute Membersを参照してください。
位置指定パラメーター
位置指定パラメーターは、パラメーター名のないパラメーターです。 PowerShell では、パラメーター値の順序を使用して、各パラメーター値を関数内のパラメーターに関連付けます。
位置指定パラメーターを使用する場合は、関数名の後に 1 つ以上の値を入力します。 位置指定パラメーター値は、 $args
配列変数に割り当てられます。
関数名の後の値は、 $args
配列の最初の位置 ( $args[0]
) に割り当てられます。
次の Get-Extension
関数は、指定したファイル名に .txt
ファイル名拡張子を追加します。
function Get-Extension {
$name = $args[0] + ".txt"
$name
}
Get-Extension myTextFile
myTextFile.txt
パラメーターの切り替え
スイッチは、値を必要としないパラメーターです。 代わりに、関数名の後に switch パラメーターの名前を入力します。
switch パラメーターを定義するには、次の例に示すように、パラメーター名の前に [switch]
型を指定します。
function Switch-Item {
param ([switch]$on)
if ($on) { "Switch on" }
else { "Switch off" }
}
関数名の後に On
switch パラメーターを入力すると、関数に Switch on
が表示されます。 switch パラメーターを指定しないと、 Switch off
が表示されます。
Switch-Item -on
Switch on
Switch-Item
Switch off
次の例に示すように、 Boolean 値をスイッチの実行時に割り当てることもできます。
Switch-Item -on:$true
Switch on
Switch-Item -on:$false
Switch off
Splatting を使用してコマンド パラメーターを表す
スプラッティングを使用して、コマンドのパラメーターを表すことができます。 この機能は、Windows PowerShell 3.0 で導入されています。
セッションでコマンドを呼び出す関数では、この手法を使用します。 コマンド パラメーターを宣言または列挙したり、コマンド パラメーターが変更されたときに関数を変更したりする必要はありません。
次のサンプル関数は、 Get-Command
コマンドレットを呼び出します。 このコマンドは、Get-Command
のパラメーターを表すために@Args
を使用します。
function Get-MyCommand { Get-Command @Args }
Get-MyCommand
関数を呼び出すときは、Get-Command
のすべてのパラメーターを使用できます。 パラメーターとパラメーター値は、 @Args
を使用してコマンドに渡されます。
Get-MyCommand -Name Get-ChildItem
CommandType Name ModuleName
----------- ---- ----------
Cmdlet Get-ChildItem Microsoft.PowerShell.Management
@Args
機能では、$Args
自動パラメーターを使用します。これは、宣言されていないコマンドレット パラメーターと残りの引数の値を表します。
詳細については、「 about_Splatting」を参照してください。
関数へのオブジェクトのパイプ処理
任意の関数がパイプラインから入力を受け取ることができます。 begin
、process
、およびend
キーワードを使用して、関数がパイプラインからの入力を処理する方法を制御できます。 次のサンプル構文は、これらのキーワードを示しています。
process
ステートメント リストは、パイプライン内のオブジェクトごとに 1 回実行されます。
process
ブロックの実行中、各パイプライン オブジェクトは、$_
自動変数 (一度に 1 つのパイプライン オブジェクト) に割り当てられます。
次の関数では、 process
キーワードを使用します。 この関数は、パイプラインの値を表示します。
function Get-Pipeline
{
process {"The value is: $_"}
}
1,2,4 | Get-Pipeline
The value is: 1
The value is: 2
The value is: 4
パラメーターからパイプライン入力または入力を受け取ることができる関数が必要な場合は、 process
ブロックで両方のケースを処理する必要があります。 次に例を示します。
function Get-SumOfNumbers {
param (
[int[]]$Numbers
)
begin { $retValue = 0 }
process {
if ($null -ne $Numbers) {
foreach ($n in $Numbers) {
$retValue += $n
}
} else {
$retValue += $_
}
}
end { $retValue }
}
PS> 1,2,3,4 | Get-SumOfNumbers
10
PS> Get-SumOfNumbers 1,2,3,4
10
パイプラインで関数を使用すると、関数にパイプされたオブジェクトが $input
自動変数に割り当てられます。 この関数は、パイプラインからオブジェクトが取得される前に、 begin
キーワードを使用してステートメントを実行します。 この関数は、パイプラインからすべてのオブジェクトを受信した後、 end
キーワードを使用してステートメントを実行します。
次の例は、begin
キーワードとend
キーワードを含む$input
自動変数を示しています。
function Get-PipelineBeginEnd {
begin { "Begin: The input is $input" }
end { "End: The input is $input" }
}
パイプラインを使用してこの関数を実行すると、次の結果が表示されます。
1,2,4 | Get-PipelineBeginEnd
Begin: The input is
End: The input is 1 2 4
begin
ステートメントを実行すると、関数にはパイプラインからの入力がありません。 end
ステートメントは、関数が値を持った後に実行されます。
関数に process
キーワードがある場合、 $input
内の各オブジェクトは $input
から削除され、 $_
に割り当てられます。 次の例には、 process
ステートメント の一覧があります。
function Get-PipelineInput
{
process {"Processing: $_ " }
end {"End: The input is: $input" }
}
この例では、関数にパイプされた各オブジェクトが、 process
ステートメント リストに送信されます。 process
ステートメントは、各オブジェクト (一度に 1 つのオブジェクト) で実行されます。 関数が end
キーワードに達すると、$input
自動変数は空になります。
1,2,4 | Get-PipelineInput
Processing: 1
Processing: 2
Processing: 4
End: The input is:
詳細については、「 列挙子の使用」を参照してください。
フィルター
フィルターは、パイプライン内の各オブジェクトで実行される関数の一種です。 フィルターは、 process
ブロック内のすべてのステートメントを含む関数に似ています。
フィルターの構文は次のとおりです。
filter [<scope:>]<name> {<statement list>}
次のフィルターは、パイプラインからログ エントリを取得し、エントリ全体またはエントリのメッセージ部分のみを表示します。
filter Get-ErrorLog ([switch]$Message)
{
if ($Message) { Out-Host -InputObject $_.Message }
else { $_ }
}
次のように使用できます。
Get-WinEvent -LogName System -MaxEvents 100 | Get-ErrorLog -Message
関数スコープ
関数が作成されるスコープに存在します。
関数がスクリプトの一部である場合、その関数はそのスクリプト内のステートメントで使用できます。 既定では、スクリプト内の関数は、そのスクリプトの外部では使用できません。
関数のスコープを指定できます。 たとえば、次の例では、関数がグローバル スコープに追加されます。
function global:Get-DependentSvs {
Get-Service | Where-Object {$_.DependentServices}
}
関数がグローバル スコープ内にある場合は、スクリプト、関数、およびコマンド ラインで関数を使用できます。
関数は新しいスコープを作成します。 変数などの関数で作成された項目は、関数スコープにのみ存在します。
詳細については、「 about_Scopes」を参照してください。
関数を使用した関数の検索と管理: ドライブ
PowerShell のすべての関数とフィルターは、 Function:
ドライブに自動的に格納されます。 このドライブは、PowerShell Function プロバイダーによって公開されます。
Function:
ドライブを参照する場合は、コンピューターのC
またはD
ドライブを参照する場合と同様に、Function の後にコロンを入力します。
次のコマンドは、PowerShell の現在のセッションのすべての関数を表示します。
Get-ChildItem function:
関数内のコマンドは、スクリプト ブロックとして関数の定義プロパティに格納されます。 たとえば、PowerShell に付属するヘルプ関数にコマンドを表示するには、次のように入力します。
(Get-ChildItem function:help).Definition
次の構文を使用することもできます。
$function:help
Function:
ドライブの詳細については、Function プロバイダーのヘルプ トピックを参照してください。 「Get-Help Function
」と入力します。
新しいセッションでの関数の再利用
PowerShell コマンド プロンプトで関数を入力すると、関数は現在のセッションの一部になります。 この関数は、セッションが終了するまで使用できます。
すべての PowerShell セッションで関数を使用するには、PowerShell プロファイルに関数を追加します。 プロファイルの詳細については、「about_Profiles」を参照してください。
関数を PowerShell スクリプト ファイルに保存することもできます。 テキスト ファイルに関数を入力し、ファイル名拡張子を .ps1
してファイルを保存します。
関数のヘルプを記述する
Get-Help
コマンドレットは、関数、およびコマンドレット、プロバイダー、スクリプトに関するヘルプを取得します。 関数のヘルプを取得するには、 Get-Help
を入力し、その後に関数名を入力します。
たとえば、 Get-MyDisks
関数のヘルプを取得するには、次のように入力します。
Get-Help Get-MyDisks
次の 2 つの方法のいずれかを使用して、関数のヘルプを記述できます。
関数のコメント ベースのヘルプ
コメント内の特別なキーワードを使用してヘルプ トピックを作成します。 関数のコメントベースのヘルプを作成するには、コメントを関数本体の先頭または末尾、または関数キーワードの前の行に配置する必要があります。 コメントベースのヘルプの詳細については、 about_Comment_Based_Helpを参照してください。
関数の XML ベースのヘルプ
通常はコマンドレット用に作成される型など、XML ベースのヘルプ トピックを作成します。 ヘルプ トピックを複数の言語にローカライズする場合は、XML ベースのヘルプが必要です。
関数を XML ベースのヘルプ トピックに関連付けるには、コメントベースのヘルプ キーワード
.EXTERNALHELP
使用します。 このキーワードがないと、Get-Help
関数のヘルプ トピックが見つからず、関数のGet-Help
呼び出しでは自動生成されたヘルプのみが返されます。.EXTERNALHELP
キーワードの詳細については、about_Comment_Based_Helpを参照してください。 XML ベースのヘルプの詳細については、「 コマンドレット ヘルプを記述する方法を参照してください。
関連項目
- about_Automatic_Variables
- about_Comment_Based_Help
- about_Function_Provider
- about_Functions_Advanced
- about_Functions_Advanced_Methods
- about_Functions_Advanced_Parameters
- about_Functions_CmdletBindingAttribute
- about_Functions_OutputTypeAttribute
- about_Parameters
- about_Profiles
- about_Scopes
- about_Script_Blocks
PowerShell