about_Functions

簡単な説明

PowerShell で関数を作成して使用する方法について説明します。

長い説明

関数とは、割り当てた名前を持つ PowerShell ステートメントの一覧です。 関数を実行するときは、関数名を入力します。 リスト内のステートメントは、コマンドプロンプトで入力した場合と同じように実行されます。

関数は、次のような単純なものにすることができます。

function Get-PowerShellProcess { Get-Process PowerShell }

関数は、コマンドレットまたはアプリケーションプログラムと同じように複雑にすることもできます。

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

関数は、表示、変数への代入、または他の関数やコマンドレットに渡すことができる値を返すことができます。 キーワードを使用して return 戻り値を指定することもできます。 returnキーワードは、関数から返される他の出力には影響しません。 ただし、キーワードは return その行の関数を終了します。 詳細については、「 about_Return」を参照してください。

関数のステートメントリストには、キーワード Begin Process 、、および End を使用して、さまざまな種類のステートメントリストを含めることができます。 これらのステートメントでは、パイプラインからの入力の処理方法が異なります。

フィルターは、キーワードを Filter 使用する特別な種類の関数です。

関数は、コマンドレットのように機能することもできます。 プログラミングを使用 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」を参照してください。

単純な関数

関数は、役に立つために複雑である必要はありません。 最も単純な関数の形式は次のとおりです。

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}
}

便利な小さい関数のツールボックスを作成できます。 これらの関数を PowerShell プロファイルに追加します。詳細については、このトピックの「 about_Profiles 」を参照してください。

関数名

関数には任意の名前を割り当てることができますが、他のユーザーと共有する関数は、すべての PowerShell コマンドに対して設定されている名前付け規則に従う必要があります。

関数名は、動詞と名詞のペアで構成されている必要があります。動詞は、関数が実行するアクションを識別し、名詞は、コマンドレットがアクションを実行する項目を識別します。

関数は、すべての PowerShell コマンドに対して承認された標準動詞を使用する必要があります。 これらの動詞を使用すると、コマンド名を簡単かつ一貫性のあるものにし、ユーザーが理解しやすいものにすることができます。

標準の PowerShell 動詞の詳細については、「Microsoft Docs での承認された 動詞 」を参照してください。

パラメーターを持つ関数

パラメーターには、名前付きパラメーター、位置指定パラメーター、スイッチパラメーター、動的パラメーターなどの関数を使用できます。 関数の動的パラメーターの詳細については、「 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 すると、関数は100をに $size 割り当てます。 値を指定した場合、関数はその値を使用します。

必要に応じて、パラメーターの既定値を説明する簡単なヘルプ文字列を指定できます。これには、パラメーターの説明に psdefaultvalue 属性を追加し、 Psdefaultvaluehelp プロパティを指定します。 関数の Size パラメーター Get-SmallFiles の既定値 (100) を説明するヘルプ文字列を指定するには、次の例に示すように psdefaultvalue 属性を追加します。

function Get-SmallFiles {
  param (
      [PSDefaultValue(Help = '100')]
      $Size = 100
  )
}

Psdefaultvalue 属性クラスの詳細については、「 Psdefaultvalue 属性のメンバー」を参照してください。

位置指定パラメーター

位置指定パラメーターは、パラメーター名のないパラメーターです。 PowerShell では、パラメーター値の順序を使用して、各パラメーター値を関数のパラメーターに関連付けます。

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

Get-Extension の関数は、指定したファイル名にファイル名拡張子を追加 .txt します。

function Get-Extension {
  $name = $args[0] + ".txt"
  $name
}
Get-Extension myTextFile
myTextFile.txt

スイッチパラメーター

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

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

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

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

Switch-Item -on
Switch on
Switch-Item
Switch off

次の例に示すように、関数を実行するときに、スイッチに ブール 値を割り当てることもできます。

Switch-Item -on:$true
Switch on
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 コマンドに渡されます。

Get-MyCommand -Name Get-ChildItem
CommandType     Name                ModuleName
-----------     ----                ----------
Cmdlet          Get-ChildItem       Microsoft.PowerShell.Management

この機能は @Args 自動パラメーターを使用 $Args します。これは、宣言されていないコマンドレットパラメーターと残りの引数の値を表します。

スプラッティングの詳細については、「 about_Splatting」を参照してください。

関数へのオブジェクトのパイプ処理

どの関数でも、パイプラインから入力を受け取る可能性があります。 、、および キーワードを使用して、関数 Beginがパイプラインからの入力を処理する方法 ProcessEnd 制御できます。 次のサンプル構文は、3 つのキーワードを示しています。

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

ステートメント Begin リストは、関数の先頭で 1 回だけ実行されます。

重要

関数で 、または ブロックがBegin``Process定義されているEnd場合は、すべてのコードがそれらのブロック内に存在する必要があります。 ブロックが定義されている場合、ブロックの外部 では コードは認識されません。

ステートメント Process リストは、パイプライン内のオブジェクトごとに 1 回実行されます。 ブロックの Process 実行中は、各パイプライン オブジェクトが自動 $_ 変数 (一度に 1 つのパイプライン オブジェクト) に割り当てられます。

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

次の関数では、 キーワードを使用 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

パイプラインで関数を使用すると、関数にパイプされたオブジェクトが自動変数に割り当 $input てられます。 関数は、 キーワードを指定して ステートメント Begin を実行してから、パイプラインからオブジェクトを受け取る必要があります。 関数は、すべてのオブジェクトがパイプラインから受信 End された後に、 キーワードを使用して ステートメントを実行します。

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

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 つのオブジェクトで実行されます。 関数 $input が キーワードに到達すると、自動変数は空 End になります。

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-Object {$_.DependentServices}
}

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

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

PowerShell のスコープの詳細については、PowerShell のスコープに関するページ about_Scopes

関数を使用した関数の検索と管理: ドライブ

PowerShell のすべての関数とフィルターは、ドライブに自動的に格納 Function: されます。 このドライブは、PowerShell 関数プロバイダーによって 公開 されます。

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

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

Get-ChildItem function:

関数内のコマンドは、関数の definition プロパティにスクリプト ブロックとして格納されます。 たとえば、PowerShell に付属するヘルプ関数にコマンドを表示するには、次のコマンドを入力します。

(Get-ChildItem function:help).Definition

次の構文を使用することもできます。

$function:help

ドライブの詳細については、関数 Function: プロバイダーのヘルプ トピックを 参照 してください。 「Get-Help Function.

新しいセッションでの関数の再利用

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

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

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

関数のヘルプの記述

コマンドレット Get-Help は、関数とコマンドレット、プロバイダー、およびスクリプトのヘルプを取得します。 関数のヘルプを表示するには、「」と入力し Get-Help 、その後に関数名を入力します。

たとえば、関数のヘルプを表示するには、次 Get-MyDisks のコマンドを入力します。

Get-Help Get-MyDisks

次の 2 つのメソッドのいずれかを使用して、関数のヘルプを記述できます。

  • Comment-Basedのヘルプ

    コメントで特別なキーワードを使用して、ヘルプ トピックを作成します。 関数のコメント ベースのヘルプを作成するには、コメントを関数本体の先頭または末尾、または function キーワードの前の行に配置する必要があります。 コメント ベースのヘルプの詳細については、「コメント ベースのヘルプ」を about_Comment_Based_Help

  • XML-Basedのヘルプ

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

    関数を XML ベースのヘルプ トピックに関連付けるには、コメント ベースの .ExternalHelp ヘルプ キーワードを使用します。 このキーワードを指定しない場合、 Get-Help は関数のヘルプ トピックを見つからず Get-Help 、 を呼び出して関数に対して を呼び出した場合は、自動生成されたヘルプのみを返します。

    キーワードの詳細については、「 ExternalHelp about_Comment_Based_Help」 を参照してください。 XML ベースのヘルプの詳細については、「 How to Write Cmdlet Help」を参照してください

関連項目