PowerShell 5.1模块别名描述缺失及旧版别名提示方案问询

问题背景 #

我们组织的PhriInfrastructure模块中，Test-IsLocalhost函数为了向后兼容设置了别名Get-IsLocalhost。使用New-Alias添加描述后，导入模块执行Get-Alias和Get-Help时，描述字段均为空；直接在命令行创建别名时，Get-Alias能看到描述但Get-Help依然不显示。

核心原因 #

PowerShell 5.1中模块导出的别名存在描述属性无法持久化到全局作用域的已知行为，不算严格意义上的bug，但属于设计局限。同时Get-Help对别名的自定义描述支持有限，默认会直接展示原命令的帮助内容。

解决方案 #

一、让别名描述在Get-Alias中显示 #

不要仅依赖模块内的New-Alias创建别名，而是在模块加载后显式为全局作用域的别名设置描述：

# 在模块脚本（.psm1）中执行
# 创建别名
New-Alias -Name Get-IsLocalhost -Value Test-IsLocalhost
# 导出别名与原函数
Export-ModuleMember -Function Test-IsLocalhost -Alias Get-IsLocalhost
# 显式设置全局作用域别名的描述
(Get-Alias -Name Get-IsLocalhost -Scope Global).Description = "Get-IsLocalhost已重命名为Test-IsLocalhost，以符合PowerShell动词规范"

二、让用户感知别名已弃用的更优方式 #

比起单纯设置别名描述，以下方法能更直接地提示用户使用主命令：

1. 创建包装函数替代别名
   当用户调用别名时弹出警告，同时执行原函数逻辑，直观提示弃用：

function Get-IsLocalhost {
    [CmdletBinding()]
    param(
        # 与Test-IsLocalhost一致的参数定义
        [Parameter(ValueFromPipeline = $true)]
        [string[]]$ComputerName
    )
    Write-Warning "⚠️ Get-IsLocalhost已弃用，请使用Test-IsLocalhost代替"
    # 传递所有参数到原函数
    Test-IsLocalhost @PSBoundParameters
}
# 导出包装函数（替代原别名导出）
Export-ModuleMember -Function Test-IsLocalhost, Get-IsLocalhost

这种方式可以逐步过渡：先警告，后续可改为抛出错误强制用户切换。

2. 在原函数帮助中注明别名信息
   在Test-IsLocalhost的注释帮助中添加.NOTES部分，让用户查询原命令帮助时了解别名情况：

function Test-IsLocalhost {
    <#
    .SYNOPSIS
    检测指定计算机是否为本地主机
    .DESCRIPTION
    判断输入的计算机名是否指向本地机器
    .NOTES
    曾用别名：Get-IsLocalhost，现已弃用，请直接使用Test-IsLocalhost
    #>
    # 函数逻辑实现
}

三、PowerShell版本差异说明 #

PowerShell 7+版本已修复此问题：模块导出的别名描述可以正确显示在Get-Alias结果中，Get-Help也能更好地处理别名的自定义帮助内容。如果条件允许，升级到PowerShell 7+是更彻底的解决办法。

内容的提问来源于stack exchange，提问作者Pxtl