Powershell 无法正确呈现我的脚本帮助

Question

我有一个 Powershell 脚本，在它的开头有一个很大的帮助，可以使用 Get-Help 命令显示 - https://gist.github.com/MarkKharitonov/91698caf8c695902eacde2b6c7825bf1

我对帮助的呈现方式有两个问题。特别是 .EXAMPLE 部分。以下是帮助的缩写版本(请参阅超链接以获取完整版本的脚本和帮助):

<#
.SYNOPSIS
    Runs a WinDBG command or a script file.

...

.NOTES
    The default is to scan for images using the .imgscan /l. One has to check first with the WinDBG GUI to see if this is necessary, because this is a time consuming operation.

.EXAMPLE
    Please, find below a PowerShell session transcript showing the script invoked with the -Command parameter:

    PS D:\tmp\cantestr52 - 06-09-2017> cat C:\Users\mkharitonov\runcdb.config.ps1
    $Sosex = "E:\Utils\sosex\64\sosex.dll"
    $CDB = "e:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe"
    $SymbolsCache = "E:\Symbols"
    PS D:\tmp\cantestr52 - 06-09-2017> cat .\runcdb.config.ps1
    $dump = "d:\tmp\cantestr52 - 06-09-2017\Quartz.Server.DMP"
    $ImagePath = "d:\tmp\cantestr52 - 06-09-2017\BJE"
    $NoScanForImages = $false
    PS D:\tmp\cantestr52 - 06-09-2017> runcdb.ps1 -Command "!dumpheap -mt 00007fff11d90f78 -live"
    ...        
    PS D:\tmp\cantestr52 - 06-09-2017>

    The script produced two log files:
    c:\Users\MKHARI~1\AppData\Local\Temp\!dumpheap_-mt_00007fff11d90f78_-live.log.init 
    c:\Users\MKHARI~1\AppData\Local\Temp\!dumpheap_-mt_00007fff11d90f78_-live.log

    Here is the WinDBG code executed by the script:
    | .logopen "c:\Users\MKHARI~1\AppData\Local\Temp\!dumpheap_-mt_00007fff11d90f78_-live.log.init"
    | .imgscan /l
    | .load E:\Utils\sosex\64\sosex.dll
    | !lhi
    | .logclose
    | .logopen "c:\Users\MKHARI~1\AppData\Local\Temp\!dumpheap_-mt_00007fff11d90f78_-live.log"
    | !dumpheap -mt 00007fff11d90f78 -live
    | .logclose
    | q
#>

问题1

请注意，最后几行以 | 开头。这是因为 .logopen - PowerShell 尝试将其视为帮助部分关键字，例如 .NOTES 或 .EXAMPLE。当然，没有这样的关键字，因此 PowerShell 只是截断帮助输出并停止显示最后几行。我必须想办法逃离这个点，但找不到路。

问题2

请注意:

注意输出中的C:\PS>。当然，这不属于我的帮助范围。

那么，有两个问题 - 如何转义帮助行中的第一个点以及上面帮助输出中的 C:\PS> 的来源是什么？

Answer 1

问题 1 -(以点 . 开头的行)

我认为基于评论的帮助无法解决这个问题，但是如果您使用XML based help那么我认为这不会是一个问题。不过，这是一个很大的变化。

问题 2 -(提示字符串)

似乎所有示例都这样做，并且不太可能通过 XML 帮助来避免。无论如何，我也不喜欢这种行为。

但是，我要说的是，我认为您的示例没有正确遵循示例的格式。在提示面前看起来很尴尬的解释不应该出现在示例部分中。

在 .EXAMPLE 之后，您应该只放置代码行(可以在代码后面添加简短的解释)。

更多解释可以在 .NOTES 或链接文档中给出。