RFC: Deprecating Parameters

PowerShell Team

Request For Comment

One of our partners asked what the guidance was for a product that releases a cmdlet and then decides that they need to deprecate one or more of the parameters in a future release. We don’t currently have guidance on this topic so I thought I would tell you what we were thinking of saying and then you can comment about whether that is reasonable or not.

Background

The problem is that a bunch of scripts might have been written to use that parameter so if they just drop the parameter in the next release, it will break those scripts.

It’s easy to say, “never drop a parameter” but that isn’t realistic. Things change and teams need the flexibility to adapt.

Proposed Guidance

Avoid dropping parameters whenever possible since doing may break customer scripts.

If you must drop a parameter, do so over the course of a couple of releases. Depreciate it in the next release and then drop it in the release after that.

Deprecate the parameter by:

  1. Documenting this in your release notes.
  2. Add this information to the HELP content for this cmdlet. Put a note under the NOTES section and in the PARAMETER details section.
  3. Modify the implementation of the CMDLET to issue a message on the WARNING channel (WriteWarning()) when the deprecated parameter is used.

Validate that all the data binding scenarios (pipelining) scenarios continue to work property after dropping the parameters.

Note

One possibility is for PowerShell to provide explicit support for this scenario. We could create a DEPECREATED stream and have a DEPRECATED attribute that you could put on your parameters and then we could change the engine to look for this and issue a standardized error message. In the end, this would consume a lot of pm/dev/test calories for a scenario that I really hope doesn’t happens. I’d rather spend those calories on some amazing remoting capabilities so I’m strongly disinclined to go down that path.

What do you think?

Jeffrey Snover [MSFT]
Windows Management Partner Architect
Visit the Windows PowerShell Team blog at: http://blogs.msdn.com/PowerShell
Visit the Windows PowerShell ScriptCenter at: http://www.microsoft.com/technet/scriptcenter/hubs/msh.mspx

1 comment

Discussion is closed. Login to edit/delete existing comments.

Feedback usabilla icon