PowerShell で関数を作成する

PowerShell では関数がよく使用されますが、PowerShell 言語を正しく理解するためには、関数の仕組みを理解することが重要です。このブログでは、ほとんどゼロの状態から、検証属性を使用するパラメータを持つようになるまで、PowerShell 関数を作成する方法を示します。

マネージド・ファイル・トランスファー MOVEit にはスクリプトのスキルを必要としない高度なファイル転送自動化機能があります。

これを説明するにあたり、まずこれ以上簡単なものはないくらいの関数から始めましょう。

function Write-Log {
     [CmdletBinding()]
     param()
 }

PowerShell セッション内で走らせてみると、実行はされますが、実行するコードがないため実質的には何も行いません。 PowerShell は何もしない関数を実行して戻ります。

関数が実際に何かをするためには、実行するためのコードを追加する必要があります。コードは、param ブロックと最後の中括弧の間に書くことができます。下の例では、Write-Log という関数を作成して "I did something" という文字列をコンソールに返すようにしています。

function Write-Log {
     [CmdletBinding()]
     param()
     
     'I did something'
 }

PS> Write-Log
 I did something

Write-Log と名前をつけたのは、これを最終的には何らかのテキストをログファイルに書き込む関数にしようと想定しているからです。毎回同じことをログファイルに書くのはばかげていますから、関数が実行されるときにメッセージを変更するようにしましょう。そのためには、パラメータを追加します。パラメータを使用すると、実行時に異なる値を関数に渡すことができます。関数は実行時にダイナミックな入力を受け付けます。

パラメータとして、変数を使うことにします。ここでは変数の名前を Message として、param ブロックの中に追加します。関数自体の内部でパラメータを参照できます。実行すると、関数は、Message パラメータに渡した値を返します。

function Write-Log {
     [CmdletBinding()]
     param($Message)
     
     $Message
 }

PS> Write-Log -Message 'I did something'
 I did something

パラメータは１つだけでなく、いくつでも追加することができます。以下では、Severity パラメータを追加して、関数が実行されたときに参照する値を設定します。

function Write-Log {
     [CmdletBinding()]
     param($Message, $Severity)
     
     "$Message - Severity: $Severity"
 }

Write-Log -Message 'I did something' -Severity 1

パラメータの使い方がわかったので、次はパラメータの型について説明します。パラメータには、PowerShell で使われる他のものと同様に型があります。上の例でも型はありましたが、パラメータは明示的に型指定されておらず、どんな種類のオブジェクトでも受け入れる設定になっていました。想定している値だけが渡されるように、すべてのパラメータについて型指定しておくことが奨励されています。

パラメータの型は、パラメータを定義する直前に角括弧で指定します。

function Write-Log {
     [CmdletBinding()]
     param([System.ServiceProcess.ServiceController]$Message)
     
     $Message
 }

パラメータに型が明示的に割り当てられると、PowerShell はその型または変換できるオブジェクトの入力のみを受け付けます。下は、ブール値 $false を Message パラメーターに渡した例ですが、ブール値型を ServiceController 型に変換できないため、PowerShell はこれを受け付けずエラーになります。

Get-Service では ServiceController オブジェクトが返ってくるので、次のようにするとうまくいきます。

PS> Write-Log -Message $service
 
 Status   Name               DisplayName
 ------   ----               -----------
 Stopped  AdtAgent           Microsoft Monitoring Agent Audit Fo...

パラメータ属性も使用できます。パラメータ属性を使用すると、各パラメータのさまざまな特性を定義して、どのように動作するかを決めることができます。下の例は、パラメータを必須とするため Mandatory 属性を指定しています。この属性が指定されていると、Message パラメータには値が必須となり、値が渡されないと関数は実行されません。

Severity パラメータにはデフォルト値を指定しています。Severity パラメータが実行時に渡される値によって上書きされない限り、その値は常に1に設定されます。

function Write-Log {
     [CmdletBinding()]
     param(
         [Parameter(Mandatory)]
         [string]$Message,
         
         [Parameter()]
         [int]$Severity = 1
     )
     
     "$Message - Severity: $Severity"
 
 }

最後に、パラメータの検証属性について説明します。パラメータに渡される値に制限を加えたいとき、検証属性を使います。以下は、許容される数値の範囲を定義する ValidateRange() 検証属性を使用した例です。ここでは、Severity の値を1から5の整数値に限定しています。その範囲を超える値は受け付けません。

function Write-Log {
     [CmdletBinding()]
     param(
         [Parameter(Mandatory)]
         [pscustomobject]$Message,
         
         [Parameter()]
         [ValidateRange(1, 5)]
         [int]$Severity
     )
     
     "$Message - Severity: $Severity"
 }

まとめ

PowerShell で関数がどのように機能するかについての基本的な事項を概説しました。PowerShell の便利な機能を作成し始めるにあたって知っておくべきことはカバーしたつもりです。スクリプトで関数が有用そうなところがあれば、作成し始めてみてください。作成し慣れれば、コードもより洗練されて、読みやすくなると思います。