Udostępnij za pomocą

Jak dodać składnię do tematu pomocy dotyczącej poleceń cmdlet

Uwaga

Ręczne tworzenie pomocy opartej na języku XML jest bardzo trudne. Moduł PlatyPS umożliwia napisanie pomocy w języku Markdown, a następnie przekonwertowanie go na pomoc opartą na języku XML. Ułatwia to pisanie i konserwację pomocy. platyPS można również utworzyć pakiety Pomocy z możliwością aktualizacji. Aby uzyskać więcej informacji, zobacz Create XML-based help using PlatyPS.

Zanim zaczniesz kodować kod XML dla diagramu składni 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

  • Wymagany
    • Jeśli wartość true, parametr musi być wyświetlany we wszystkich poleceniach używających zestawu parametrów.
    • Jeśli wartość false, parametr jest opcjonalny we wszystkich poleceniach używających zestawu parametrów.
  • Pozycja
    • Jeśli nazwa jest nazwana, wymagana jest nazwa parametru.
    • Jeśli pozycyjna, nazwa parametru jest opcjonalna. Po jej pominięciu 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ą wartością parametru bez nazwy w poleceniu.
  • Dane wejściowe potoku
    • Jeśli wartość true (ByValue), możesz przekazać dane wejściowe do parametru. Dane wejściowe są skojarzone z parametrem ("bound to"), 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 zakończyć działaniem polecenia tylko wtedy, gdy nie można przekonwertować typu. Wartość może skojarzyć tylko jeden parametr w zestawie parametrów.
    • Jeśli wartość true (ByPropertyName), możesz przekazać dane wejściowe do parametru. Jednak dane wejściowe są skojarzone z parametrem tylko wtedy, gdy nazwa parametru jest zgodna z nazwą właściwości obiektu wejściowego. Jeśli na przykład nazwa parametru jest Path, obiekty przesyłane potokiem do polecenia cmdlet są skojarzone z tym parametrem tylko wtedy, gdy obiekt ma właściwość o nazwie path.
    • Jeśli wartość true (ByValue, ByPropertyName), możesz przekazać dane wejściowe do parametru za pomocą nazwy właściwości lub wartości. Wartość może skojarzyć tylko jeden parametr w zestawie parametrów.
    • Jeśli wartość false, nie można przekazać danych wejściowych potoku do tego parametru.
  • Globbing
    • Jeśli wartość true, tekst, który użytkownik wpisze dla wartości parametru, może zawierać symbole wieloznaczne.
    • Jeśli wartość false, tekst, który użytkownik wpisze dla wartości parametru, nie może zawierać symboli wieloznacznych.

Atrybuty wartości parametru

  • Wymagany
    • Jeśli wartość true, określona wartość musi być używana za każdym razem, gdy użyj parametru w poleceniu.
    • Jeśli wartość false, wartość parametru jest opcjonalna. Zazwyczaj wartość jest opcjonalna tylko wtedy, gdy jest to jedna z kilku prawidłowych wartości parametru, na przykład w typie wyliczanym.

Atrybut Required wartości parametru różni się od atrybutu Required parametru.

Wymagany atrybut parametru wskazuje, czy parametr (i jego wartość) należy uwzględnić podczas wywoływania polecenia cmdlet. Natomiast wymagany atrybut wartości parametru jest używany tylko wtedy, gdy parametr jest uwzględniony w poleceniu. Wskazuje, czy określona 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łami, nie są wymagane, ponieważ są one jedną z kilku wartości, które mogą być używane z parametrem .

Zbieranie informacji o składni

  1. Zacznij od nazwy polecenia cmdlet.

    SYNTAX
    Get-Tech

  2. Wyświetl listę wszystkich parametrów polecenia cmdlet. Wpisz łącznik (-) przed każdą nazwą parametru. Rozdziel parametry na zestawy parametrów (niektóre polecenia cmdlet mogą mieć tylko jeden zestaw parametrów). W tym przykładzie polecenie cmdlet Get-Tech 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.

    Wyświetl najpierw domyślny zestaw parametrów. Domyślny parametr jest określany przez klasę poleceń cmdlet.

    Dla każdego zestawu parametrów należy najpierw wyświetlić jego unikatowy parametr, chyba że istnieją parametry pozycyjne, 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 unikatowy dla tego zestawu parametrów). Ułatwia to użytkownikom identyfikowanie parametrów, które muszą podać dla zestawu parametrów.

    Wyświetl listę parametrów w kolejności, w której powinny być wyświetlane w poleceniu. Jeśli kolejność nie ma znaczenia, wyświetl powiązane parametry razem lub wyświetl najpierw najczęściej używane parametry.

    Pamiętaj, aby wyświetlić listę parametrów WhatIf i Confirm, jeśli polecenie cmdlet obsługuje metodę ShouldProcess.

    Nie wyświetlaj listy typowych parametrów (takich jak Pełne, Debugowanie i BłądAction) na diagramie składniowym. Polecenie cmdlet Get-Help dodaje te informacje podczas wyświetlania tematu Pomocy.

  3. Dodaj wartości parametrów. W programie PowerShell wartości parametrów są reprezentowane przez ich typ .NET. Można jednak skrócić nazwę typu, taką jak "ciąg" dla parametru System.String.

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

    Typy skrótów tak długo, jak ich znaczenie jest jasne, takie jak ciąg dla System.String i int int dla System.Int32.

    Wyświetl listę wszystkich wartości wyliczenia, takich jak parametr -Type w poprzednim przykładzie, które można ustawić na podstawowe lub zaawansowane.

    Parametry przełącznika, takie jak -List w poprzednim przykładzie, nie mają wartości.

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

  5. Ujęć parametry opcjonalne i ich wartości w nawiasach kwadratowych.

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

  6. Dołącz opcjonalne nazwy parametrów (dla parametrów pozycyjnych) w nawiasach kwadratowych. Nazwa parametrów, które są pozycyjne, takie jak Nazwa parametru w poniższym przykładzie, nie musi być uwzględniona w poleceniu.

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

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

  8. Jeśli użytkownik może wybrać spośród parametrów lub wartości parametrów, takich jak parametr Type, należy ująć opcje w nawiasy klamrowe i oddzielić je wyłącznie symbolem OR(;).

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

  9. Jeśli wartość parametru musi używać określonego formatowania, takiego jak znaki cudzysłowu lub nawiasy, pokaż 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ę natychmiast po węźle opisu, który kończy się tagiem </maml:description>. Aby uzyskać informacje na temat zbierania 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ęta w parę tagów <command:syntax>. W przypadku każdego zestawu parametrów polecenia cmdlet ujętego w parę <command:syntaxitem> tagów. Nie ma limitu liczby tagów <command:syntaxitem>, 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 zawiera 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 ramach pary tagów <command:parameter>. Potrzebujesz pary tagów <command:parameter> dla każdego parametru uwzględnionego w zestawie parametrów, z wyjątkiem typowych parametrów udostępnianych przez program PowerShell.

Atrybuty otwierającego tagu <command:parameter> określają sposób wyświetlania parametru na diagramie składniowym. Aby uzyskać informacje na temat atrybutów parametrów, zobacz Atrybuty parametrów.

Uwaga

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

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>
  • Last updated on