powershell - 为什么我的别名不给我 get-help 或 -？

Question

这是PS5.1

我有一个名为“proc”的别名，它指向我使用以下命令设置的机器上的特定脚本

Set-Alias -Name proc     -Value "$sourceCodePath\deploy\Invoke-Process.ps1"           -Scope Global

如果我做

proc -?

或者

get-help proc

当我只想要帮助页面时，我得到了某种搜索输出，就像我不够具体一样

> proc -?

Name                              Category  Module                    Synopsis 
----                              --------  ------                    --------          
proc                              Alias                               Invoke-Process.ps1
Enter-PSHostProcess               Cmdlet    Microsoft.PowerShell.Core Connects to and enters into an interactive session with a local process.  
Exit-PSHostProcess                Cmdlet    Microsoft.PowerShell.Core Closes an interactive session with a local process.                       
Get-PSHostProcessInfo             Cmdlet    Microsoft.PowerShell.Core                                                                           
etc...

好的，这是 Get-Help 记录的行为，所以我尝试缩小范围

Get-Help -Category alias -Name proc -Full

这只是在没有任何实际帮助信息的情况下再次返回单个项目？

Name          : proc
Category      : Alias
Synopsis      : Invoke-Process.ps1
Component     :
Role          :
Functionality :

任何人都知道为什么会发生这种情况，如果我可以做些什么来让我的别名表现得像一个一流的 powershell 公民，而不必为此制作一个模块或任何更重量级的东西？

顺便说一句，这有效

& ((get-alias proc).ReferencedCommand.Source) -?

但每次我想提醒自己参数选项时，这是一个很大的上下文切换。

谢谢你的帮助!

Answer 1

基本上，这个输出的原因是 Get-Help正在返回有关 的帮助信息别名 不是引用的实际文件。
0 级 - TLDR
如果您只是想返回基本脚本信息，则需要在配置文件脚本中使用一个小函数来:

获取别名

解析源脚本文件位置

将该文件位置信息传递到 Get-Help

奖励:让它也成为别名!

例如。

Function Get-HelpAlias($alias){
    Get-Help((Get-Alias $alias).ResolvedCommand.Source)
} 

Set-Alias -Name gha -Value Get-HelpAlias

PS C:\> gha proc
Invoke-Process.ps1 [par1] [par2]

级别 1 - 脚本文件帮助
让我们分解发生了什么:
当你跑的时候:

Get-Help proc

实际上，您看到的是搜索结果，因为“proc”对于 Get-Help 来说不够独特。唯一标识您要查找的内容。通过指定类别:

Get-Help proc -Category Alias

你得到一个结果。如果您选择了一个更“独特”的别名，您可以看到这一点:

PS C:\> Set-Alias -Name zzzzzz -Value "$sourceCodePath\deploy\Invoke-Process.ps1" 
PS C:\> Get-Help zzzzzz

Name          : zzzzzz
Category      : Alias
Synopsis      : \deploy\Invoke-Process.ps1
Component     :
Role          :
Functionality :

至于它返回什么，它是返回关于别名的帮助信息。可以清楚的看到它的Category是一个Alias，返回的信息就是Alias中包含的值。你可以在这里看到:

PS C:\Temp> Get-Alias proc

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Alias           proc -> \deploy\Invoke-Process.ps1

我们可以通过获取别名、查看引用的脚本并将脚本引用字符串传递给 Get-Help 来“伪造”事物。 :

Get-Help((Get-Alias proc).ResolvedCommand.Source)

如果这就是您想要做的所有事情，那么您也可以在您的配置文件脚本中添加一个函数(当然还有一个别名；-)，它对您想要引用的任何脚本别名执行此操作，如下所示:

Function Get-HelpAlias($alias){
    Get-Help((Get-Alias $alias).ResolvedCommand.Source)
} 

Set-Alias -Name gha -Value Get-HelpAlias

PS C:\> gha proc
Invoke-Process.ps1 [par1] [par2]

这是 1 级 TLDR，如果您只是想要基本的脚本信息，它会起作用。
现在进入 2 级。

2 级 - 实际帮助
如果您希望帮助有用，您实际上必须编写它。在这些示例中，我们给出 Get-Help最困难的情况，没有帮助信息，它是最好的。对于别名，指向没有帮助信息的脚本，提供别名信息，因为这是最有用的。对于没有帮助信息的脚本文件，给出脚本文件信息。
如果我们真的写了帮助信息，我们会得到一个 非常不同的结果。好消息是使用 PowerShell 编写的帮助信息是 非常简单而且您不必成为“一流”的 PowerShell 公民就可以做到这一点。
创建帮助信息最简单的方法是写 Comment Based Help .例如。写 Comment Based Help for a Script在脚本的顶部只需添加如下内容:

<#
.SYNOPSIS
    Invoke-Process runs programs
.DESCRIPTION
    Connects to array of computers provided, and runs scripts.
#>


param (
    [string]$param1,
    [string]$param2
)
......

这是向脚本添加帮助的简单方法。然后你的输出(使用上面的函数)看起来像这样:

PS C:\> Get-Help .\Invoke-Process.ps1

NAME
    C:\Invoke-Process.ps1

SYNOPSIS
    Invoke-Process runs programs


SYNTAX
    C:\Invoke-Process.ps1 [[-param1] <String>] [[-param2] <String>] [<CommonParameters>]


DESCRIPTION
    Connects to array of computers provided, and runs scripts.


RELATED LINKS

REMARKS
    To see the examples, type: "get-help C:\Temp\asdf.ps1 -examples".
    For more information, type: "get-help C:\Temp\asdf.ps1 -detailed".
    For technical information, type: "get-help C:\Temp\asdf.ps1 -full".

第 3 级 - 让它按应有的方式工作
cmdlet 呢？他们会发生什么？例如，如果我们传递别名 gci 会发生什么至 Get-Help ?

PS C:\> Get-Help gci

NAME
    Get-ChildItem

SYNTAX
.... 

那是不同的。该别名返回的结果与上面发生的不同。它实际上按照我想要的方式工作。为什么我的不这样做？？？
这突出了函数和脚本之间的区别。在上面的示例中，我们试图获取有关脚本文件的信息。这是最低级别的帮助功能。 “普通”脚本不接受参数之类的东西，而且它们有一些非常无聊的信息，所以我们尽最大努力。这就是为什么在运行 Get-Help proc 时它返回搜索信息，因为搜索信息通常对您更有用。
功能和模块是不同的。他们是一等公民，因为我们拥有更多信息，而且实际上很重要。如果我们不想编写一个完整的模块(不比下面难多少)，我们可以将我们的脚本编写为一个函数。然后我们将它导入到 session 中(运行 . .\Invoke-Process.ps1 )以使函数可用，我们得到了惊人的帮助:
调用进程.ps1

<#
.SYNOPSIS
    Invoke-Process runs programs
.DESCRIPTION
    Connects to array of computers provided, and runs scripts.
.PARAMETER Servers
    The array of Servers
.PARAMETER Program
    Program to run
#>
Function Invoke-Process {
    Param (
        [string[]]$Server,
        [string]$Program
    )
    ....
}

PS C:\> . .\Invoke-Process.ps1
PS C:\> Set-Alias proc Invoke-Process
PS C:\> Get-Help proc

NAME
    Invoke-Process

SYNOPSIS
    Invoke-Process runs programs


SYNTAX
    Invoke-Process [[-Server] <String[]>] [[-Program] <String>] [<CommonParameters>]


DESCRIPTION
    Connects to array of computers provided, and runs scripts.


RELATED LINKS

REMARKS
    To see the examples, type: "get-help Invoke-Process -examples".
    For more information, type: "get-help Invoke-Process -detailed".
    For technical information, type: "get-help Invoke-Process -full".

只需添加更多信息即可轻松获得您想要/期望的帮助。