Comment-Based 說明關鍵詞

發行項
01/22/2025

本主題列出並描述批注型說明中的關鍵詞。

說明中的關鍵詞 Comment-Based

以下是以批注為基礎的有效說明關鍵詞。它們會依其通常出現在 [說明] 主題中以及其預定用途的順序列出。這些關鍵詞可以依批注型說明的任何順序顯示，而且不會區分大小寫。

請注意，.EXTERNALHELP 關鍵詞優先於所有其他以批注為基礎的說明關鍵詞。當 .EXTERNALHELP 存在時，Get-Help Cmdlet 不會顯示批注型說明，即使找不到符合關鍵詞值的說明檔也一般。

`.SYNOPSIS`

函式或腳本的簡短描述。每個主題中只能使用此關鍵詞一次。

`.DESCRIPTION`

函式或腳本的詳細描述。每個主題中只能使用此關鍵詞一次。

`.PARAMETER <Parameter-Name>`

參數的描述。您可以在函式或文稿中包含每個參數的 .PARAMETER 關鍵詞。

.PARAMETER 關鍵詞可以依批注區塊中的任何順序顯示，但參數出現在 Param 語句或函式宣告中的順序會決定參數出現在 [說明] 主題中的順序。若要變更 [說明] 主題中的參數順序，請變更 Param 語句或函數宣告中的參數順序。

您也可以將批註放在參數變數名稱之前的 Param 語句中，以指定參數描述。如果您使用 Param 語句批注和 .PARAMETER 關鍵詞，則會使用與 .PARAMETER 關鍵詞相關聯的描述，並忽略 Param 語句批注。

`.EXAMPLE`

使用函式或腳本的範例命令，選擇性地後面接著範例輸出和描述。針對每個範例重複這個關鍵詞。

`.INPUTS`

Microsoft可傳送至函式或腳本之物件的 .NET Framework 類型。您也可以包含輸入物件的描述。

`.OUTPUTS`

Cmdlet 傳回之物件的 .NET Framework 類型。您也可以包含傳回物件的描述。

`.NOTES`

函式或腳本的其他資訊。

`.LINK`

相關主題的名稱。針對每個相關主題重複這個關鍵詞。此內容會出現在 [說明] 主題的 [相關連結] 區段中。

.LINK 關鍵詞內容也可以包含相同幫助主題的在線版本統一資源標識碼（URI）。當您使用 Get-Help的 Online 參數時，在線版本隨即開啟。 URI 的開頭必須是「HTTP」或「HTTPs」。

`.COMPONENT`

函式或腳本所使用的技術或功能名稱，或其相關。 Get-Help 的 Component 參數會使用此值來篩選 Get-Help所傳回的搜尋結果。

`.ROLE`

說明主題的使用者角色名稱。 Get-Help 的 Role 參數會使用此值來篩選 Get-Help所傳回的搜尋結果。

`.FUNCTIONALITY`

描述函式用途的關鍵詞。 Get-Help 的 Functionality 參數會使用此值來篩選 Get-Help所傳回的搜尋結果。

`.FORWARDHELPTARGETNAME <Command-Name>`

重新導向至指定命令的說明主題。您可以將使用者重新導向至任何說明主題，包括函式、腳本、Cmdlet 或提供者的說明主題。

`.FORWARDHELPCATEGORY <Category>`

指定 .FORWARDHELPTARGETNAME中專案的 [說明] 類別。使用這個關鍵詞，以避免有具有相同名稱的命令時發生衝突。

有效值為：

別名
Cmdlet
HelpFile
Function
Provider
General
FAQ
Glossary
ScriptCommand
ExternalScript
濾波器
都

`.REMOTEHELPRUNSPACE <PSSession-variable>`

指定包含說明主題的工作階段。輸入包含 PSSession 的變數。 Export-PSSession Cmdlet 會使用此關鍵詞來尋找匯出命令的說明主題。

`.EXTERNALHELP <XML Help File>`

指定文稿或函式之 XML 型說明檔的路徑和/或名稱。

.EXTERNALHELP 關鍵詞會告訴 Get-Help Cmdlet，以取得 XML 型檔案中腳本或函式的說明。針對腳本或函式使用 XML 型說明檔時，需要 .EXTERNALHELP 關鍵詞。如果沒有，Get-Help 找不到函式或腳本的說明檔。

.EXTERNALHELP 關鍵詞優先於所有其他以批注為基礎的說明關鍵詞。當 .EXTERNALHELP 存在時，Get-Help Cmdlet 不會顯示批注型說明，即使找不到符合關鍵詞值的說明檔也一般。

當文本模組匯出函式時，.EXTERNALHELP 的值應該是沒有路徑的檔名。 Get-Help 在模組目錄的地區設定特定子目錄中尋找檔案。檔案名沒有需求，但最佳做法是使用下列檔名格式：<ScriptModule>.psm1-help.xml。

當函式未與模組相關聯時，請在 .EXTERNALHELP 關鍵詞的值中包含路徑和檔名。如果 XML 檔案的指定路徑包含 UI 文化特性特定的子目錄，Get-Help 會根據針對所有 XML 型說明主題所建立的語言後援標準，以遞歸方式搜尋具有腳本或函式名稱的 XML 檔案。

如需 Cmdlet 說明 XML 說明檔案格式的詳細資訊，請參閱撰寫 Windows PowerShell Cmdlet 說明。

共用方式為