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

Question

我想将相同样式的脚本示例文档应用到我的脚本，这在本机文档中经常演示。例如，考虑 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 -------------------------- header？后者在文档标记中使用 .EXAMPLE 指令时呈现。

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

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

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

How do I format and name the examples in my PowerShell script documentation?

documentation

powershell

powershell-5.0