共用方式為

撰寫 PowerShell 模組的說明

PowerShell 模組可以包含模組和模組成員的說明主題，例如 Cmdlet、提供者、函式和腳本。 Get-Help Cmdlet 會以顯示其他 PowerShell 專案說明的相同格式顯示模組說明主題，而使用者會使用標準Get-Help命令來取得說明主題。

本文件說明模組說明主題的格式和正確位置，並建議模組說明內容的指導方針。

模組說明的類型

模組可以包含下列類型的說明。

  • XML 型說明

    • Cmdlet 說明。 描述模組中 Cmdlet 的說明主題是使用命令說明架構的 XML 檔案
    • 提供者幫助。 描述模組中提供者的說明主題是使用提供者說明架構的 XML 檔案。
    • 功能說明。 說明模組中函數的說明主題可以是 XML 檔案，這些檔案使用指令說明綱目或函數內註解型說明主題，或 Script 或 Script 模組
    • 指令碼說明。 說明模組中 Script 的說明主題可以是 XML 檔案，這些 XML 檔案使用指令說明綱目，或 Script 或 Script 模組中的註解型說明主題。
    • 資料夾包含 $PSHOME\Schemas\PSMaml 定義 XML 格式的綱目檔案。

  • 概念性 （“About”） 說明文字檔

    您可以使用概念性 （「關於」） 說明主題來說明模組及其成員，並說明如何一起使用這些成員來執行作業。 根據預設，PowerShell 包含 100 多個概念性 關於說明 主題。 檔案名稱必須使用格式， about_<name>.help.txt 例如 about_MyModule.help.txt。

    備註

    TOPIC區段標頭必須從檔案第一行的第一欄開始。 第二行的章節內容應與檔案名稱相符，但沒有 .help.txt 後綴。 您必須將內容縮排 4 個空格。 第三行必須是空白的。 SYNOPSIS區段標題必須從第四行的第一欄開始。 您必須將第五行的內容縮排 4 個空格。 這些需求是 Cmdlet 正確辨識內容的必要 Get-Help 條件。

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

    您可以使用下列範例範本作為撰寫概念性說明主題的起點。 除了前兩節之外，概念說明主題的結構是任意的。 其餘的章節標題可以是適合您內容的任何內容。

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

LONG DESCRIPTION

A detailed, full description of the subject or purpose of the module.

EXAMPLES

Examples of how to use the module or how the subject feature works in
practice.

TROUBLESHOOTING

Instructions for resolving common problems.

SEE ALSO

Text-only references for further reading. Hyperlinks can't work in the
PowerShell console.

    您可以使用任何您想要的樣式和標記，但 PowerShell 會將其視為純文字，而且 PowerShell 主控台中沒有文字的特殊轉譯。 以下建議可確保最佳的顯示效果和可讀性。

    • 使用 UTF-8 搭配 BOM 編碼，以確保任何特殊 （多位元組） 字元正確顯示。
    • 在章節標題下劃線或使用所有大寫字母以使其脫穎而出。這使得內容更容易掃描。
    • 將每行的長度限制為 80 個字元。
    • 縮排程式碼區塊和範例輸出，以將它們與周圍的散文分開。

模組說明的放置

Cmdlet 會在 Get-Help 模組目錄的語言特定子目錄中尋找模組說明主題檔案。

例如，下列目錄結構圖顯示 SampleModule 模組的說明主題位置。

<ModulePath>
    \SampleModule
        \<en-US>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml
        \<fr-FR>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml

備註

在此範例中， <ModulePath> 預留位置代表環境變數中的 PSModulePath 其中一個路徑，例如 $HOME\Documents\Modules、 或 $PSHOME\Modules使用者指定的自訂路徑。

取得模組說明

當使用者將模組匯入階段作業時，該模組的說明主題會與模組一起匯入階段作業。 您可以在模組資訊清單中 FileList 索引鍵的值中列出說明主題檔案，但說明主題不會受到 Export-ModuleMember Cmdlet 的影響。

您可以提供不同語言的模組說明主題。 Cmdlet 會自動 Get-Help 以 [控制台] 的 [區域和語言選項] 項目中為目前使用者指定的語言顯示模組說明主題。 在 Windows Vista 和更新版本的 Windows 中， Get-Help 會根據針對 Windows 建立的語言後援標準，在模組目錄的語言特定子目錄中搜尋說明主題。

從 PowerShell 3.0 開始，執行 Get-Help Cmdlet 或函式的命令會觸發模組的自動匯入。 Get-Help Cmdlet 會立即顯示模組中說明主題的內容。

如果模組不包含說明主題，且使用者電腦上模組中沒有命令的說明主題， Get-Help 則會顯示自動產生的說明。 自動產生的說明包含命令語法、參數以及輸入和輸出類型，但不包含任何描述。 自動產生的說明包含文字，可指示使用者嘗試使用 Cmdlet 從 Update-Help 因特網或檔案共用下載命令的說明。 它也建議使用 Cmdlet 的 Get-Help 參數來取得說明主題的線上版本。

支援可更新的說明

PowerShell 3.0 和更新版本的 PowerShell 使用者可以從因特網或本機檔案共用下載並安裝模組的更新說明檔案。 和 Update-Help Cmdlet 會Save-Help向使用者隱藏管理詳細資料。 使用者會執行 Update-Help Cmdlet，然後使用 Cmdlet 在 Get-Help PowerShell 命令提示字元讀取模組的最新說明檔案。 使用者不需要重新啟動 Windows 或 PowerShell。

防火牆後面的使用者和無法存取網際網路的使用者也可以使用可更新的說明。 具有網際網路存取權的系統管理員會使用 Cmdlet 將 Save-Help 最新的說明檔案下載並安裝至檔案共用。 然後，使用者會使用 Cmdlet 的 Update-Help Path 參數，從檔案共用取得最新的說明檔案。

模組作者可以在模組中包含說明檔，並使用可更新的說明來更新說明檔，或從模組中省略說明檔，並使用可更新的說明來安裝和更新它們。

如需可更新說明的詳細資訊，請參閱 支援可更新的說明。

支援線上說明

無法或不在其電腦上安裝更新說明檔案的使用者通常依賴模組說明主題的線上版本。 Cmdlet 的 Get-Help 參數會在使用者的預設網際網路瀏覽器中開啟 Cmdlet 或進階函式說明主題的線上版本。

Get-Help Cmdlet 會使用 Cmdlet 或函式的 HelpUri 屬性值來尋找說明主題的線上版本。

從 PowerShell 3.0 開始，您可以在 Cmdlet 類別上定義 HelpUri 屬性，或定義 CmdletBinding 屬性的 HelpUri 屬性，以協助使用者尋找 Cmdlet 和函式說明主題的線上版本。 屬性的值是 Cmdlet 或函式的 HelpUri 屬性值。

如需詳細資訊，請參閱 支援線上說明。

另請參閱

  • Last updated on