about_Functions

[アーティクル]
03/13/2024

簡単な説明

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

詳細な説明

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

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

function Get-PowerShellProcess { Get-Process PowerShell }

関数は、コマンドレットやアプリケーションと同じくらい複雑な場合もあります。

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

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

関数のステートメントリストには、キーワード (keyword)begin、processおよび end. これらのステートメントリストは、パイプラインからの入力を異なる方法で処理します。

フィルターキーワード (keyword)は、パイプライン内の各オブジェクトで実行される関数の種類を作成するために使用されます。フィルターは、ブロック内のすべてのステートメントを含む関数に 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 キーワード (keyword)
スコープ (省略可能)
選択した名前
任意の数の名前付きパラメーター (省略可能)
中かっこで囲まれた 1 つ以上の PowerShell コマンド {}

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

入力処理メソッド

このセクションで説明するメソッドは、入力処理方法と呼ばれます。関数の場合、これら 3 つのメソッドは、関数の begin、 processおよび end ブロックによって表されます。

関数でこれらのブロックを使用する必要はありません。名前付きブロックを使用しない場合、PowerShell は関数のブロックにコードを end 配置します。ただし、これらの名前付きブロックのいずれかを使用する場合、またはブロックを定義する dynamicparam 場合は、すべてのコードを名前付きブロックに配置する必要があります。

次の例は、1 回限りの前処理用のブロック、複数のレコード処理用のブロック、processおよび 1 回限りの後処理用のブロックを含むbegin関数の概要を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 ブロック は実行されません 。
- 、end、およびcleanブロックはbegin引き続き実行されます。

重要

関数パラメーターがパイプライン入力を受け入れるように設定されていて、ブロックが 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 動詞の詳細については、「承認済み動詞」を参照してください。

パラメーターを持つ関数

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

名前付きパラメーター

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

次のサンプル構文に示すように、キーワード (keyword)をparam使用して中かっこ内のパラメーターを定義できます。

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

次のサンプル構文に示すように、キーワード (keyword)を使用せずに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 属性を追加し、PSDefaultValue の Help プロパティを指定することで、パラメーターの既定値を説明する簡単なヘルプ文字列を指定できます。関数の Size パラメーターの既定値 (100) を説明するヘルプ文字列をGet-SmallFiles指定するには、次の例に示すように 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 パラメーターの名前を入力します。

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

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

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

Splatting を使用してコマンドパラメーターを表す

スプラッティングを使用して、コマンドのパラメーターを表すことができます。この機能は、Windows PowerShell 3.0 で導入されています。

セッションでコマンドを呼び出す関数では、この手法を使用します。コマンドパラメーターを宣言または列挙したり、コマンドパラメーターが変更されたときに関数を変更したりする必要はありません。

次のサンプル関数は、コマンドレットを Get-Command 呼び出します。このコマンドは@ArgsGet-Command、.

function Get-MyCommand { Get-Command @Args }

関数を呼び出すときのすべてのパラメーター Get-Command を Get-MyCommand 使用できます。パラメーターとパラメーター値は、次を使用して @Argsコマンドに渡されます。

Get-MyCommand -Name Get-ChildItem

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

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

詳細については、「about_Splatting」を参照してください。

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

任意の関数がパイプラインから入力を受け取ることができます。関数がパイプラインからの入力を処理する方法は、 processend キーワード (keyword)を使用してbegin制御できます。次のサンプル構文は、これらのキーワード (keyword)を示しています。

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

次の関数では、キーワード (keyword)を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前に、キーワード (keyword)を使用してステートメントを実行します。この関数は、パイプラインからすべてのオブジェクトをend受信した後、キーワード (keyword)を使用してステートメントを実行します。

次の例は、自動変数と$inputbeginend キーワード (keyword)を示しています。

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 、関数に値が設定された後に実行されます。

関数にキーワード (keyword)があるprocess場合、各オブジェクト$inputは削除$inputされ、割り当てられます$_。次の例にはステートメントリストがあります process 。

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

この例では、関数にパイプされた各オブジェクトがステートメントリストに process 送信されます。ステートメントは process 、各オブジェクト (一度に 1 つのオブジェクト) で実行されます。関数が$inputキーワード (keyword)に達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 { $_ }
}

次のように使用できます。

Get-WinEvent -LogName System -MaxEvents 100 | Get-ErrorLog -Message

関数スコープ

関数が作成されるスコープに存在します。

関数がスクリプトの一部である場合、その関数はそのスクリプト内のステートメントで使用できます。既定では、スクリプト内の関数は、そのスクリプトの外部では使用できません。

関数のスコープを指定できます。たとえば、次の例では、関数がグローバルスコープに追加されます。

function global:Get-DependentSvs {
  Get-Service | Where-Object {$_.DependentServices}
}

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

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

詳細については、「about_Scopes」を参照してください。

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

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

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

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

Get-ChildItem function:

関数内のコマンドは、スクリプトブロックとして関数の定義プロパティに格納されます。たとえば、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 つの方法のいずれかを使用して、関数のヘルプを記述できます。

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

コメント内の特殊なキーワード (keyword)を使用してヘルプトピックを作成します。関数のコメントベースのヘルプを作成するには、コメントを関数本体の先頭または末尾、または関数のキーワード (keyword)の前の行に配置する必要があります。コメントベースのヘルプの詳細については、about_Comment_Based_Helpを参照してください。
関数の XML ベースのヘルプ

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

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

キーワード (keyword)の.EXTERNALHELP詳細については、「about_Comment_Based_Help」を参照してください。 XML ベースのヘルプの詳細については、「コマンドレットヘルプを記述する方法」を参照してください。

about_Functions

簡単な説明

詳細な説明

構文

入力処理メソッド

`begin`

`process`

`end`

単純な関数

関数名

パラメーターを持つ関数

名前付きパラメーター

位置指定パラメーター

パラメーターの切り替え

Splatting を使用してコマンドパラメーターを表す

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

フィルター

関数スコープ

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

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

関数のヘルプを記述する

関連項目

フィードバック

その他のリソース

about_Functions

簡単な説明

詳細な説明

構文

入力処理メソッド

begin

process

end

単純な関数

関数名

パラメーターを持つ関数

名前付きパラメーター

位置指定パラメーター

パラメーターの切り替え

Splatting を使用してコマンド パラメーターを表す

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

フィルター

関数スコープ

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

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

関数のヘルプを記述する

関連項目

フィードバック

その他のリソース

`begin`

`process`

`end`

Splatting を使用してコマンドパラメーターを表す