如何隐藏PowerShell弃用参数集？兼容旧脚本并优化Get-Help输出

针对你需要保留旧参数集兼容现有脚本，但又不想让它在Get-Help中出现或明确标记为弃用的需求，我分两种场景给你具体方案：

优先方案：升级到PowerShell 5.1及以上（推荐） #

PowerShell 5.1提供了更完善的参数弃用控制属性，能同时满足隐藏智能提示、标记弃用、控制Get-Help显示的需求。

实现代码示例 #

function Get-FooBar {
    [CmdletBinding(DefaultParameterSetName='NewSet')]
    param (
        # 公共参数，两个参数集都需要
        [Parameter(Mandatory=$true, ParameterSetName='NewSet')]
        [Parameter(Mandatory=$true, ParameterSetName='OldSet')]
        [string]$SomeCommonParameter,

        # 新参数集（推荐使用）
        [Parameter(Mandatory=$true, ParameterSetName='NewSet')]
        [NewResourceType]$NewParameter,

        # 旧参数集（已弃用）
        [Parameter(Mandatory=$true, ParameterSetName='OldSet')]
        [Obsolete("此参数已弃用，请使用 -NewParameter 替代")]
        [DontShow()]
        [OldResourceType]$OldParameter
    )

    <#
    .SYNOPSIS
    获取FooBar资源

    .DESCRIPTION
    可通过新参数集（推荐）或兼容旧参数集获取FooBar资源，旧参数集仅用于兼容现有脚本

    .PARAMETER SomeCommonParameter
    两个参数集通用的必填参数

    .PARAMETER NewParameter
    推荐使用的新参数，用于指定资源类型

    .PARAMETER OldParameter
    **已弃用** 仅为兼容现有脚本保留，请使用 -NewParameter 替代
    #>

    # 根据参数集执行对应逻辑
    switch ($PSCmdlet.ParameterSetName) {
        'NewSet' {
            # 新参数集处理逻辑
            Write-Verbose "使用新参数集处理请求"
        }
        'OldSet' {
            # 旧参数集处理逻辑（可映射到新逻辑以减少冗余）
            Write-Verbose "使用已弃用的旧参数集处理请求"
        }
    }
}

方案效果 #

1. 智能提示隐藏：[DontShow()]属性会让旧参数在制表符补全时不显示，避免用户误选
2. 弃用警告：用户使用旧参数时，PowerShell会自动弹出Obsolete属性中定义的警告信息
3. Help文档标记：在.PARAMETER OldParameter中明确标注已弃用，用户查看Get-Help Get-FooBar时能清晰看到提示；如果希望旧参数集完全不显示在Get-Help的SYNTAX部分，可以手动在注释块的.SYNTAX节点只定义新参数集：

   <#
   ...
   .SYNTAX
   Get-FooBar -SomeCommonParameter <string> -NewParameter <NewResourceType>
   ...
   #>
   

兼容PowerShell 3.0的方案 #

如果暂时无法升级版本，只能通过文档标记+运行时警告的方式实现需求：

实现代码示例 #

function Get-FooBar {
    [CmdletBinding(DefaultParameterSetName='NewSet')]
    param (
        [Parameter(Mandatory=$true, ParameterSetName='NewSet')]
        [Parameter(Mandatory=$true, ParameterSetName='OldSet')]
        [string]$SomeCommonParameter,

        [Parameter(Mandatory=$true, ParameterSetName='NewSet')]
        [NewResourceType]$NewParameter,

        [Parameter(Mandatory=$true, ParameterSetName='OldSet')]
        [OldResourceType]$OldParameter
    )

    <#
    .SYNOPSIS
    获取FooBar资源

    .DESCRIPTION
    可通过新参数集（推荐）或兼容旧参数集获取FooBar资源，旧参数集仅用于兼容现有脚本

    .PARAMETER SomeCommonParameter
    两个参数集通用的必填参数

    .PARAMETER NewParameter
    推荐使用的新参数，用于指定资源类型

    .PARAMETER OldParameter
    **已弃用** 仅为兼容现有脚本保留，请使用 -NewParameter 替代
    #>

    # 检测到旧参数集时主动抛出警告
    if ($PSCmdlet.ParameterSetName -eq 'OldSet') {
        Write-Warning "警告：-OldParameter参数集已弃用，请尽快切换到-NewParameter参数集"
    }

    # 后续处理逻辑
}

方案效果 #

• 旧参数集仍会出现在Get-Help的SYNTAX部分，但参数描述中明确标记为弃用
• 用户使用旧参数时会收到主动弹出的警告，提示他们切换到新参数集

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