PowerSehll 小技巧 - 開關參數與腳本使用說明

分享最近的學會的 PowerShell 技巧兩則。

第一個是如何為 ps1 腳本加上啟用特定功能的開關。我以前比較笨，都是另設字串參數預設為 N，要啟用就傳入 Y，例如：-IncludeSubFolder Y。但 PowerShell 有較優雅的做法 - 沒給參數代表不啟用，附加參數則是啟用，以 Get-Content 為例：

其中只需寫出參數名稱不用給參數值的 -Force、-UseTransaction、-Wait、-Raw 即是所謂的 - 開關參數 Switch Parameters。要宣告成開關參數的方法很簡單，撰寫 .ps1 宣告 Param($變數名稱) 時，在變數名稱前方加上 [Switch] 即可。開關參數也可用於一般函式，由於其型別為布林值，故亦可明確寫成 -EnableSomething:$true 或 -EnableSomething:$false 進行切換，此一特性可用於以變數決定啟用與否，寫成 -EnableSomething:$boolVariable。

另外，希望為 .ps1 加上詳細使用說明讓它看起來更專業嗎？像是這樣：

做法是在 .ps1 用 <# ... #> 包含特定格式的註解，術語叫做 Comment-Based Help，概念就像 .NET 的 XML Documentation。

註解式說明包含以下常用項目：

• SYNOPSIS 概要
  簡要說明
• DESCRIPTION 描述
  較完整的說明
• EXAMPLE 範例
  語法參數範例，可以列舉多則
• PARAMETER <參數名稱> 參數說明
  每個參數一則，或是用 # ... 寫在 Param 參數宣告上方(見下方範例)更直覺一些
• INPUTS
  說明以 | 串接時可接收的 .NET 型別要求
• OUTPUTS
  說明輸出的 .NET 物件型別
• NOTES
  備註說明
• LINK
  可指向說明網頁 URL
• EXTERNALHELP
  額外提供 XML 說明文件

以下範例改寫自之前 tree.exe 產生資料夾樹狀結構中的 PowerShell 程式，為它加上 -ShowFile 開關參數及詳細說明：

<# 
.SYNOPSIS 
    tree 指令美化版 
.DESCRIPTION
    為 tree 的樹狀顯示加上花俏顏色，其實沒什麼意義啦
.EXAMPLE
    PS C:\>.\tree.ps1
    查詢當前資料夾結構
.EXAMPLE
    PS C:\>.\tree.ps1 D:\Temp -ShowFile
    查詢 D:\Temp 結構，包含檔案
#>
Param (
    # 要查詢的資料夾，未指定時為目前所在資料夾
    [string] $Path,
    # 是否顯示檔案
    [Switch]
    [bool] $ShowFile 
)
$arg = @($Path, '/a')
if ($ShowFile) {
    $arg += '/f'
}
& tree $arg | Select-Object -Skip 2 | ForEach-Object {
    if ($_.Contains(':\')) {
        Write-Host $_ -ForegroundColor Cyan
    }
    elseif ($_.StartsWith('+') -or $_.StartsWith('\')) { 
        $m = [System.Text.RegularExpressions.Regex]::Match($_, '^(?<l>[+\\]-+)(?<n>.+)')
        Write-Host $m.Groups["l"] -NoNewline
        Write-Host " $($m.Groups["n"].Value) " -BackgroundColor DarkYellow -ForegroundColor Black
    }
    else {
        Write-Host $_
    }
}

使用指令 get-help .\tree.ps1 可檢視說明。加上 -detail 參數會顯示參數說明及範例，加上 -full 則再增加輸入輸出型別及額外說明，-examples 則是只顯示範例。這樣子，自製 PowerShell 小工具看起來就更專業囉。

Intruduction to PowerShell switch parameter and how to use comment-based help to provide detail instruction.