Jak dodać przykłady do tematu pomocy dotyczącego polecenia cmdletHow to Add Examples to a Cmdlet Help Topic

Informacje o przykładach w pomocy polecenia cmdletThings to Know about Examples in Cmdlet Help

  • Wyświetl listę wszystkich nazw parametrów w poleceniu, nawet jeśli nazwy parametrów są opcjonalne.List all of the parameter names in the command, even when the parameter names are optional. Dzięki temu użytkownik może łatwo interpretować polecenie.This helps the user to interpret the command easily.

  • Unikaj aliasów i nazw parametrów częściowych, nawet jeśli są one wykonywane w programie PowerShell.Avoid aliases and partial parameter names, even though they work in PowerShell.

  • W przykładowym opisie Wyjaśnij uzasadnienie dla konstruowania polecenia.In the example description, explain the rational for the construction of the command. Wyjaśnij, dlaczego wybrano określone parametry i wartości oraz jak używać zmiennych.Explain why you chose particular parameters and values, and how you use variables.

  • Jeśli polecenie używa wyrażeń, wyjaśnij je szczegółowo.If the command uses expressions, explain them in detail.

  • Jeśli w poleceniu są używane właściwości i metody obiektów, szczególnie właściwości, które nie są wyświetlane na ekranie domyślnym, użyj przykładu jako możliwości poinformowania użytkownika o obiekcie.If the command uses properties and methods of objects, especially properties that do not appear in the default display, use the example as an opportunity tell the user about the object.

Widoki pomocy, w których są wyświetlane przykładyHelp Views that Display Examples

Przykłady są wyświetlane tylko w szczegółowych i pełnych widokach pomocy poleceń cmdlet.Examples appear only in the Detailed and Full views of cmdlet Help.

Dodawanie węzła przykładyAdding an Examples Node

Poniższy kod XML pokazuje, jak dodać węzeł przykładów , który zawiera pojedynczy przykładowy węzeł.The following XML shows how to add an Examples node that contains a single Example node. Dodaj dodatkowe przykładowe węzły dla każdego przykładu, który ma zostać uwzględniony w temacie.Add additional example nodes for each examples you want to include in the topic.

<command:examples>
  <command:example>
  </command:example>
</command:examples>

Dodawanie przykładowego tytułuAdding an Example Title

Poniższy kod XML pokazuje, jak dodać tytuł dla przykładu.The following XML shows how to add a title for the example. Tytuł jest używany do ustawienia przykładu, a nie innych przykładów.The title is used to set the example apart from other examples. Program PowerShell korzysta ze standardowego nagłówka zawierającego numer sekwencyjny.PowerShell uses a standard header that includes a sequential example number.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
  </command:example>
</command:examples>

Dodawanie poprzedzających znakówAdding Preceding Characters

W poniższym kodzie XML pokazano, jak dodać znaki, takie jak wiersz polecenia programu Windows PowerShell, które są wyświetlane bezpośrednio przed przykładowym poleceniem (bez żadnych spacji interwencji).The following XML shows how to add characters, such as the Windows PowerShell prompt, that are displayed immediately before the example command (without any intervening spaces). Program PowerShell używa wiersza polecenia programu Windows PowerShell: C:\PS> .PowerShell uses the Windows PowerShell prompt: C:\PS>.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
</command:example>
</command:examples>

Dodawanie poleceniaAdding the Command

Poniższy kod XML pokazuje, jak dodać rzeczywiste polecenie z przykładu.The following XML shows how to add the actual command of the example. Podczas dodawania polecenia wpisz całą nazwę (nie używaj aliasu) poleceń cmdlet i parametrów.When adding the command, type the entire name (do not use alias) of cmdlets and parameters. Ponadto używaj małych liter, gdy tylko jest to możliwe.Also, use lowercase characters whenever possible.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
    <dev:code> command </dev:code>
</command:example>
</command:examples>

Dodawanie opisuAdding a Description

Poniższy kod XML pokazuje, jak dodać opis dla przykładu.The following XML shows how to add a description for the example. Program PowerShell używa jednego zestawu <maml:para> tagów do opisu, nawet jeśli <maml:para> można użyć wielu tagów.PowerShell uses a single set of <maml:para> tags for the description, even though multiple <maml:para> tags can be used.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
    <dev:code> command </dev:code>
    <dev:remarks>
      <maml:para> command description </maml:para>
    </dev:remarks>
</command:example>
</command:examples>

Dodawanie przykładowych danych wyjściowychAdding Example Output

Poniższy kod XML pokazuje, jak dodać dane wyjściowe polecenia.The following XML shows how to add the output of the command. Informacje o wynikach polecenia są opcjonalne, ale w niektórych przypadkach warto zademonstrować efekt użycia określonych parametrów.The command results information is optional, but in some cases it is helpful to demonstrate the effect of using specific parameters. Program PowerShell używa dwóch zestawów pustych <maml:para> tagów do oddzielenia danych wyjściowych polecenia z polecenia.PowerShell uses two sets of blank <maml:para> tags to separate the command output from the command.

<command:examples>
  <command:example>
    <maml:title>----------  EXAMPLE 1  ----------</maml:title>
    <maml:Introduction>
      <maml:paragraph>C:\PS></maml:paragraph>
    </maml:Introduction>
    <dev:code> command </dev:code>
    <dev:remarks>
      <maml:para> command description </maml:para>
      <maml:para></maml:para>
      <maml:para></maml:para>
      <maml:para> command output </maml:para>
</dev:remarks>
</command:example>
</command:examples>