Cmdlet Attribute Declaration

The Cmdlet attribute identifies a Microsoft .NET Framework class as a cmdlet and specifies the verb and noun used to invoke the cmdlet.

[Cmdlet("verbName", "nounName"]
[Cmdlet("verbName", "nounName", Named Parameters...)]

Parameters

VerbName (String)
Required. Specifies the cmdlet verb. This verb specifies the action taken by the cmdlet. For more information about approved cmdlet verbs, see Approved Verbs for Windows PowerShell Commands and Required Development Guidelines.

NounName (String)
Required. Specifies the cmdlet noun. This noun specifies the resource that the cmdlet acts upon. For more information about about cmdlet nouns, see Cmdlet Declaration and Strongly Encouraged Development Guidelines.

SupportsShouldProcess (Boolean)
Optional named parameter. True indicates that the cmdlet supports calls to the ShouldProcess method, which provides the cmdlet with a way to prompt the user before an action that changes the system is performed. False, the default value, indicates that the cmdlet does not support calls to the ShouldProcess method. For more information about confirmation requests, see Requesting Confirmation from Cmdlets.

ConfirmImpact (ConfirmImpact)
Optional named parameter. Specifies when the action of the cmdlet should be confirmed by a call to the ShouldProcess method. ShouldProcess will only be called when the ConfirmImpact value of the cmdlet (by default, Medium) is equal to or greater than the value of the $ConfirmPreference variable. This parameter should be specified only when the SupportsShouldProcess parameter is specified.

DefaultParameterSetName (String)
Optional named parameter. Specifies the default parameter set that the Windows PowerShell runtime attempts to use when it cannot determine which parameter set to use. Notice that this situation can be eliminated by making the unique parameter of each parameter set a mandatory parameter.

There is one case where Windows PowerShell cannot use the default parameter set even if a default parameter set name is specified. The Windows PowerShell runtime cannot distinguish between parameter sets based solely on object type. For example, if you have one parameter set that takes a takes a string as the file path, and another set that takes a FileInfo object directly, Windows PowerShell cannot determine which parameter set to use based on the values passed to the cmdlet, nor does it use the default parameter set. In this case, even if you specify a default parameter set name, Windows PowerShell throws an ambiguous parameter set error message.

SupportsTransactions (Boolean)
Optional named parameter. True indicates that the cmdlet can be used within a transaction. When True is specified, the Windows PowerShell runtime adds the UseTransaction parameter to the parameter list of the cmdlet. False, the default value, indicates that the cmdlet cannot be used within a transaction.

  • Together, the verb and noun are used to identify your registered cmdlet and to invoke your cmdlet within a script.

  • When the cmdlet is invoked from the Windows PowerShell console, the command resembles the following command:

    VerbName-NounName

  • All cmdlets that change resources outside of Windows PowerShell should include the SupportsShouldProcess keyword when the Cmdlet attribute is declared, which allows the cmdlet to call the ShouldProcess method before the cmdlet performs its action. If the ShouldProcess call returns false, the action should not be taken. For more information about the confirmation requests generated by the ShouldProcess call, see Requesting Confirmation from Cmdlets.

    The Confirm and WhatIf cmdlet parameters are available only for cmdlets that support ShouldProcess calls.

The following class definition uses the Cmdlet attribute to identify the .NET Framework class for a Get-Proc cmdlet that retrieves information about the processes running on the local computer.

[Cmdlet(VerbsCommon.Get, "Proc")]
public class GetProcCommand : Cmdlet   

For more information about the Get-Proc cmdlet, see GetProc Tutorial.



Community Additions

ADD
Show:
© 2014 Microsoft