MSDN Magazine - December 2007 - (Page 69) a Windows PowerShell cmdlet and commands in other standalone shell environments. For instance, a cmdlet is an instance of a Microsoft® .NET Framework class; it is not a standalone executable. Cmdlets generally output objects rather than text and should not format their output. A cmdlet processes its input objects from an object pipeline rather than from a stream of text. A cmdlet should not parse its own arguments and it should not specify a presentation for errors. Finally, cmdlets are record-oriented and generally process a single object at a time. Cmdlets have a specific structure; they must be attributed in a particular way and they must be derived from a specific base class. If a particular cmdlet supports parameters, those parameters must also be attributed in a specific way, and the cmdlet must provide implementations of some specific methods. If you’re wondering what all this means, don’t worry. I’ll explain each of these requirements in more detail. file. Thus, I will create three cmdlets: Set-IsolatedStorageData, GetIsolatedStorageData, and Remove-IsolatedStorageFile. Cmdlet Class Definition Now I need to create the code that will implement my cmdlets, starting with my Set-IsolatedStorageData cmdlet. First I declare the cmdlet class: [Cmdlet(VerbsCommon.Set , “IsolatedStorage”, SupportsShouldProcess=true)] public class SetIsolatedStorageCommand : PSCmdlet Cmdlet Attribute To declare a .NET class as a cmdlet, you attribute the class with the CmdletAttribute attribute (which is the only required attribute for any cmdlet). When you specify the CmdletAttribute attribute, you must specify a verb and noun name pair, which will be used as the name of the cmdlet. This should describe what the cmdlet does and what sort of resource the cmdlet works with. Note that the CmdletAttribute attribute itself is a .NET class. The properties of the class correspond to the parameters available when using the cmdlet. The noun portion of the cmdlet name allows you to differentiate your custom cmdlet from other cmdlets. The noun part specifies the resources upon which the cmdlet acts. Ideally, the noun used in cmdlet naming should be very specific; if you’ve got a generic term, you should use that term as a suffix to your cmdlet. For example, if you create a get-server cmdlet for your SQL database, you should use “New-SQLDatabase” rather than “New-Database”. The combination of specific noun and verb names makes it easy for the user to discover cmdlets quickly and anticipate functionality. Remember that these should be words that people will recognize, so you shouldn’t use reserved punctuation (slashes, brackets, and so on) or wildcard characters in your cmdlet names. Since I am creating cmdlets that work with Windows® IsolatedStorage, I’ll use that as the basis for my noun. It may be a bit long, but with cmdlet names, the more specific, the better. There are some pretty strong guidelines regarding what verbs should be used for verb names. Remember that consistency is important in Windows PowerShell, so be sure you use the appropriate verbs. By using one of the predefined verb names, you will improve consistency between your custom cmdlets, the included cmdlets, and cmdlets created by other users. For example, to retrieve data you use Get, rather than Retrieve or Acquire. Common verbs used in Windows PowerShell include: Add, Clear, Copy, Get, Join, Lock, Move, New, Remove, Rename, Select, Set, Split, and Unlock.You can tell what each is used for just from its name. In this article I’ll create three cmdlets: one to set the data contents of the IsolatedStorage, one to retrieve the contents, and one to remove the IsolatedStorage Notice that I’m using Pascal casing and that the name of the class includes the verb and noun name for the cmdlet. Strictly speaking, this isn’t necessary, but it makes my code much more readable. The cmdlet attribution indicates that I’m using a common verb, in this case Set. If possible, you should always use common verbs when creating cmdlets. Setting SupportsShouldProcess to True indicates that the cmdlet supports calls to The combination of specific the ShouldProcess method, noun and verb names which provides the cmdlet the opportunity to prompt makes it easy for the user to the user for verification bediscover cmdlets quickly and fore an action that changes anticipate functionality. the system is performed. If this attribute isn’t present or is set to False (which is the default value), it would indicate that the cmdlet does not support calls to the ShouldProcess method. All cmdlets that change resources outside of Windows PowerShell should set the SupportsShouldProcess property to true when declaring the CmdletAttribute attribute. This allows the cmdlet to call the ShouldProcess method before performing its action. If the ShouldProcess call returns false, the action will not be taken. (For more information about the confirmation requests generated by ShouldProcess call, see the MSDN® documentation at msdn2.microsoft.com/ bb204629.) The Confirm and WhatIf cmdlet parameters are available only for cmdlets that support ShouldProcess calls. The last bit declares the class and uses PSCmdlet as the base class, which means that I’ll get all the extended behaviors associated with a Windows PowerShell cmdlet. Windows PowerShell supports cmdlets that are derived from two different base classes: PSCmdlet and Cmdlet. A cmdlet derived from PSCmdlet gives you access to the Windows PowerShell runtime. This enables calls to other scripts, and allows access to the Windows PowerShell providers for working with session state. PSCmdlet also provides access to the Windows PowerShell logging features, though this comes at the price of being a bit bigger and leaves you dependent upon the Windows PowerShell runtime. Cmdlets derived from the Cmdlet class offer only the fewest dependencies on the Windows PowerShell runtime. This has some benefits—these cmdlets are a bit smaller since they have less functionality, and you’re less likely to encounter problems due to changes in Windows PowerShell over time. In addition, these cmdlets can be easily included in other applications without the Windows PowerShell runtime. december2007 69 http://msdn2.microsoft.com/bb204629 http://msdn2.microsoft.com/bb204629
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.