2

Say you have and old, deprecated parameter set, and a new parameter set:

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

    Get-FooBar -SomeCommonParameter <string> -OldParameter <OldResourceType>

I want both parameter sets to continue working, to preserve compatibility with existing scripts, but I do not want the old deprecated parameter set to appear in the Get-Help output. Or, at the very least, clearly marked as deprecated within the SYNTAX section of Get-Help.

The DontShow property of the parameter attribute in PowerShell 4.0 helps a bit, as then IntelliSense/tab completion won't use it, but the parameter set still appears in the Get-Help output.

We are currently using PowerShell 3.0, but I don't think updating the version of PowerShell we target would be a blocker.

Mark Raymond
  • 906
  • 8
  • 22
  • 3
    I don't think you can hide parameter sets. I'd put a deprecation notice in the `.NOTES` section. – Ansgar Wiechers Jan 05 '18 at 12:29
  • 1
    You could also add something like `if ($PSCmdlet.ParameterSetName -eq $DeprecatedParameterSetName) { Write-Warning "The $DeprecatedParameterSetName parameter set has been deprecated and will be removed in a future release. Please update your scripts." }`. – Bacon Bits Jan 05 '18 at 14:24

1 Answers1

3

Are you changing names, or is the functionality different as well? If you're just changing names, make the new name the name of the parameter and alias the old names.

If you're changing functionality as well, the dbatools module does the following:

  • Indicate in the comment-based help that the parameter is deprecated (before describing the parameter)
  • Tests for deprecated parameter names with an internal function, and provides the user with a warning message if they've used one.

Example: Get-DbaDiskSpace calls Test-DbaDeprecation from its begin block. Test-DbaDeprecation parses the function call to find usage of the passed-in (deprecated) parameter name.

alroc
  • 27,574
  • 6
  • 51
  • 97