about_Functions
適用対象: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0
トピック
about_Functions
概要
Windows PowerShell® で関数を作成して使用する方法について説明します。
詳細説明
関数とは、ユーザーによって名前が付けられた Windows PowerShell ステートメントのリストです。関数を実行する場合は、関数名を入力します。リスト内のステートメントは、コマンド プロンプトでステートメントを入力した場合と同じように実行されます。
関数は、次のように簡単に記述できます。
function Get-PowerShellProcess {Get-Process PowerShell}
また、コマンドレットやアプリケーション プログラムのように複雑な関数も記述できます。
関数は、コマンドレットと同様にパラメーターを受け取ることができます。パラメーターには、名前付きパラメーター、位置指定パラメーター、スイッチ パラメーター、動的パラメーターを指定できます。関数パラメーターは、コマンド ラインまたはパイプラインから読み取ることができます。
関数は値を返すことができ、返された値は、表示したり、変数に代入したりできるほか、他の関数やコマンドレットに渡すことができます。
関数のステートメント リストには、さまざまな種類のステートメント リストを、Begin、Process、End というキーワードと共に含めることができます。これらのステートメント リストは、パイプラインからの入力を別の方法で処理します。
フィルターは、Filter キーワードを使用する特殊な関数です。
関数は、コマンドレットのように動作することもできます。C# プログラミングを使用せずに、コマンドレットと同じように動作する関数を作成できます。詳細については、「about_Functions_Advanced」(https://go.microsoft.com/fwlink/?LinkID=144511) を参照してください。
構文
関数の構文は次のとおりです。
function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
param([type]$parameter1 [,[type]$parameter2])
dynamicparam {<statement list>}
begin {<statement list>}
process {<statement list>}
end {<statement list>}
}
関数には、次の項目が含まれます。
- A Function keyword
- A scope (optional)
- A name that you select
- Any number of named parameters (optional)
- One or more Windows PowerShell commands enclosed in braces ({})
関数の Dynamicparam キーワードと動的パラメーターの詳細については、「about_Functions_Advanced_Parameters」を参照してください。
単純な関数
関数は、複雑にしなくても役に立ちます。最も単純な関数の形式は次のとおりです。
function <function-name> {statements}
たとえば、次の関数は、Windows 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 {$_.LastWriteTime -gt $Start}
}
少量の便利な関数のツールボックスを作成できます。「about_Profiles」とこのトピックの後半の説明に従って、これらの関数を Windows PowerShell プロファイルに追加します。
関数名
関数には任意の名前を割り当てることができますが、他のユーザーと共有する関数については、すべての Windows PowerShell コマンド用に確立されている命名規則に従う必要があります。
関数名は、動詞と名詞のペアで構成する必要があります。この場合、動詞は、関数が実行するアクションを示し、名詞は、コマンドレットによって実行されるそのアクションの対象となる項目を示します。
関数では、すべての Windows PowerShell コマンドに承認されている標準的な動詞を使用する必要があります。これらの動詞を使用することで、コマンド名は、ユーザーにとってわかりやすい、シンプルで一貫性のある名前になります。
標準的な Windows PowerShell 動詞の詳細については、MSDN のコマンドレットの動詞に関する記事 (https://go.microsoft.com/fwlink/?LinkID=160773) を参照してください。
パラメーターを使用した関数
関数では、名前付きパラメーター、位置指定パラメーター、スイッチ パラメーター、動的パラメーターなどのパラメーターを使用できます。関数の動的パラメーターの詳細については、「about_Functions_Advanced_Parameters」(https://go.microsoft.com/fwlink/?LinkID=135173) を参照してください。
名前付きパラメーター
任意の数の名前付きパラメーターを定義できます。このトピックの後半で説明するように、名前付きパラメーターの既定値を含めることができます。
次のサンプル構文に示すように、パラメーターは、Param キーワードを使用して、中かっこの中で定義できます。
function <name> {
param ([type]$parameter1[,[type]$parameter2])
<statement list>
}
また、次のサンプル構文に示すように、Param キーワードを使用せずに中かっこの外側でパラメーターを定義することもできます。
function <name> [([type]$parameter1[,[type]$parameter2])] {
<statement list>
}
これら 2 つの方法に違いはありません。好みに合った方法を使用してください。
関数を実行すると、パラメーターに指定した値が、パラメーター名を含む変数に代入されます。その変数の値は関数で使用できます。
Get-SmallFiles という名前の関数の例を次に示します。この関数には、$size パラメーターがあります。この関数は、$size パラメーターの値より小さいファイルをすべて表示し、ディレクトリを除外します。
function Get-SmallFiles {
param ($size)
Get-ChildItem c:\ | where {$_.Length -lt $Size -and !$_.PSIsContainer}
}
この関数では、パラメーターに定義された名前である $size 変数を使用できます。
この関数を使用するには、次のコマンドを入力します。
C:\PS> function Get-SmallFiles –Size 50
パラメーター名を指定せずに名前付きパラメーターの値を入力することもできます。たとえば、次のコマンドでは、Size パラメーターを指定するコマンドと同じ結果になります。
C:\PS> function Get-SmallFiles 50
パラメーターの既定値を定義するには、次の Get-SmallFiles の例に示すように、パラメーター名に続けて等号 (=) と値を入力します。
function Get-SmallFiles ($size = 100) {
Get-ChildItem c:\ | where {$_.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
)
PSDefaultValue 属性クラスの詳細については、MSDN の PSDefaultValue 属性メンバーに関するページ (https://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute\_members(v=vs.85).aspx) を参照してください。
位置指定パラメーター
位置指定パラメーターとは、パラメーター名を持たないパラメーターです。Windows PowerShell では、パラメーター値の順序を使用して、関数内のパラメーターに各パラメーター値を関連付けます。
位置指定パラメーターを使用する場合は、関数名の後に 1 つ以上の値を入力します。位置パラメーターの値は、$args 配列変数に代入されます。関数名に続く値は、$args 配列の最初の位置 $args[0] に代入されます。
次の Get-Extension 関数は、指定した名前のファイルに .txt ファイル名拡張子を追加します。
function Get-Extension {
$name = $args[0] + ".txt"
$name
}
C:\PS> Get-Extension myTextFile
myTextFile.txt
スイッチ パラメーター
スイッチとは、値を必要としないパラメーターです。代わりに、関数名の後にスイッチ パラメーターの名前を入力します。
スイッチ パラメーターを定義するには、次の例に示すように、パラメーター名の前に型 [switch] を指定します。
function Switch-Item {
param ([switch]$on)
if ($on) { "Switch on" }
else { "Switch off" }
}
関数名の後に On スイッチ パラメーターを入力した場合は、"Switch on" と表示されます。スイッチ パラメーターを指定しない場合は、"Switch off" と表示されます。
C:\PS> Switch-Item -on
Switch on
C:\PS> Switch-Item
Switch off
関数を実行するときに、スイッチにブール値を代入することもできます。次に例を示します。
C:\PS> Switch-Item -on:$true
Switch on
C:\PS> Switch-Item -on:$false
Switch off
スプラッティングを使用したコマンド パラメーターの表現
スプラッティングでコマンドのパラメーターを表すことができます。この機能は Windows PowerShell 3.0 で導入されました。
この手法は、セッション内でコマンドを呼び出す関数で使用します。コマンドのパラメーターを宣言または列挙する必要はありません。また、コマンドのパラメーターを変更するときに関数を変更する必要もありません。
次のサンプル関数は、Get-Command コマンドレットを呼び出します。このコマンドでは、@Args を使用して Get-Command のパラメーターを表します。
function Get-MyCommand { Get-Command @Args }
Get-MyCommand 関数を呼び出すときに、Get-Command のすべてのパラメーターを使用できます。パラメーターとパラメーター値は、@Args を使用してコマンドに渡されます。
PS C:\>Get-MyCommand -Name Get-ChildItem
CommandType Name ModuleName
----------- ---- ----------
Cmdlet Get-ChildItem Microsoft.PowerShell.Management
@Args 機能では、$Args 自動パラメーターを使用します。これにより、残りの引数から宣言されていないコマンドレット パラメーターと値が表示されます。
スプラッティングの詳細については、「about_Splatting」(https://go.microsoft.com/fwlink/?LinkId=262720) を参照してください。
オブジェクトを関数に渡すためのパイプ処理
どの関数でも、パイプラインから入力を受け取ることができます。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 Get-Pipeline
{
process {"The value is: $_"}
}
この関数の動作を示すために、次の例に示すように、数字のリストをコンマで区切って入力します。
C:\PS> 1,2,4 | Get-Pipeline
The value is: 1
The value is: 2
The value is: 4
パイプライン内で関数を使用すると、パイプを使用して関数に渡されたオブジェクトが $input 自動変数に代入されます。この関数では、パイプラインからオブジェクトを受け取る前に、Begin キーワードを使用したステートメントが実行されます。すべてのオブジェクトをパイプラインから受け取ったら、End キーワードを使用したステートメントが実行されます。
次の例では、Begin キーワードと End キーワードを使用した $input 自動変数を示しています。
function Get-PipelineBeginEnd
{
begin {"Begin: The input is $input"}
end {"End: The input is $input" }
}
パイプラインを使用してこの関数を実行した場合、次の結果が表示されます。
C:\PS> 1,2,4 | Get-PipelineBeginEnd
Begin: The input is
End: The input is 1 2 4
Begin ステートメントが実行されると、パイプラインから関数への入力はありません。End ステートメントは、関数が値を取得した後に実行されます。
関数に Process キーワードを指定した場合は、$input 内のデータが読み取られます。次の例には、Process ステートメント リストがあります。
function Get-PipelineInput
{
process {"Processing: $_ " }
end {"End: The input is: $input" }
}
この例では、パイプを使用して関数に渡された各オブジェクトは、Process ステートメント リストに送信されます。Process ステートメントは、各オブジェクトに対して 1 回ずつ実行されます。関数が End キーワードに到達した時点で、$input 自動変数は空になります。
C:\PS> 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 { $_ }
}
関数スコープ
関数は、その関数が作成されたスコープ内に存在します。
関数がスクリプトの一部である場合、その関数はそのスクリプト内のステートメントで使用できます。既定では、スクリプト内の関数をコマンド プロンプトで使用することはできません。
関数のスコープは指定することができます。たとえば、次の例では、グローバル スコープに関数を追加しています。
function global:Get-DependentSvs { Get-Service |
where {$_.DependentServices} }
関数がグローバル スコープにある場合、スクリプト、関数、およびコマンド ラインでその関数を使用できます。
通常は、関数によってスコープが作成されます。関数内で作成された項目 (変数など) は、その関数スコープ内のみに存在します。
Windows PowerShell のスコープの詳細については、「about_Scopes」(https://go.microsoft.com/fwlink/?LinkID=113260) を参照してください。
Function: ドライブを使用した関数の検索と管理ドライブのコンテンツの表示
Windows PowerShell のすべての関数およびフィルターは、自動的に Function: ドライブに格納されます。このドライブは、Windows PowerShell Function プロバイダーによって公開されます。
Function: ドライブを参照する場合は、コンピューターの C ドライブまたは D ドライブを参照する場合と同様に、Function の後にコロンを入力します。
次のコマンドは、Windows PowerShell の現在のセッション内のすべての関数を表示します。
Get-ChildItem function:
関数内のコマンドは、関数の定義プロパティ内にスクリプト ブロックとして保存されます。たとえば、Windows PowerShell に付属する Help 関数のコマンドを表示するには、次のように入力します。
(Get-ChildItem function:help).Definition
Function: ドライブの詳細については、Function プロバイダーのヘルプ トピックを参照してください。「Get-Help Function」と入力するか、TechNet ライブラリ (https://go.microsoft.com/fwlink/?LinkID=113436) を参照してください。
新しいセッションでの関数の再利用
Windows PowerShell コマンド プロンプトで関数を入力すると、その関数は現在のセッションの一部となります。この関数は、セッションが終了するまで使用できます。
すべての Windows PowerShell セッションで関数を使用するには、関数を Windows PowerShell プロファイルに追加します。プロファイルの詳細については、「about_Profiles」(https://go.microsoft.com/fwlink/?LinkID=113729) を参照してください。
また、関数を Windows 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 ベースのヘルプの詳細については、MSDN のコマンドレットのヘルプの記述方法に関するページを参照してください。
関連項目
about_Automatic_Variables
about_Comment_Based_Help
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
関数 (プロバイダー)