Jak dodać składnię do tematu pomocy dotyczącego polecenia cmdlet

Artykuł
09/25/2021

Zanim zaczniesz kodować kod XML dla diagramu składniowego w pliku pomocy polecenia cmdlet, przeczytaj tę sekcję, aby uzyskać jasny obraz rodzaju danych, które należy podać, takich jak atrybuty parametrów i sposób wyświetlania tych danych na diagramie składni.

Atrybuty parametru

Wymagane
- W przypadku wartości true parametr musi znajdować się we wszystkich poleceniach, które używają zestawu parametrów.
- W przypadku wartości false parametr jest opcjonalny we wszystkich poleceniach, które używają zestawu parametrów.
Położenie
- Jeśli nazwane, nazwa parametru jest wymagana.
- Jeśli ma wartość pozycyjną, nazwa parametru jest opcjonalna. Jeśli zostanie pominięty, wartość parametru musi znajdować się w określonej pozycji w poleceniu. Jeśli na przykład wartość to position="1", wartość parametru musi być pierwszą lub jedyną nienazwanej wartością parametru w poleceniu.
Dane wejściowe potoku
- W przypadku wartości true (ByValue) można potokować dane wejściowe do parametru . Dane wejściowe są skojarzone z parametrem ("powiązana z"), nawet jeśli nazwa właściwości i typ obiektu nie są zgodne z oczekiwanym typem. Składniki powiązania parametrów programu PowerShell próbują przekonwertować dane wejściowe na poprawny typ i nie mogą wykonać polecenia tylko wtedy, gdy nie można przekonwertować typu. Tylko jeden parametr w zestawie parametrów może być skojarzony przez wartość.
- W przypadku wartości true (ByPropertyName) można potokować dane wejściowe do parametru . Jednak dane wejściowe są skojarzone z parametrem tylko wtedy, gdy nazwa parametru odpowiada nazwie właściwości obiektu wejściowego. Jeśli na przykład nazwa parametru to , obiekty potokowe do polecenia cmdlet są skojarzone z tym parametrem tylko wtedy, gdy obiekt ma Path właściwość o nazwie path.
- W przypadku wartości true (ByValue, ByPropertyName) można potokować dane wejściowe do parametru według nazwy właściwości lub wartości. Tylko jeden parametr w zestawie parametrów może być skojarzony przez wartość.
- W przypadku wartości false nie można potokować danych wejściowych do tego parametru.
Globbing
- W przypadku wartości true tekst, który użytkownik typi dla wartości parametru, może zawierać symbole wieloznaczne.
- W przypadku wartości false tekst, który użytkownik typi dla wartości parametru, nie może zawierać symboli wieloznacznych.

Atrybuty wartości parametru

Wymagane
- W przypadku wartości true określona wartość musi być używana za każdym razem, gdy parametr jest używany w poleceniu.
- W przypadku wartości false wartość parametru jest opcjonalna. Zazwyczaj wartość jest opcjonalna tylko wtedy, gdy jest jedną z kilku prawidłowych wartości parametru, takich jak typ wyliczany.

Wymagany atrybut wartości parametru różni się od wymagane atrybutu parametru.

Wymagany atrybut parametru wskazuje, czy parametr (i jego wartość) musi zostać uwzględniony podczas wywołania polecenia cmdlet. Z kolei wymagany atrybut wartości parametru jest używany tylko wtedy, gdy parametr jest uwzględniony w poleceniu . Wskazuje, czy ta wartość musi być używana z parametrem .

Zazwyczaj wartości parametrów, które są symbolami zastępczymi, są wymagane, a wartości parametrów, które są literału nie są wymagane, ponieważ są one jedną z kilku wartości, które mogą być używane z parametrem .

Zbieranie informacji o składni

Rozpocznij od nazwy polecenia cmdlet .
```
SYNTAX
    Get-Tech
```
Lista wszystkich parametrów polecenia cmdlet. Przed nazwą każdego parametru wpisz łącznik ( - ) (ASCII 45). Rozdziel parametry na zestawy parametrów (niektóre polecenia cmdlet mogą mieć tylko jeden zestaw parametrów). W tym przykładzie Get-Tech cmdlet ma dwa zestawy parametrów.
```
SYNTAX
    Get-Tech -name -type
    Get-Tech -ID -list -type
```
Uruchom każdy zestaw parametrów przy użyciu nazwy polecenia cmdlet .

Najpierw należy wyświetlić domyślny zestaw parametrów. Domyślny parametr jest określony przez klasę polecenia cmdlet .

Dla każdego zestawu parametrów należy najpierw wyświetlić jego unikatowy parametr, chyba że istnieją parametry pozyacyjne, które muszą pojawić się jako pierwsze. W poprzednim przykładzie parametry Name i ID są unikatowymi parametrami dla dwóch zestawów parametrów (każdy zestaw parametrów musi mieć jeden parametr, który jest unikatowy dla tego zestawu parametrów). Ułatwia to użytkownikom identyfikowanie parametru, który muszą podać dla zestawu parametrów.

Wyświetla listę parametrów w kolejności, w których powinny pojawić się w poleceniu . Jeśli kolejność nie ma znaczenia, należy najpierw wyświetlić powiązane parametry lub wyświetlić listę najczęściej używanych parametrów.

Pamiętaj, aby wyświetlić parametry WhatIf i Confirm, jeśli polecenie cmdlet obsługuje funkcję ShouldProcess.

Nie należy zwracać listy typowych parametrów (takich jak Verbose, Debug i ErrorAction) w diagramie składni. Polecenie Get-Help cmdlet dodaje te informacje podczas wyświetlania tematu Pomocy.
Dodaj wartości parametrów. W programie PowerShell wartości parametrów są reprezentowane przez ich typ .NET. Jednak nazwę typu można nazwać, na przykład "string" dla System.String.
```
SYNTAX
    Get-Tech -name string -type basic advanced
    Get-Tech -ID int -list -type basic advanced
```
Skrócone typy, o ile ich znaczenie jest jasne, na przykład ciąg dla System.String i int dla System.Int32.

Lista wszystkich wartości wyliczeń, takich jak parametr w poprzednim przykładzie, który można ustawić na -type wartość podstawową lub zaawansowaną.

Parametry przełącznika, takie -list jak w poprzednim przykładzie, nie mają wartości.
Dodaj nawiasy kątowe do wartości parametrów, które są symbolami zastępczymi, w porównaniu z wartościami parametrów, które są literałami.
```
SYNTAX
    Get-Tech -name <string> -type basic advanced
    Get-Tech -ID <int> -list -type basic advanced
```

Ujmij parametry opcjonalne i ich wartości w nawiasy kwadratowe.

SYNTAX
    Get-Tech -name <string> [-type basic advanced]
    Get-Tech -ID <int> [-list] [-type basic advanced]

Nazwy parametrów opcjonalnych (dla parametrów pozytywnych) należy ująć w nawiasy kwadratowe. Nazwa parametrów, które są pozyacyjne, takich jak Nazwa parametru w poniższym przykładzie, nie muszą być uwzględnione w poleceniu.
```
SYNTAX
    Get-Tech [-name] <string> [-type basic advanced]
    Get-Tech -ID <int> [-list] [-type basic advanced]
```
Jeśli wartość parametru może zawierać wiele wartości, takich jak lista nazw w parametrze Name, dodaj parę nawiasów kwadratowych bezpośrednio po wartości parametru.
```
SYNTAX
    Get-Tech [-name] <string[]> [-type basic advanced]
    Get-Tech -ID <int[]> [-list] [-type basic advanced]
```
Jeśli użytkownik może wybrać spośród parametrów lub wartości parametrów, takich jak parametr Type, ujmij opcje w nawiasy klamrowe i rozdziel je wyłącznym symbolem OR (;)).
```
SYNTAX
    Get-Tech [-name] <string[]> [-type {basic | advanced}]
    Get-Tech -ID <int[]> [-list] [-type {basic | advanced}]
```
Jeśli wartość parametru musi używać określonego formatowania, takiego jak znaki cudzysłowu lub nawiasy, wyświetl format w składni.
```
SYNTAX
    Get-Tech [-name] <"string[]"> [-type {basic | advanced}]
    Get-Tech -ID <int[]> [-list] [-type {basic | advanced}]
```

Kodowanie kodu XML diagramu składniowego

Węzeł składni kodu XML rozpoczyna się bezpośrednio po węźle opisu, który kończy się </maml:description> tagiem . Aby uzyskać informacje o zbieraniu danych używanych na diagramie składniowym, zobacz Zbieranie informacji o składni.

Dodawanie węzła składni

Diagram składni wyświetlany w temacie pomocy polecenia cmdlet jest generowany na podstawie danych w węźle składni kodu XML. Węzeł składni jest ujęty w parę <command:syntax> tagów. Z każdym zestawem parametrów polecenia cmdlet ujętym w parę <command:syntaxitem> tagów. Nie ma żadnego ograniczenia liczby <command:syntaxitem> tagów, które można dodać.

W poniższym przykładzie pokazano węzeł składni, który ma węzły elementów składni dla dwóch zestawów parametrów.

<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>

Dodawanie nazwy polecenia cmdlet do danych zestawu parametrów

Każdy zestaw parametrów polecenia cmdlet jest określony w węźle elementu składni. Każdy węzeł elementu składni rozpoczyna się od pary <maml:name> tagów, które zawierają nazwę polecenia cmdlet.

Poniższy przykład zawiera węzeł składni, który ma węzły elementów składni dla dwóch zestawów parametrów.

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

Dodawanie parametrów

Każdy parametr dodany do węzła elementu składni jest określony w parze <command:parameter> tagów. Potrzebujesz pary tagów dla każdego parametru zawartego w zestawie parametrów, z wyjątkiem typowych parametrów, które <command:parameter> są dostarczane przez program PowerShell.

Atrybuty tagu otwierającego <command:parameter> określają, jak parametr jest wyświetlany na diagramie składni. Aby uzyskać informacje na temat atrybutów parametrów, zobacz Atrybuty parametrów.

Uwaga

Tag <command:parameter> obsługuje element <maml:description> podrzędny, którego zawartość nigdy nie jest wyświetlana. Opisy parametrów są określone w węźle parametrów XML. Aby uniknąć niespójności między informacjami w treści elementu składni i węźle parametru, pomiń element ( lub <maml:description> pozostaw go pusty.

Poniższy przykład zawiera węzeł elementu składni dla zestawu parametrów z dwoma parametrami.

<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>