This time around, I thought I’d show how to work with programmatically generated dynamic parameters, as opposed to the statically defined sets we saw the last time. The context here is a fairly silly Cmdlet, but it’s good enough to demonstrate the concept end to end. It’s a Cmdlet for removing a file. It takes one string parameter which is the path to the file. The dynamic parameter I’m going to add is a –Force parameter. The trick is, this parameter will only be added if the current user is an administrator (XP), or is elevated as one (Vista).
This first portion of the Cmdlet defines the usual stuff like a verb and noun. This time though, I’m using a regular class constructor. It’s not often you see constructors in simple Cmdlets because typically all one would usually do is override one or more of the three processing methods BeginProcessing, ProcessRecord and EndProcessing. In this case, I need to create a instance of a “RuntimeDefinedParameterDictionary,” which does exactly what it says on the tin. It’s a dictionary of parameters, the key being a string (the name of the parameter) and the value being a instance of a RuntimeDefinedParameter class. These classes are all members of the System.Management.Automation namespace.
In the constructor, I’m calling a generic method defined as AddDynamicParameter<T>(string name). This is only called if the current user is an admin. I’ve defined three generic helper methods which you can see a little further down below.
- [Cmdlet(VerbsCommon.Remove, NOUN_FILE)]
- public class RemoveFileCommand : PSCmdlet, IDynamicParameters
- {
- private const string NOUN_FILE = "File";
- private const string SWITCH_FORCE = "Force";
-
- private readonly RuntimeDefinedParameterDictionary _parameters;
-
- public RemoveFileCommand()
- {
- _parameters = new RuntimeDefinedParameterDictionary();
-
-
-
- var principal = new WindowsPrincipal(WindowsIdentity.GetCurrent());
-
-
-
- if (principal.IsInRole(WindowsBuiltInRole.Administrator))
- {
- this.AddDynamicParameter<SwitchParameter>(SWITCH_FORCE);
- }
- }
-
- [Parameter]
- public string FilePath
- {
- get;
- set;
- }
-
- protected override void EndProcessing()
- {
-
- if (File.Exists(FilePath))
- {
- RemoveFile();
- }
- else
- {
- WriteWarning(FilePath + " does not exist.");
- }
- }
This is a simple piece of code who’s role is to remove the file specified by the user. I’ve omitted the actual code that would delete the file for brevity. I’m using another helper method to see if the –Force parameter has been added to the Cmdlet’s definition, and if so, was it specified by the invoker of the Cmdlet. The idea is here is that the Cmdlet will not remove the file if it’s marked Read-Only, but if –Force is specified it will remove the R/O attribute and continue as planned.
- private void RemoveFile()
- {
-
- var attribs = File.GetAttributes(FilePath);
-
-
- if ((attribs & FileAttributes.ReadOnly) == FileAttributes.ReadOnly)
- {
- bool shouldForce;
-
-
- if (TryGetSwitchParameter(SWITCH_FORCE, out shouldForce))
- {
- WriteVerbose("Force.IsPresent: " + shouldForce);
- }
-
- if (shouldForce)
- {
- RemoveReadOnlyAttribute();
- }
- else
- {
- WriteWarning(FilePath + " is marked Read-Only!");
- return;
- }
- }
-
-
- }
And the final piece is here. The first method GetDynamicParameters, belongs to the IDynamicParameters interface and tells PowerShell that the Cmdlet may return extra parameters not defined on the class itself. In this case, we are returning a RuntimeDefinedParameterDictionary instead of a statically defined parameters on a nested class.
- public object GetDynamicParameters()
- {
- return _parameters;
- }
-
-
- private void AddDynamicParameter<T>(string name)
- {
-
- var parameter = new RuntimeDefinedParameter
- {
- Name = name,
- ParameterType = typeof (T),
- };
-
-
- var attrib = new ParameterAttribute
- {
- ParameterSetName =
- ParameterAttribute.AllParameterSets
- };
-
- parameter.Attributes.Add(attrib);
-
- _parameters.Add(name, parameter);
- }
-
- private bool TryGetSwitchParameter(string name, out bool isPresent)
- {
- RuntimeDefinedParameter parameter;
-
- if (TryGetDynamicParameter(name, out parameter))
- {
- isPresent = parameter.IsSet;
- return true;
- }
-
- isPresent = false;
- return false;
- }
-
-
- private bool TryGetParameter<T>(string name, out T value)
- {
- RuntimeDefinedParameter parameter;
-
- if (TryGetDynamicParameter(name, out parameter))
- {
- value = (T)parameter.Value;
- return true;
- }
-
- value = default(T);
-
- return false;
- }
-
-
- private bool TryGetDynamicParameter(string name, out RuntimeDefinedParameter value)
- {
- if (_parameters.ContainsKey(name))
- {
- value = _parameters[name];
- return true;
- }
-
-
- value = null;
-
- return false;
- }
Finally, the three helper methods are revealed. One is used for checking for dynamic SwitchParameters, the next is for ordinary parameters that return type T, the generic argument. The third method, TryGetDynamicParameter is used by the first two methods.
I hope this helps reveal some of the mystery behind dynamic parameters on Cmdlets. There is one more type of dynamic parameter that I will be examining in one of my next few posts, that is the scenario where a provider (like the FileSystemProvider or RegistryProvider) passes a dynamic parameter to a Cmdlet. In this particular case, the provider can only pass dynamic parameters to the built-in Cmdlets that operate on providers, e.g. Get-ChildItem, Get-Item, Get-ItemProperty etc.
Have fun!