PowerShell
PowerShell関数

前書き

パラメータなしの単純な関数

これは、文字列を返す関数の例です。この例では、変数に値を代入するステートメントで関数が呼び出されます。この場合の値は、関数の戻り値です。

function Get-Greeting{
    "Hello World"
}

# Invoking the function
$greeting = Get-Greeting

# demonstrate output
$greeting
Get-Greeting

functionは次のコードをfunction宣言します。

Get-Greetingは関数の名前です。スクリプトで関数を使用する必要があるときは、関数を名前で呼び出すことで関数を呼び出すことができます。

{ ... }は、関数によって実行されるスクリプトブロックです。

上記のコードがISEで実行された場合、結果は次のようになります。

Hello World
Hello World

基本パラメータ

関数は、paramブロックを使用してパラメータで定義できます。

function Write-Greeting {
    param(
        [Parameter(Mandatory,Position=0)]
        [String]$name,
        [Parameter(Mandatory,Position=1)]
        [Int]$age
    )
    "Hello $name, you are $age years old."
}

または、単純な関数の構文を使用します。

function Write-Greeting ($name, $age) {
    "Hello $name, you are $age years old."
}

注：いずれのタイプのパラメーター定義でも、キャストパラメーターは必要ありません。

単純関数構文（SFS）は、paramブロックと比較して非常に限定された機能しか持っていません。
関数内で公開されるパラメータを定義することはできますが、 パラメータの属性を指定したり、 パラメータの検証を使用したり、 [CmdletBinding()]をSFSとともに含めることはできません（これは非包括的なリストです）。

関数は、順序付きまたは名前付きのパラメーターで呼び出すことができます。

呼び出し時のパラメーターの順序は、関数ヘッダー内の宣言の順序（デフォルト）と一致するか、 Positionパラメーター属性を使用して指定できます（前述の拡張機能の例を参照）。

$greeting = Write-Greeting "Jim" 82

あるいは、この関数は名前付きパラメータで呼び出すことができます

$greeting = Write-Greeting -name "Bob" -age 82

必須パラメータ

関数へのパラメータは、必須としてマークすることができます

function Get-Greeting{
    param
    (
        [Parameter(Mandatory=$true)]$name
    )
    "Hello World $name"
}

関数が値なしで呼び出された場合、コマンドラインは値の入力を求めます：

$greeting = Get-Greeting 

cmdlet Get-Greeting at command pipeline position 1
Supply values for the following parameters:
name: 

高度な機能

これはPowershell ISEからの高度な機能スニペットのコピーです。基本的に、これはPowerShellの高度な機能で使用できる多くのもののテンプレートです。注目すべき重要ポイント：

• get-help integration - 関数の先頭には、get-helpコマンドレットによって読み取られるように設定されたコメントブロックが含まれています。機能ブロックは、必要に応じて最後に配置することができます。
• cmdletbinding - 関数はコマンドレットのように動作します
• パラメーター
• パラメータセット

<#
.Synopsis
   Short description
.DESCRIPTION
   Long description
.EXAMPLE
   Example of how to use this cmdlet
.EXAMPLE
   Another example of how to use this cmdlet
.INPUTS
   Inputs to this cmdlet (if any)
.OUTPUTS
   Output from this cmdlet (if any)
.NOTES
   General notes
.COMPONENT
   The component this cmdlet belongs to
.ROLE
   The role this cmdlet belongs to
.FUNCTIONALITY
   The functionality that best describes this cmdlet
#>
function Verb-Noun
{
    [CmdletBinding(DefaultParameterSetName='Parameter Set 1', 
                  SupportsShouldProcess=$true, 
                  PositionalBinding=$false,
                  HelpUri = 'http://www.microsoft.com/',
                  ConfirmImpact='Medium')]
    [Alias()]
    [OutputType([String])]
    Param
    (
        # Param1 help description
        [Parameter(Mandatory=$true, 
                   ValueFromPipeline=$true,
                   ValueFromPipelineByPropertyName=$true, 
                   ValueFromRemainingArguments=$false, 
                   Position=0,
                   ParameterSetName='Parameter Set 1')]
        [ValidateNotNull()]
        [ValidateNotNullOrEmpty()]
        [ValidateCount(0,5)]
        [ValidateSet("sun", "moon", "earth")]
        [Alias("p1")] 
        $Param1,

        # Param2 help description
        [Parameter(ParameterSetName='Parameter Set 1')]
        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [ValidateScript({$true})]
        [ValidateRange(0,5)]
        [int]
        $Param2,

        # Param3 help description
        [Parameter(ParameterSetName='Another Parameter Set')]
        [ValidatePattern("[a-z]*")]
        [ValidateLength(0,15)]
        [String]
        $Param3
    )

    Begin
    {
    }
    Process
    {
        if ($pscmdlet.ShouldProcess("Target", "Operation"))
        {
        }
    }
    End
    {
    }
}

パラメータ検証

PowerShellでは、パラメータの入力を検証するさまざまな方法があります。

パラメータ値を検証するための関数やスクリプト内にコードを記述するのではなく、無効な値が渡された場合、これらのParameterAttributesがスローされます。

ValidateSet

場合によっては、パラメータが受け入れることができる可能な値を制限する必要があります。スクリプトや関数の$Colorパラメータに赤、緑、青だけを許可したいとします。

ValidateSetパラメータ属性を使用してこれを制限することができます。この引数を設定するときにタブの補完を許可するという追加の利点があります（環境によっては）。

param(
    [ValidateSet('red','green','blue',IgnoreCase)]
    [string]$Color
)

大文字と小文字の区別を無効にするには、 IgnoreCaseを指定することもできます。

ValidateRange

このパラメータの検証方法では、最小値と最大値のInt32値が使用され、その範囲内にパラメータが必要です。

param(
    [ValidateRange(0,120)]
    [Int]$Age
)

ValidatePattern

このパラメータ検証の方法は、指定された正規表現パターンに一致するパラメータを受け入れます。

param(
    [ValidatePattern("\w{4-6}\d{2}")]
    [string]$UserName
)

ValidateLength

このパラメータ検証方法は、渡された文字列の長さをテストします。

param(
    [ValidateLength(0,15)]
    [String]$PhoneNumber
)

ValidateCount

このパラメータ検証方法は、渡された引数の量、たとえば文字列の配列をテストします。

param(
    [ValidateCount(1,5)]
    [String[]]$ComputerName
)

ValidateScript

最後に、ValidateScriptメソッドは非常に柔軟で、スクリプトブロックをとり、渡された引数を表すために$ _を使用して評価します。結果が$ true（任意の出力を有効として含む）の場合、引数を渡します。

これは、ファイルが存在するかどうかをテストするために使用できます：

param(
    [ValidateScript({Test-Path $_})]
    [IO.FileInfo]$Path 
)

ユーザーがADに存在することを確認するには：

param(
    [ValidateScript({Get-ADUser $_})]
    [String]$UserName
)

そして、あなたが書くことができる他のほとんどのもの（onelinersに限定されていないので）：

param(
    [ValidateScript({
        $AnHourAgo = (Get-Date).AddHours(-1)
        if ($_ -lt $AnHourAgo.AddMinutes(5) -and $_ -gt $AnHourAgo.AddMinutes(-5)) {
            $true
        } else {
            throw "That's not within five minutes. Try again."
        }
    })]
    [String]$TimeAboutAnHourAgo
)