如何為 PowerShell 腳本撰寫基於註解的幫助

本文展示了如何為腳本和函數撰寫基於註解的幫助主題。我們將使用特殊的幫助註解關鍵字來創建主題。

我們使用 Get-Help Cmdlet 來顯示類似於 XML 文件生成的基於註解的幫助主題。

PowerShell 中的基於註解的幫助

以下是基於註解的幫助的語法。

# .<help keyword>
# <help content>

或

<#
.<help keyword>
<help content>
#>

我們將基於註解的幫助主題寫作為一系列註解。要標記註解，我們可以在每行註解的開頭添加 # 符號，或者使用 <# 和 #> 創建註解區塊。

控制台將把註解區塊內的行註冊為註解。

我們使用特殊關鍵字來定義基於註解的主題幫助的每個部分。關鍵字以 . 開頭，且不區分大小寫。

這是一個例子：

<#
.Description
Get-Clipboard fetches the content of our clipboard in the session.
#>

在上述例子中，.Description 關鍵字將該註解標記為我們函數的描述。

一個註解區塊必須至少包含一個關鍵字。有些關鍵字僅會出現一次，而其他則沒有限制。

關鍵字的內容應該在關鍵字之後的行開始並且沒有限制。

在為函數添加基於註解的幫助時，您可以在下面討論的三個位置中的任何一個添加它們。

1. 在函數主體的開頭。
2. 在函數主體的結尾。
3. 在 function 關鍵字之前，並且相隔不超過一個空白行。

示例：

function Get-Function
{
<#
.<help keyword>
<content>
#>

  # function logic
}

或

function Get-Function
{
   # function logic

<#
.<help keyword>
<content>
#>
}

或

<#
.<help keyword>
<content>
#>
function Get-Function { }

基於註解的幫助可以出現在腳本的開頭或結尾。這裡有一些示例：

<#
.<help keyword>
<content>
#>

function Get-Function { }

或

function Get-Function { }

<#
.<help keyword>
<content>
#>

PowerShell 中的基於註解的關鍵字

以下是有效的基於註解的幫助關鍵字。它們可以以任意順序出現，且不區分大小寫。

.SYNOPSIS

這是一個關於函數或腳本的簡短描述。每個主題中該關鍵字應僅出現一次。

.DESCRIPTION

這是對函數或腳本的詳細描述。我們在每個主題中僅使用一次。

.PARAMETER

這描述了您腳本或函數中的參數。對於我們的腳本或函數中的每個參數，我們添加一個 .PARAMETER 關鍵字。

.PARAMETER <Parameter-Name>

參數關鍵字在註解區塊中不遵循嚴格的順序。腳本或函數中參數的語法將決定幫助主題中的順序。

您可以通過改變語法來改變順序。

我們可以透過在函數或腳本中添加註解來指定參數關鍵字內容。該註解應該位於參數變數名稱之前。

PowerShell 優先考慮與參數關鍵字相關的描述，而不是語法註解（如果兩者都使用的話）。

<#
.SYNOPSIS
    Brief description
#>
function Noun-Verb {
    [CmdletBinding()]
    param (
        # It is the same as .Parameter
        [string]$CompName
    )
    # Logic
}

.EXAMPLE

包括一個使用該腳本或函數的示例命令。我們可以為腳本或函數中的所有示例包含此關鍵字。

.INPUTS

這些是我們可以通過管道傳遞給我們的腳本或函數的 .NET 對象。我們可以添加對輸入對象的描述。

.OUTPUTS

這些是我們的 Cmdlet 返回的 .NET 對象。我們可以為返回的對象添加描述。

.NOTES

這些是有關腳本或函數的任何附加信息。信息可以包括編碼日期、函數名稱或創建者的姓名。

.LINK

這些是相關主題。

這是一個函數的基於註解的幫助示例：

總之，我們可以通過將基於註解的幫助放置在註解區塊中來在函數或腳本中添加它們。在添加幫助主題時，使用上述討論的關鍵字，並記住在腳本和函數中放置註解區塊的位置。