How to add examples to a cmdlet help topic
Note
Manual authoring of XML-based help is very difficult. The PlatyPS module allows you to write help in Markdown and then convert it to XML-based help. This makes it much easier to write and maintain help. PlatyPS can also create the Updateable Help packages for you. For more information, see Create XML-based help using PlatyPS.
Things to know about examples in cmdlet help
List all of the parameter names in the command, even when the parameter names are optional. This helps the user to interpret the command easily.
Avoid aliases and partial parameter names, even though they work in PowerShell.
In the example description, explain the rational for the construction of the command. Explain why you chose particular parameters and values, and how you use variables.
If the command uses expressions, explain them in detail.
If the command uses properties and methods of objects, especially properties that don't appear in the default display, use the example as an opportunity tell the user about the object.
Help Views that Display Examples
Examples appear only in the Detailed and Full views of cmdlet Help.
Adding an examples node
The following XML shows how to add an Examples node that contains a single Example node. Add additional example nodes for each examples you want to include in the topic.
<command:examples>
<command:example>
</command:example>
</command:examples>
Adding an example title
The following XML shows how to add a title for the example. The title is used to set the example apart from other examples. 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>
Adding preceding characters
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). PowerShell uses
the Windows PowerShell prompt: C:\PS>
.
<command:examples>
<command:example>
<maml:title>---------- EXAMPLE 1 ----------</maml:title>
<maml:introduction>
<maml:para>C:\PS></maml:para>
</maml:introduction>
</command:example>
</command:examples>
Adding the command
The following XML shows how to add the actual command of the example. When adding the command, type the entire name (do not use alias) of cmdlets and parameters. Also, use lowercase characters whenever possible.
<command:examples>
<command:example>
<maml:title>---------- EXAMPLE 1 ----------</maml:title>
<maml:introduction>
<maml:para>C:\PS></maml:para>
</maml:introduction>
<dev:code> command </dev:code>
</command:example>
</command:examples>
Adding a Description
The following XML shows how to add a description for the example. 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:para>C:\PS></maml:para>
</maml:introduction>
<dev:code> command </dev:code>
<dev:remarks>
<maml:para> command description </maml:para>
</dev:remarks>
</command:example>
</command:examples>
Adding example output
The following XML shows how to add the output of the command. The command results information is
optional, but in some cases it's helpful to demonstrate the effect of using specific parameters.
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:para>C:\PS></maml:para>
</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>
PowerShell
피드백
https://aka.ms/ContentUserFeedback
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요.다음에 대한 사용자 의견 제출 및 보기