PowerShell関数のパラメーター：より良い関数を構築する実践ガイド

チュートリアル
PowerShell

PowerShellで関数を構築することは、スクリプトをモジュール化して再利用可能にする素晴らしい方法です。ただし、これらの関数を異なるシナリオで適応可能にしたい場合は、関数パラメータを追加することで次のレベルに引き上げることができます。

このチュートリアルでは、基本的なログ記録関数を拡張し、ログメッセージ、ファイルパス、および検証を制御するパラメータを追加します。

最終的には、パラメータが関数を多目的で、エラーに強く、PowerShellツールキットへの強力な追加とする方法がわかります。

基本のWrite-Log関数を定義する

まず、時間を追加して標準ログファイルにそれを追加する単一の入力パラメータを取る基本的な関数から始めましょう。

この例では：

  • $LogMessageパラメータは必須とされており、値を提供しない場合はPowerShellがプロンプトを表示します。
  • 各ログエントリにはHH:mm:ss形式のタイムスタンプが含まれます。
function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$LogMessage
    )
    $timeGenerated = Get-Date -Format HH:mm:ss
    Add-Content -Path "C:\Scripts\software_installer.log" -Value "$timeGenerated - $LogMessage"
}

Write-Log関数のテスト

Write-Log関数に基本的な構造があり、パラメータを受け入れるようになったので、機能をテストする時がきました。テストを行うことで、デフォルト設定からカスタム入力まで、関数の各側面が期待どおりに機能し、エラーを適切に処理することが確認されます。

カスタムメッセージを使用してWrite-Log関数をテストします。

Write-Log -LogMessage 'Testing a new log message'

このコマンドは、タイムスタンプを含む新しいエントリをログファイル（C:\Scripts\software_installer.log）に追加します。

Write-Log関数について注意すべき点はいくつかあります。

Standardized Information Logging By setting a default path for the log file, you don’t have to specify the file name every time you call the function. This standardizes all log information to a single file, keeping your logs organized.
簡素化されたログ記録プロセス この関数は、Get-Dateを使用して現在の日付と時刻を取得し、Add-Contentで内容を追加するような詳細を抽象化します。この関数のユーザーとして、これらの詳細を思い出す必要なく、ログファイルにメッセージを書くことに専念できます。
コードの可読性の向上 この関数は特定のログファイルにメッセージを明示的に記録し、目的が単に一般的なテキストファイルに書き込むことではなく、ログ記録であることを明確にします。これにより、コードはより自己説明的で、一目で理解しやすくなります。

これらの改善により、Write-Log関数はログ記録タスクを効率化し、スクリプトをよりクリーンで保守しやすくします。

最新のログメッセージを確認するには、ログファイルの内容をチェックします：

Get-Content -Path "C:\Scripts\software_installer.log"

このコマンドは、タイムスタンプ付きの最新メッセージを含むすべてのログエントリを表示します。

しかし、おそらくLogMessageパラメータなしでWrite-Logを呼び出してしまった場合：

Write-Log

必須のLogMessageがないため、PowerShellは関数の実行を防ぎます。しかし、LogMessageが必須でなければ、空のメッセージが書き込まれ、意図しない「おっと」エントリが作成されます。

結果を確認するには、再度ログファイルをチェックします：

Get-Content -Path "C:\Scripts\software_installer.log"

カスタムログファイルパスによる柔軟性の追加

関数は素晴らしく機能しますが、$LogFilePath パラメータを追加して、さらに柔軟性を持たせましょう。このパラメータを使用すると、デフォルトのパスを提供しつつ、カスタムファイルパスを指定できます。

function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$LogMessage,

        [Parameter()]
        [string]$LogFilePath = 'C:\Scripts\software_installer.log'
    )
    $timeGenerated = Get-Date -Format HH:mm:ss
    Add-Content -Path $LogFilePath -Value "$timeGenerated - $LogMessage"
}

$LogFilePath のデフォルトパスはC:\Scripts\software_installer.logですが、任意の有効なパスを提供することができます。

別のファイルパスを指定するには、次のように Write-Log を呼び出します：

Write-Log -LogMessage 'Custom path log message' -LogFilePath 'C:\Scripts\custom_log.log'

ファイルパスを強制する ValidateScript

存在しないファイルにログを記録したくないでしょう。そのため、ValidateScript パラメータ属性を使用して、ログを記録する前にファイルが存在するかを確認できます。この属性を使用すると、パラメータの値に対してコードを実行し、関数を実行する前に検証できます。

function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$LogMessage,

        [Parameter()]
        [ValidateScript({ Test-Path -Path $_ })]
        [string]$LogFilePath = 'C:\Scripts\software_installer.log'
    )
    $timeGenerated = Get-Date -Format HH:mm:ss
    Add-Content -Path $LogFilePath -Value "$timeGenerated - $LogMessage"
}

ValidateScript を使用すると、Write-Log は提供されたファイルパスが存在するかどうかをチェックします。ファイルが存在しない場合、PowerShell は停止し、エラーを返します。

関数が期待通りに動作することを確認するために、呼び出す前に空のファイルを作成できます：

Set-Content -Path 'C:\Scripts\softwarex_installer.log' -Value ''
Write-Log -LogMessage 'Log entry in a new file' -LogFilePath 'C:\Scripts\softwarex_installer.log'

Write-Log の機能と検証をテストする

関数に柔軟性を追加した後、それが意図した通りに機能するかをテストするのは自然なことです。ValidateScript 属性を調べて、Write-Log 関数がどのように強化されるかを確認し、堅牢なログ機能を確保する必要があります。

存在しないファイルにログを記録しようとして ValidateScript がどのように機能するかを見てみましょう：

Write-Log -LogMessage 'Finishing install...' -LogFilePath 'C:\Scripts\softwarex_installer.log'

この場合、ValidateScript属性は、指定されたログファイルパスが存在するかどうかをTest-Pathを呼び出してチェックします。パスが存在しない場合、関数はエラーを返します。

関数は、C:\Scripts\softwarex_installer.logが存在しないため失敗します。これは、Test-Pathを手動で実行して確認できます:

Test-Path 'C:\Scripts\softwarex_installer.log'

Test-Pathが$falseを返すため、ファイルは確かに存在しません。

これを修正するには、空のログファイルを作成して再度テストしてください。

Set-Content -Path 'C:\Scripts\softwarex_installer.log' -Value ''
Write-Log -LogMessage 'Finishing install...' -LogFilePath 'C:\Scripts\softwarex_installer.log'

これで、関数が期待どおりに動作します。

ログファイルを表示して結果を確認してください:

Get-Content -Path 'C:\Scripts\softwarex_installer.log'

ValidateScriptや他のパラメーター検証属性を使用すると、関数パラメーターの正しい使用が強制され、エラーが減少し、PowerShell関数が信頼性を持つようになります。

結論

PowerShell関数にパラメーターを追加すると、柔軟性と有用性が大幅に向上します。デフォルト値、必須属性、および検証の組み合わせにより、関数は信頼性を維持しながらさまざまな入力を処理できます。

これらのテクニックを使用すると、スケーラブルでユーザーフレンドリーな関数を構築し、さまざまなスクリプトにシームレスに組み込むことができます。

これらのスキルをさらに発展させながら、より高度なPowerShellツールを作成してワークフローを効率化し、強化してください。このPowerShellパラメーターチュートリアルをチェックして、関数パラメーターに詳しく入りましょう！

Source:
https://adamtheautomator.com/powershell-function-parameters/