MSDN Magazine - December 2007 - (Page 70) Figure 1 Parameters Needed to Gather Key and Value private string _key = null; [Parameter( Mandatory=true, Position=1, ValueFromPipelineByPropertyName=true )] public string Key { get { return _key; } set { _key = value; } } private string _value = null; /// the value to store [Parameter( Mandatory=true, Position=2, ValueFromPipelineByPropertyName=true )] public string Value { get { return _value; } set { _value = value; } } designates the actual name of the IsolatedStorage file. So here is the parameter declaration—a Name parameter: private string _name = “PowerShellIsolatedStore”; /// name of store [Parameter] public string Name { get { return _name; } set { _name = value; } } When you create a parameter, you should choose whether it is positional or named. With a positional parameter you don’t need to provide the parameter name—just the value: PS> cd c:\windows If your plan is to create a cmdlet that will always be part of the Windows PowerShell environment, you should use PSCmdlet as your base class. However, if you think that your code will be used in more than just Windows PowerShell, you should use Cmdlet as a base class. For my examples, I am deriving from PSCmdlet. When you are creating your cmdlet, you will need to reference SysThe Windows PowerShell tem.Management.AutomaSDK has detailed tion.dll, which can be tricky suggestions on parameter to find since it’s only in the names and how you should Global Assembly Cache (GAC), but I’ve got a trick use them in your cmdlet to to help with that, which I’ll help ensure consistency. share in just a moment. By setting Position=num as part of the attribute, you designate what position is used for that parameter. If a parameter is not positional, you leave off the Position attribute and use the parameter name from the command line to provide a value. The documentation recommends that you make frequently used parameters positional whenever possible. The only problem with this guidance is that if you have many parameters, it can be a bit much to remember. Of course, even when a parameter is positional, the parameter name can still be used from the command line. Cmdlet parameters can be defined as mandatory, meaning that they must have a value assigned before the Windows PowerShell runtime will invoke the cmdlet. Alternatively, they can be defined as optional. By default, all parameters are defined as optional. To define an optional parameter, then, simply omit the Mandatory property in the attribute declaration. Since I’ll be storing a key and a value in the isolated storage, I need to create parameters so I can gather those values (see Figure 1). Cmdlet parameters can also have aliases. To tell Windows PowerShell that a parameter has an alias, you add an AliasAttribute attribute to the property definition. The basic syntax for declaring the attribute is [Alias(“alias”)]. In my example, I create an alias called Filename that applies to the Name parameter, like so: private string _name = “PowerShellIsolatedStore”; /// name of store [Alias(“Filename”)] [Parameter] public string Name { get { return _name; } set { _name = value; } } Parameter Definition Next I need to consider the parameters for my cmdlet. Parameters allow the user to provide input to the cmdlet. Cmdlet parameter names should be consistent across the cmdlet design. The Windows PowerShell SDK has detailed suggestions on parameter names and how you should use them in your cmdlet to help ensure consistency with other cmdlets you may come across. To declare parameters for a cmdlet, you must first define the properties that represent the parameters. To inform the Windows PowerShell runtime that a property is a cmdlet parameter, you add a ParameterAttribute attribute to the property definition. Parameters must be explicitly marked as public; ones that are not marked as public default to internal and are not found by the Windows PowerShell runtime. This can lead to some confusion when you’re trying to figure out why your cmdlet doesn’t have the parameters you think it should have. In my sample, I know that all my cmdlets will need a name that 70 msdnmagazine Custom Cmdlets Common Parameters Windows PowerShell reserves a few parameter names, referred to as Common parameters, which you can’t use: WhatIf, Confirm, Verbose, Debug, ErrorAction, ErrorVariable, OutVariable, and OutBuffer. In addition, the following aliases for these parameter names are reserved: vb, db, ea, ev, ov, and ob. ShouldProcess Parameters Another group of parameters, the ShouldProcess parameters, are present only when the cmdlet specifies the SupportsShouldProcess keyword in its CmdletAttribute attribute. When your cmdlet supports ShouldProcess, you have access
For optimal viewing of this digital publication, please enable JavaScript and then refresh the page. If you would like to try to load the digital publication without using Flash Player detection, please click here.