如何格式化和命名 PowerShell 脚本文档中的示例？答案

【问题标题】：How do I format and name the examples in my PowerShell script documentation?如何格式化和命名 PowerShell 脚本文档中的示例？
【发布时间】：2017-08-15 09:02:00
【问题描述】：

我想将脚本示例的相同文档样式应用于我的脚本，这在本机文档中经常演示。例如，考虑Invoke-Command 命令的帮助。

Get-Help Invoke-Command -Examples

此命令的输出包含以下内容：

Example 3: Run a command in a persistent connection

PS C:\>$s = New-PSSession -ComputerName Server02 -Credential Domain01\User01
PS C:\> Invoke-Command -Session $s -ScriptBlock {Get-Culture}

如何命名我的示例，以使它们如上所示，而不是默认的 -------------------------- EXAMPLE 3 -------------------------- 标头？后者是在文档标签中使用.EXAMPLE 指令时呈现的。

此外，我如何利用多行示例使它们包含 shell 路径前缀 (PS C:\?)。我可以在我的文档中手动输入此前缀来创建效果，但我想知道是否有不同且更合规的方法。

【问题讨论】：

标签： powershell documentation powershell-5.0

【解决方案1】：

执行此操作的方法是使用外部帮助 MAML XML 文件。可以手动创建，也可以使用 PlatyPS 模块从 markdown 创建 MAML。您还可以使用 PlatyPS 从基于评论的帮助 (CBH) 创建降价。

使用 PlatyPS：

# Create markdown from CBH in a module
New-MarkdownHelp -Module MyModule -OutputFolder .\docs -Locale en-US

# Create MAML external help, usually in a build step
New-ExternalHelp -Path .\docs -OutputPath .\moduleOutFolder\en-US

# Then you can optionally replace the CBH with a link to the external help
# file so you only need to adjust the markdown

<#
.EXTERNALHELP MyModuleName-help.xml
#>

在创建初始降价时，您可能必须手动调整多行示例的降价。由于这个原因和其他一些偏好差异，我通常只维护降价并替换 CBH。

【讨论】：