【PowerShell】関数(function)の使い方を超解説

PowerShellでの関数の使い方を解説していきます。
関数とはモジュールとも呼ばれ、特定のタスクや操作を実行するために設計された箱のようなものです。
関数は再利用可能で、コードの構造を整理し、保守性を向上させるのに役立ち、様々な形で宣言および呼び出しができます。

※このページに掲載されいているプログラムは、PowerShellのバージョン：5.1.19041.3693 にて動作確認済みです。

PowerShellの関数

テーブルの上に座っているおもちゃのレコードプレーヤー

関数の基本構文

以下はPowerShellにおける関数の基本構造です。

function 関数名 {
　　param (
　　　　#ここに関数内で使用する変数を宣言する
　　　　#複数記載する場合はカンマ(,)を忘れずに
　　)
　　#ここから関数内でやりたい処理を記載します
　　return 変数
}

function 関数名 {

　　param (

　　　　#ここに関数内で使用する変数を宣言する

　　　　#複数記載する場合はカンマ(,)を忘れずに

　　)

　　#ここから関数内でやりたい処理を記載します

　　return 変数

}

param内に記載した変数は関数外では値を取得できない。
引数が不要な関数の場合、paramの記載は不要。
関数処理後、返したい変数をreturnで指定する。
return後記載の処理は処理されない。
処理を関数化しておくことで、修正する箇所を1か所で済ませられる。

メモ

関数の呼び出しの基本構文

PowerShellにおける、関数の呼び出し方です。

関数名 引数1 引数2　...

1	関数名引数1 引数2　...

メモ

関数内でparam内に記載した変数分、引数として指定。
関数と引数、引数と引数は半角スペースで開ける。

関数と関数呼び出しの使用例

# C:\Sample1.ps1
function Get-Sum {
　　param (
　　　　[int]$a, #関数内変数を複数指定する場合、カンマが必要
　　　　[int]$b
　　)
　　$result = $a + $b
　　return $result


　　#以下処理はreturn後なので、処理されない
　　Write-Host "returnの後に記載"
}

Get-Sum 1 2
#関数内の変数を関数外から呼び出そうとしているので、何も表示されない
Write-Host $a

# C:\Sample1.ps1

function Get-Sum {

　　param (

　　　　[int]$a, #関数内変数を複数指定する場合、カンマが必要

　　　　[int]$b

　　)

　　$result = $a + $b

　　return $result

　　#以下処理はreturn後なので、処理されない

　　Write-Host "returnの後に記載"

}

Get-Sum 1 2

#関数内の変数を関数外から呼び出そうとしているので、何も表示されない

Write-Host $a

実行結果

PS　C:> ./Sample1.ps1
3

1 2	PS　C:> ./Sample1.ps1 3

ちなみに上記関数の呼び出しの際に引数に空白を指定した場合、int型であればゼロ、String型であれば空白で認識されます。

引数の初期化

関数呼び出し時に引数を空白を指定した場合、ゼロもしくは空白で認識されたくない際は、引数の初期値（デフォルト値）を指定すれば、空白時に指定の値を代入することができます。

# C:\Sample2.ps1
function Get-Sum {
　　param (
　　　　[int]$a = 1, #初期値を指定
　　　　[int]$b = 2
　　)
　　$result = $a + $b
　　return $result
}

Get-Sum 1 #引数をあえて１つにしている

# C:\Sample2.ps1

function Get-Sum {

　　param (

　　　　[int]$a = 1, #初期値を指定

　　　　[int]$b = 2

　　)

　　$result = $a + $b

　　return $result

}

Get-Sum 1 #引数をあえて１つにしている

実行結果

PS　C:> ./Sample2.ps1
3

1 2	PS　C:> ./Sample2.ps1 3

また引数はparamで指定する方法と、関数の後ろにカッコで囲むことでも指定可能です。

function Get-Sum([int]$a = 1, [int]$b = 2) {
　　$result = $a + $b
　　return $result
}

function Get-Sum([int]$a = 1, [int]$b = 2) {

　　$result = $a + $b

　　return $result

}

関数内の標準出力について

壊れやすい箱を持っている人

PowerShellの関数内でechoやWrite-Hostなどコンソールに文字を表示させる処理を関数内に記載すると、関数を呼び出すたびに表示されてしまいます。
例として、指定した場所に空のファイルを作成する関数を見てみましょう。

# C:\Sample3.ps1
function New-EmptyFile {
　　param (
　　　　[string]$filePath
　　)
　　# ファイルを作成
　　New-Item -Path $filePath -ItemType File
　　Write-Host "ファイルの作成が完成しました。"
}

New-EmptyFile -filePath "C:\Example.txt"

# C:\Sample3.ps1

function New-EmptyFile {

　　param (

　　　　[string]$filePath

　　)

　　# ファイルを作成

　　New-Item -Path $filePath -ItemType File

　　Write-Host "ファイルの作成が完成しました。"

}

New-EmptyFile -filePath "C:\Example.txt"

実行結果

PS　C:> ./Sample3.ps1

ディレクトリ: C:

Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 2023/11/24 15:08 0 Example.txt
ファイルの作成が完成しました。

PS　C:> ./Sample3.ps1

ディレクトリ: C:

Mode LastWriteTime Length Name

---- ------------- ------ ----

-a---- 2023/11/24 15:08 0 Example.txt

ファイルの作成が完成しました。

上記の様にNew-Itemの実行結果がコンソールに呼び出されます。
この関数を使用するたびに毎回表示されたくない場合、voidを使用することで結果を表示させないようにできます。

# C:\Sample4.ps1
function New-EmptyFile {
　　param (
　　　　[string]$filePath
　　)

　　#[void]を行頭に付けて、カッコで囲む
　　[void](New-Item -Path $filePath -ItemType File)
　　Write-Host "ファイルの作成が完成しました。"
}

# 関数を呼び出し
New-EmptyFile -filePath "C:\Example.txt"

# C:\Sample4.ps1

function New-EmptyFile {

　　param (

　　　　[string]$filePath

　　)

　　#[void]を行頭に付けて、カッコで囲む

　　[void](New-Item -Path $filePath -ItemType File)

　　Write-Host "ファイルの作成が完成しました。"

}

# 関数を呼び出し

New-EmptyFile -filePath "C:\Example.txt"

実行結果

PS　C:> ./Sample4.ps1
ファイルの作成が完成しました。

1 2	PS　C:> ./Sample4.ps1 ファイルの作成が完成しました。

[void]の代わりに、行末に | Out-Null と記載することでも同様の効果が得られます。

function New-EmptyFile {
　　param (
　　　　[string]$filePath
　　)

　　#行末に | Out-Null を追加
　　New-Item -Path $filePath -ItemType File | Out-Null
　　Write-Host "ファイルの作成が完成しました。"
}

function New-EmptyFile {

　　param (

　　　　[string]$filePath

　　)

　　#行末に | Out-Null を追加

　　New-Item -Path $filePath -ItemType File | Out-Null

　　Write-Host "ファイルの作成が完成しました。"

}

関数のオプションについて

Free Businessman Consulting photo and picture

PowerShell関数においてオプションは、関数が受け取る引数の性質を制御するための仕組みです。
以下は、一般的なオプションについて紹介していきます。

Parameter属性

Parameter属性は、パラメータに関する様々な属性を指定するために使用されます。たとえば、位置づけ、必須の有無、デフォルト値の設定などが指定できます。

以下の例では、$Name パラメータは位置0にあり、必須であることを示していて、$Age パラメータはデフォルト値が設定されており、位置1に配置されています。

# C:\Sample5.ps1
function Name-Age {
　　param (
　　　　#引数0番目を指定、必須項目とする（=$trueは省略可）
　　　　[Parameter(Position=0, Mandatory=$true)]
　　　　[string]$Name,
　　　　#引数1番目を指定、初期値25を指定
　　　　[Parameter(Position=1)]
　　　　[int]$Age = 25
　　)

　　Write-Host "Name: $Name, Age: $Age"
}

Name-Age Taro 30

# C:\Sample5.ps1

function Name-Age {

　　param (

　　　　#引数0番目を指定、必須項目とする（=$trueは省略可）

　　　　[Parameter(Position=0, Mandatory=$true)]

　　　　[string]$Name,

　　　　#引数1番目を指定、初期値25を指定

　　　　[Parameter(Position=1)]

　　　　[int]$Age = 25

　　)

　　Write-Host "Name: $Name, Age: $Age"

}

Name-Age Taro 30

実行結果

PS　C:> ./Sample5.ps1
Name: Taro, Age: 30

1 2	PS　C:> ./Sample5.ps1 Name: Taro, Age: 30

上記関数で、引数の指定を無しにした場合はどうなるのでしょうか。

Sample5.ps1の15行目を Name-Age に変更

PS　C:> ./Sample5.ps1
コマンド パイプライン位置 1 のコマンドレット Name-Age
次のパラメーターに値を指定してください:
Name:

PS　C:> ./Sample5.ps1

コマンドパイプライン位置 1 のコマンドレット Name-Age

次のパラメーターに値を指定してください:

Name:

このように表示され、必須項目である$Nameパラメータの入力を求めてきます。
$Nameパラメータを入力すると、$Ageパラメータは初期値を返します。

PS　C:> ./Sample5.ps1
コマンド パイプライン位置 1 のコマンドレット Name-Age
次のパラメーターに値を指定してください:
Name: Akira
Name: Akira, Age: 25

PS　C:> ./Sample5.ps1

コマンドパイプライン位置 1 のコマンドレット Name-Age

次のパラメーターに値を指定してください:

Name: Akira

Name: Akira, Age: 25

Alias属性

Alias属性を使用すると、関数を別名で呼ぶことができます。
以下の例は、MyFunction関数をAliasNameとしても呼ぶことが可能です。

# C:\Samples6.ps1
function MyFunction {
　　[Alias("AliasName")]
　　param (
　　　　[string]$Name
　　)

　　Write-Host "Name: $Name"
}

MyFunction taro
AliasName jiro

# C:\Samples6.ps1

function MyFunction {

　　[Alias("AliasName")]

　　param (

　　　　[string]$Name

　　)

　　Write-Host "Name: $Name"

}

MyFunction taro

AliasName jiro

実行結果

PS　C:> ./Sample6.ps1
Name: taro
Name: jiro

PS　C:> ./Sample6.ps1

Name: taro

Name: jiro

Switchパラメータ

Switchパラメータを設定すると、引数が指定されているかどうかをTrueかFalseで返すようになります。
以下の例は、引数swにSwitchパラメータを指定しています。

# C:\Samples7.ps1
function Switch-Ex {
　　param (
　　　　#Switchパラメータを指定
　　　　[Switch]$sw
　　)

　　#$swがTrueかFalseで分岐
　　if ($sw) {
　　　　Write-Host "swがTrueです。"
　　} else {
　　　　Write-Host "swがFalseです。"
　　}
}

Switch-Ex "a"
Switch-Ex -sw "a"

# C:\Samples7.ps1

function Switch-Ex {

　　param (

　　　　#Switchパラメータを指定

　　　　[Switch]$sw

　　)

　　#$swがTrueかFalseで分岐

　　if ($sw) {

　　　　Write-Host "swがTrueです。"

　　} else {

　　　　Write-Host "swがFalseです。"

　　}

Switch-Ex "a"

Switch-Ex -sw "a"

実行結果

PS　C:> ./Sample7.ps1
swがFalseです。
swがTrueです。

PS　C:> ./Sample7.ps1

swがFalseです。

swがTrueです。

メモ

関数呼び出し１回目は引数swを明示していないので、$swにはFalseが入ります。
関数呼び出し２回目は引数swを明示しているので、$swにはTrueが入ります。

ValidateSetパラメータ

ValidateSetパラメータは、引数の入力制限を設定します。
ValidateSetパラメータ設定時はリスト型で指定し、それ以外の値を受け付けないようにします。

# C:\Samples8.ps1
function Validate-Set {
　　param (
　　　　[ValidateSet("りんご", "みかん", "バナナ")]
　　　　[string]$Choice
　　)

　　Write-Host "選んだくだもの: $Choice"
}

Validate-Set りんご

# C:\Samples8.ps1

function Validate-Set {

　　param (

　　　　[ValidateSet("りんご", "みかん", "バナナ")]

　　　　[string]$Choice

　　)

　　Write-Host "選んだくだもの: $Choice"

}

Validate-Set りんご

実行結果

PS　C:> ./Sample8.ps1
選んだくだもの: りんご

1 2	PS　C:> ./Sample8.ps1 選んだくだもの: りんご

ValidateSetパラメータで指定した値以外を入力すると、エラーが返ってきます。

　Sample8.ps1の11行目を Validate-Set すいかに変更

PS　C:> ./Sample8.ps1
Validate-Set : パラメーター 'Choice の引数を確認できません。引数 "すいか" は、ValidateSet 属性で指定されたセット "りんご,みかん,バナナ" に属していません。このセットの引数を指定して、コマンドを再度実行してください。
発生場所 C:\Users\user\Desktop\PowerShellの関数8 .ps1:11 文字:14
+ Validate-Set すいか
+ ~~~
+ CategoryInfo : InvalidData: (:) [Validate-Set]、ParameterBindingValidationException
+ FullyQualifiedErrorId : ParameterArgumentValidationError,Validate-Set

PS　C:> ./Sample8.ps1

Validate-Set : パラメーター 'Choice の引数を確認できません。引数 "すいか" は、ValidateSet 属性で指定されたセット "りんご,みかん,バナナ" に属していません。このセットの引数を指定して、コマンドを再度実行してください。

発生場所 C:\Users\user\Desktop\PowerShellの関数8 .ps1:11 文字:14

+ Validate-Set すいか

+ ~~~

+ CategoryInfo : InvalidData: (:) [Validate-Set]、ParameterBindingValidationException

+ FullyQualifiedErrorId : ParameterArgumentValidationError,Validate-Set

PowerShellの関数オプションは上記は一例で、他にもたくさん存在します。
詳しく知りたい方は以下をご覧ください。

Microsoft公式　PowerShell

まとめ

Free Sunset Men photo and picture

PowerShellで関数を使用することで、使いやすくてメンテナンスがしやすいスクリプトを構築することができます。
パラメータのデフォルト値の設定やパイプライン操作など、PowerShellが提供する独自の機能を活用することもできます。
PowerShellの関数を学んで、見やすくて管理しやすいコードを目指してみてはいかがでしょうか。

リンク

プログラミング知識を身に着けたい人におすすめの無料スクールはこちら。