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

Question

我想将脚本示例的相同文档样式应用于我的脚本，这在 native 文档中经常演示。例如，考虑 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:\? )。我可以在我的文档中手动输入此前缀来创建效果，但我想知道是否有不同且更合规的方法。

Answer 1

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

使用 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
#>

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