如何將語法新增至 Cmdlet 說明主題

備註

手動撰寫 XML 型說明是非常困難的。 PlatyPS 模組可讓您在 Markdown 中撰寫說明，然後將它轉換成 XML 型說明。這可讓您更輕鬆地撰寫和維護說明。 PlatyPS 也可以為您建立可更新的說明套件。如需詳細資訊，請參閱使用 PlatyPS建立 XML 型說明。

開始撰寫 Cmdlet 說明檔中語法圖表的 XML 程式代碼之前，請先閱讀本節，以清楚瞭解您需要提供的數據種類，例如參數屬性，以及該數據在語法圖表中的顯示方式。

參數屬性

必要
- 如果為 true，參數必須出現在所有使用參數集的命令中。
- 如果為 false，則參數在使用參數集的所有命令中都是選擇性的。
位置
- 如果命名，則需要參數名稱。
- 如果為位置，則參數名稱是選擇性的。省略時，參數值必須位於命令中指定的位置。例如，如果值是 position=“1”，參數值必須是命令中第一個或只有未命名的參數值。
管線輸入
- 如果為 true （ByValue），您可以使用管線將輸入傳送至參數。即使屬性名稱和物件類型不符合預期的類型，輸入仍與參數相關聯（“bound to”）參數。 PowerShell 參數係結元件會嘗試將輸入轉換成正確的類型，而且只有在無法轉換類型時，命令才會失敗。參數集中只有一個參數可以依值相關聯。
- 如果為 true （ByPropertyName），您可以使用管線將輸入傳送至參數。不過，只有在參數名稱符合輸入物件屬性的名稱時，輸入才會與參數相關聯。例如，如果參數名稱是 Path，則只有在物件具有具名路徑的屬性時，傳送至 Cmdlet 的物件才會與該參數相關聯。
- 如果為 true（ByValue、ByPropertyName），您可以透過屬性名稱或值將輸入管線傳送至參數。參數集中只有一個參數可以依值相關聯。
- 如果為 false，您無法使用管線將輸入傳送至此參數。
Globbing
- 如果為 true，則用戶為參數值輸入的文字可以包含通配符。
- 如果為 false，則用戶為參數值輸入的文字不能包含通配符。

參數值屬性

必要
- 如果為 true，則每當在命令中使用參數時，都必須使用指定的值。
- 如果為 false，則參數值是選擇性的。一般而言，值只有在參數是數個有效值之一時，才為選擇性值，例如在列舉型別中。

參數值的 Required 屬性與參數的 Required 属性不同。

參數的必要屬性會指出叫用 Cmdlet 時，是否必須包含參數（及其值）。相反地，只有在命令中包含參數時，才會使用參數值的必要屬性。它指出該特定值是否必須與參數搭配使用。

一般而言，佔位元符的參數值是必要的，而且不是常值的參數值，因為它們是可能搭配參數使用的數個值之一。

收集語法資訊

從 Cmdlet 名稱開始。
```
SYNTAX
    Get-Tech
```
列出 Cmdlet 的所有參數。在每個參數名稱之前輸入連字元（-）。將參數分成參數集（某些 Cmdlet 可能只有一個參數集）。在此範例中，Get-Tech Cmdlet 有兩個參數集。
```
SYNTAX
    Get-Tech -Name -Type
    Get-Tech -Id -List -Type
```
使用 Cmdlet 名稱啟動每個參數集。

先列出預設參數集。默認參數是由 Cmdlet 類別所指定。

針對每個參數集，請先列出其唯一參數，除非有必須先出現的位置參數。在上一個範例中，Name 和 Id 參數是兩個參數集的唯一參數（每個參數集都必須有一個參數，該參數集是唯一的參數）。這可讓使用者更輕鬆地識別為參數集提供哪些參數。

以命令中應顯示的順序列出參數。如果順序不重要，請一起列出相關的參數，或先列出最常使用的參數。

如果 Cmdlet 支援 ShouldProcess，請務必列出 WhatIf 和 Confirm 參數。

請勿在語法圖表中列出通用參數（例如 Verbose、Debug 和 ErrorAction）。 Get-Help Cmdlet 會在顯示說明主題時為您新增該資訊。
新增參數值。在 PowerShell 中，參數值會以其 .NET 類型表示。不過，可以縮寫類型名稱，例如 System.String 的 “string”。
```
SYNTAX
    Get-Tech -Name string -Type Basic Advanced
    Get-Tech -Id int -List -Type Basic Advanced
```
只要其意義明確，請縮寫類型，例如 System.String 的字串，以及 System.Int32int。

列出列舉的所有值，例如上一個範例中的 -Type 參數，可設定為基本或進階。

切換參數，例如上一個範例中的 -List，沒有值。

將角括弧新增至佔位符的參數值，與常值的參數值相較之下。

SYNTAX
    Get-Tech -Name <string> -Type Basic Advanced
    Get-Tech -Id <int> -List -Type Basic Advanced

以方括弧括住選擇性參數及其 vales。

SYNTAX
    Get-Tech -Name <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]

以方括弧括住選擇性參數名稱（適用於位置參數）。位置的參數名稱，例如下列範例中的 Name 參數，不需要包含在命令中。
```
SYNTAX
    Get-Tech [-Name] <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]
```
如果參數值可以包含多個值，例如 Name 參數中的名稱清單，請直接在參數值之後新增一組方括弧。
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type Basic Advanced]
    Get-Tech -Id <int[]> [-List] [-Type Basic Advanced]
```
如果使用者可以從參數或參數值中選擇，例如 Type 參數，請將選項括在大括弧中，並以獨佔 OR 符號分隔它們（;)。
```
SYNTAX
    Get-Tech [-Name] <string[]> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]
```

如果參數值必須使用特定的格式設定，例如引號或括弧，請在語法中顯示格式。

SYNTAX
    Get-Tech [-Name] <"string[]"> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]

撰寫語法圖表 XML 程式代碼

XML 的語法節點會在描述節點之後立即開始，其結尾為 </maml:description> 標籤。如需收集語法圖表中所用資料的資訊，請參閱收集語法資訊。

新增語法節點

Cmdlet 說明主題中顯示的語法圖表是從 XML 語法節點中的數據產生。語法節點會以一組 <command:syntax> 標記括住。每個參數集的 Cmdlet 都以一組 <command:syntaxitem> 標記括住。您可以新增的 <command:syntaxitem> 標籤標數目沒有限制。

下列範例顯示具有兩個參數集之語法項目節點的語法節點。

<command:syntax>
  <command:syntaxItem>
    ...
    <!--Parameter Set 1 (default parameter set) parameters go here-->
    ...
  </command:syntaxItem>
  <command:syntaxItem>
    ...
    <!--Parameter Set 2 parameters go here-->
    ...
  </command:syntaxItem>
</command:syntax>

將 Cmdlet 名稱新增至參數集數據

Cmdlet 的每個參數集都會在語法項目節點中指定。每個語法項目節點的開頭都是一對包含 Cmdlet 名稱的 <maml:name> 標記。

下列範例包含具有兩個參數集之語法項目節點的語法節點。

<command:syntax>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
</command:syntax>

新增參數

每個新增至語法項目節點的參數都會在一組 <command:parameter> 標記內指定。針對參數集中包含的每個參數，您需要一組 <command:parameter> 標籤，但 PowerShell 所提供的一般參數除外。

開頭 <command:parameter> 標記的屬性會決定參數在語法圖表中的顯示方式。如需參數屬性的詳細資訊，請參閱參數屬性。

備註

<command:parameter> 標記支持永遠不會顯示其內容的子專案 <maml:description>。參數描述是在 XML 的參數節點中指定。若要避免語法專案 bodes 與參數節點中的資訊不一致，請省略（<maml:description> 或將它保留空白。

下列範例包含具有兩個參數之參數集的語法項目節點。

<command:syntaxItem>
  <maml:name>Cmdlet-Name</maml:name>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByValue)" position="1">
    <maml:name>ParameterName1</maml:name>
    <command:parameterValue required="true">
      string[]
    </command:parameterValue>
  </command:parameter>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByPropertyName)">
    <maml:name>ParameterName2</maml:name>
    <command:parameterValue required="true">
      int32[]
    </command:parameterValue>
  </command:parameter>
</command:syntaxItem>

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-03-25