Добавление синтаксиса в раздел справки по командлетам

Статья
03/25/2025

Примечание.

Создание справки на основе XML вручную очень сложно. Модуль PlatyPS позволяет написать справку в Markdown, а затем преобразовать ее в справку на основе XML. Это упрощает запись и обслуживание справки. PlatyPS также можно создать пакеты справки с возможностью обновления. Дополнительные сведения см. в статье Создание XML-справки с помощьюPlatyPS.

Прежде чем приступить к коду XML для схемы синтаксиса в файле справки командлета, ознакомьтесь с этим разделом, чтобы получить четкое представление о типе данных, которые необходимо предоставить, например атрибуты параметров, и как эти данные отображаются на схеме синтаксиса.

Атрибуты параметра

Обязательный
- Если значение true, параметр должен отображаться во всех командах, использующих набор параметров.
- Если значение false, параметр является необязательным во всех командах, использующих набор параметров.
Позиция
- При именовании имя параметра является обязательным.
- Если позиция, имя параметра является необязательным. Если он опущен, значение параметра должно находиться в указанной позиции в команде. Например, если значение имеет значение position="1", значение параметра должно быть первым или единственным неименованным значением параметра в команде.
Входные данные конвейера
- Если значение true (ByValue), можно передать входные данные в параметр. Входные данные связаны с параметром (привязано к) даже если имя свойства и тип объекта не соответствуют ожидаемому типу. Компоненты привязки параметров PowerShell пытаются преобразовать входные данные в правильный тип и завершить команду ошибкой, только если тип не может быть преобразован. Только один параметр в наборе параметров может быть связан по значению.
- Если значение true (ByPropertyName), можно передать входные данные в параметр. Однако входные данные связаны с параметром только в том случае, если имя параметра соответствует имени свойства входного объекта. Например, если имя параметра Path, объекты, переданные командлету, связаны с этим параметром только в том случае, если объект имеет свойство с именем пути.
- Если значение true (ByValue, ByPropertyName), можно передать входные данные в параметр по имени свойства или по значению. Только один параметр в наборе параметров может быть связан по значению.
- Если значение false, входные данные в этот параметр невозможно передать.
Глоббинг
- Если задано значение true, текст, который пользователь вводит для значения параметра, может содержать подстановочные знаки.
- Если значение false, текст, который пользователь вводит для значения параметра, не может содержать подстановочные знаки.

Атрибуты значения параметра

Обязательный
- Если значение равно true, указанное значение должно использоваться всякий раз при использовании параметра в команде.
- Если значение равно false, значение параметра является необязательным. Как правило, значение является необязательным, только если это одно из нескольких допустимых значений для параметра, например в перечисленном типе.

Атрибут обязательного значения параметра отличается от атрибута обязательного параметра.

Обязательный атрибут параметра указывает, должен ли параметр (и его значение) быть включен при вызове командлета. Напротив, обязательный атрибут значения параметра используется только в том случае, если параметр включен в команду. Указывает, следует ли использовать конкретное значение с параметром.

Как правило, значения параметров, которые являются заполнителями, являются обязательными, и значения параметров, которые являются литеральными, не требуются, так как они являются одним из нескольких значений, которые могут использоваться с параметром.

Сбор сведений о синтаксисе

Начните с имени командлета.
```
SYNTAX
    Get-Tech
```
Список всех параметров командлета. Введите дефис (-) перед каждым именем параметра. Разделите параметры на наборы параметров (некоторые командлеты могут иметь только один набор параметров). В этом примере командлет Get-Tech имеет два набора параметров.
```
SYNTAX
    Get-Tech -Name -Type
    Get-Tech -Id -List -Type
```
Запустите каждый набор параметров с именем командлета.

Сначала выведите список параметров по умолчанию. Параметр по умолчанию задается классом командлета.

Для каждого набора параметров сначала укажите уникальный параметр, если только не должны отображаться позиционные параметры. В предыдущем примере параметры Name и Id являются уникальными параметрами для двух наборов параметров (каждый набор параметров должен иметь один параметр, уникальный для этого набора параметров). Это упрощает для пользователей определение того, какой параметр необходимо указать для набора параметров.

Выведите список параметров в том порядке, в который они должны отображаться в команде. Если порядок не имеет значения, перечислить связанные параметры вместе или сначала перечислить наиболее часто используемые параметры.

Не забудьте указать параметры WhatIf и Confirm, если командлет поддерживает ShouldProcess.

Не перечисляйте общие параметры (например, подробные сведения, отладка и errorAction) на схеме синтаксиса. Командлет Get-Help добавляет эти сведения для вас при отображении раздела справки.
Добавьте значения параметров. В PowerShell значения параметров представлены их типом .NET. Однако имя типа может быть сокращено, например string для System.String.
```
SYNTAX
    Get-Tech -Name string -Type Basic Advanced
    Get-Tech -Id int -List -Type Basic Advanced
```
Сокращенные типы, если их значение ясно, например строковые для System.String и int для System.Int32.

Перечислите все значения перечислений, например параметр -Type в предыдущем примере, который можно задать для базовых или расширенных.

Параметры переключения, такие как -List в предыдущем примере, не имеют значений.
Добавьте угловые скобки в значения параметров, которые являются заполнителями, по сравнению с значениями параметров, которые являются литералами.
```
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]
```
Заключите необязательные имена параметров (для позиционных параметров) в квадратные скобки. Имя параметров, которые являются позициальными, например параметром 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>. Сведения о сборе данных, используемых на схеме синтаксиса, см. в разделе Сбор сведений о синтаксисе.

Добавление синтаксического узла

Схема синтаксиса, отображаемая в разделе справки командлета, создается из данных в узле синтаксиса XML. Узел синтаксиса заключен в пару тегов <command:syntax>. С каждым набором параметров командлета, заключенного в пару <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>

Добавление имени командлета в данные набора параметров

Каждый набор параметров командлета указан в узле элемента синтаксиса. Каждый узел элемента синтаксиса начинается с пары тегов <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. Чтобы избежать несоответствий между сведениями в элементах синтаксиса и узлом параметров, опустите (<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>

Поделиться через