PowerShell 互斥參數集實戰：ParameterSetName 讓參數「二選一」甚至「多選一」

前言

PowerShell 進階函數常需要「參數互斥」：用戶只能在指定組合中二選一（如 -Id 或 -Name），或根據參數組合動態決定某參數是否強制。本文通過兩個完整示例，詳解 ParameterSetName 的核心機制與進階用法。

基礎範例：單參數互斥（-id 或 -name）

function Test-ParameterSet {
    [CmdletBinding(DefaultParameterSetName = 'ByNumber')]
    param(
        [Parameter(ParameterSetName = 'ByNumber', Position = 0)]
        [int]$Id,

        [Parameter(ParameterSetName = 'ByName', Position = 0)]
        [string]$Name
    )

    $PSCmdlet.ParameterSetName   # 輸出觸發的參數集名稱
    $PSBoundParameters           # 輸出實際綁定的參數字典
}

測試：

Test-ParameterSet 123        # ByNumber, Id=123
Test-ParameterSet -Name "abc" # ByName, Name=abc
Test-ParameterSet 123 -Name "abc" # 報錯：參數集衝突

進階範例：多參數、動態強制、預設參數集

function Test-ParameterSet {
    [CmdletBinding(DefaultParameterSetName = 'NonCredential')]
    param(
        $Id,

        [Parameter(ParameterSetName = 'LocalOnly', Mandatory = $false)]
        $LocalAction,

        [Parameter(ParameterSetName = 'Credential', Mandatory = $true)]
        [Parameter(ParameterSetName = 'NonCredential', Mandatory = $false)]
        $ComputerName,

        [Parameter(ParameterSetName = 'Credential', Mandatory = $false)]
        $Credential
    )

    $PSCmdlet.ParameterSetName
    $PSBoundParameters

    if ($PSBoundParameters.ContainsKey('ComputerName')) {
        Write-Warning 'Remote Call!'
    }
}

參數集行為對照表

核心規則總結

1. 每個參數可屬於多個參數集（陣列語法 @('Set1','Set2')）。
2. 同一參數在不同參數集可有不同 Mandatory 值。
3. PowerShell 根據用戶提供的參數自動推斷唯一匹配的參數集；無法唯一匹配則報錯。
4. DefaultParameterSetName 指定無參數時的預設集合。
5. 運行時用 $PSCmdlet.ParameterSetName 獲取實際觸發集合，$PSBoundParameters 檢查具體綁定參數。

總結

善用 ParameterSetName 能在聲明式層面強制參數互斥、動態切換強制性，極大減少運行時 if/else 判斷，讓函數介面既靈活又安全。