You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Because Windows PowerShell works directly with Microsoft .NET Framework objects, a .NET Framework
20
20
object is often available that exactly matches the type the user needs to perform a particular
21
21
operation. `InputObject` is the standard name for a parameter that takes such an object as input.
22
-
For example, the sample `Stop-Proc` cmdlet in the [StopProc Tutorial](./stopproc-tutorial.md)
23
-
defines an `InputObject`parameter of type Process that supports the input from the pipeline. The
24
-
user can get a set of process objects, manipulate them to select the exact objects to stop, and then
25
-
pass them to the `Stop-Proc` cmdlet directly.
22
+
For example, the sample `Stop-Proc` cmdlet in the [StopProc Tutorial][03] defines an `InputObject`
23
+
parameter of type Process that supports the input from the pipeline. The user can get a set of
24
+
process objects, manipulate them to select the exact objects to stop, and then pass them to the
25
+
`Stop-Proc` cmdlet directly.
26
26
27
27
### Support the Force Parameter (AD02)
28
28
29
29
Occasionally, a cmdlet needs to protect the user from performing a requested operation. Such a
30
30
cmdlet should support a **Force** parameter to allow the user to override that protection if the
31
31
user has permissions to perform the operation.
32
32
33
-
For example, the [Remove-Item](/powershell/module/microsoft.powershell.management/remove-item)
34
-
cmdlet does not normally remove a read-only file. However, this cmdlet supports a **Force**
35
-
parameter so a user can force removal of a read-only file. If the user already has permission to
36
-
modify the read-only attribute, and the user removes the file, use of the **Force** parameter
37
-
simplifies the operation. However, if the user does not have permission to remove the file, the
38
-
**Force** parameter has no effect.
33
+
For example, the [Remove-Item][18] cmdlet doesn't normally remove a read-only file. However, this
34
+
cmdlet supports a **Force** parameter so a user can force removal of a read-only file. If the user
35
+
already has permission to modify the read-only attribute, and the user removes the file, use of the
36
+
**Force** parameter simplifies the operation. However, if the user doesn't have permission to remove
37
+
the file, the **Force** parameter has no effect.
39
38
40
39
### Handle Credentials Through Windows PowerShell (AD03)
41
40
42
41
A cmdlet should define a `Credential` parameter to represent credentials. This parameter must be of
43
-
type [System.Management.Automation.PSCredential](/dotnet/api/System.Management.Automation.PSCredential)
44
-
and must be defined using a Credential attribute declaration. This support automatically prompts the
45
-
user for the user name, for the password, or for both when a full credential is not supplied
46
-
directly. For more information about the Credential attribute, see [Credential Attribute Declaration](./credential-attribute-declaration.md).
42
+
type [System.Management.Automation.PSCredential][15] and must be defined using a Credential
43
+
attribute declaration. This support automatically prompts the user for the user name, for the
44
+
password, or for both when a full credential isn't supplied directly. For more information about the
45
+
Credential attribute, see [Credential Attribute Declaration][01].
47
46
48
47
### Support Encoding Parameters (AD04)
49
48
@@ -53,12 +52,13 @@ encoded in the binary form.
53
52
54
53
### Test Cmdlets Should Return a Boolean (AD05)
55
54
56
-
Cmdlets that perform tests against their resources should return a [System.Boolean](/dotnet/api/System.Boolean)
57
-
type to the pipeline so that they can be used in conditional expressions.
55
+
Cmdlets that perform tests against their resources should return a [System.Boolean][06] type to the
56
+
pipeline so that they can be used in conditional expressions.
58
57
59
58
## Code Guidelines
60
59
61
-
The following guidelines should be considered when writing cmdlet code. When you find a guideline that applies to your situation, be sure to look at the Design guidelines for similar guidelines.
60
+
The following guidelines should be considered when writing cmdlet code. When you find a guideline
61
+
that applies to your situation, be sure to look at the Design guidelines for similar guidelines.
62
62
63
63
### Follow Cmdlet Class Naming Conventions (AC01)
64
64
@@ -68,100 +68,116 @@ developers using Windows PowerShell because cmdlets are public types.
68
68
69
69
#### Define a Cmdlet in the Correct Namespace
70
70
71
-
You normally define the class for a cmdlet in a .NET Framework namespace that appends ".Commands" to
71
+
You normally define the class for a cmdlet in a .NET Framework namespace that appends `.Commands` to
72
72
the namespace that represents the product in which the cmdlet runs. For example, cmdlets that are
73
73
included with Windows PowerShell are defined in the `Microsoft.PowerShell.Commands` namespace.
74
74
75
75
#### Name the Cmdlet Class to Match the Cmdlet Name
76
76
77
77
When you name the .NET Framework class that implements a cmdlet, name the class
78
-
"*\<Verb>**\<Noun>**\<Command>*", where you replace the *\<Verb>* and *\<Noun>* placeholders with
79
-
the verb and noun used for the cmdlet name. For example, the [Get-Process](/powershell/module/Microsoft.PowerShell.Management/Get-Process)
80
-
cmdlet is implemented by a class called `GetProcessCommand`.
78
+
`<Verb><Noun>Command`, where you replace the `<Verb>` and `<Noun>` placeholders with the verb and
79
+
noun used for the cmdlet name. For example, the [Get-Process][17] cmdlet is implemented by a class
80
+
called `GetProcessCommand`.
81
81
82
82
### If No Pipeline Input Override the BeginProcessing Method (AC02)
83
83
84
-
If your cmdlet does not accept input from the pipeline, processing should be implemented in the[System.Management.Automation.Cmdlet.BeginProcessing](/dotnet/api/System.Management.Automation.Cmdlet.BeginProcessing)
85
-
method. Use of this method allows Windows PowerShell to maintain ordering between cmdlets. The first
86
-
cmdlet in the pipeline always returns its objects before the remaining cmdlets in the pipeline get a
87
-
chance to start their processing.
84
+
If your cmdlet doesn't accept input from the pipeline, processing should be implemented in the
85
+
[System.Management.Automation.Cmdlet.BeginProcessing][09]method. Use of this method allows Windows
86
+
PowerShell to maintain ordering between cmdlets. The first cmdlet in the pipeline always returns its
87
+
objects before the remaining cmdlets in the pipeline get a chance to start their processing.
88
88
89
89
### To Handle Stop Requests Override the StopProcessing Method (AC03)
90
90
91
-
Override the [System.Management.Automation.Cmdlet.StopProcessing](/dotnet/api/System.Management.Automation.Cmdlet.StopProcessing)
92
-
method so that your cmdlet can handle stop signal. Some cmdlets take a long time to complete their
93
-
operation, and they let a long time pass between calls to the Windows PowerShell runtime, such as
94
-
when the cmdlet blocks the thread in long-running RPC calls. This includes cmdlets that make calls
95
-
to the [System.Management.Automation.Cmdlet.WriteObject](/dotnet/api/System.Management.Automation.Cmdlet.WriteObject)
96
-
method, to the [System.Management.Automation.Cmdlet.WriteError](/dotnet/api/System.Management.Automation.Cmdlet.WriteError)
97
-
method, and to other feedback mechanisms that may take a long time to complete. For these cases the
98
-
user might need to send a stop signal to these cmdlets.
91
+
Override the [System.Management.Automation.Cmdlet.StopProcessing][12] method so that your cmdlet can
92
+
handle stop signal. Some cmdlets take a long time to complete their operation, and they let a long
93
+
time pass between calls to the Windows PowerShell runtime, such as when the cmdlet blocks the thread
94
+
in long-running RPC calls. This includes cmdlets that make calls to the
95
+
[System.Management.Automation.Cmdlet.WriteObject][14] method, to the
96
+
[System.Management.Automation.Cmdlet.WriteError][13] method, and to other feedback mechanisms that
97
+
may take a long time to complete. For these cases the user might need to send a stop signal to these
98
+
cmdlets.
99
99
100
100
### Implement the IDisposable Interface (AC04)
101
101
102
-
If your cmdlet has objects that are not disposed of (written to the pipeline) by the [System.Management.Automation.Cmdlet.ProcessRecord](/dotnet/api/System.Management.Automation.Cmdlet.ProcessRecord)
103
-
method, your cmdlet might require additional object disposal. For example, if your cmdlet opens a
104
-
file handle in its [System.Management.Automation.Cmdlet.BeginProcessing](/dotnet/api/System.Management.Automation.Cmdlet.BeginProcessing)
105
-
method and keeps the handle open for use by the [System.Management.Automation.Cmdlet.ProcessRecord](/dotnet/api/System.Management.Automation.Cmdlet.ProcessRecord)
106
-
method, this handle has to be closed at the end of processing.
107
-
108
-
The Windows PowerShell runtime does not always call the [System.Management.Automation.Cmdlet.EndProcessing](/dotnet/api/System.Management.Automation.Cmdlet.EndProcessing)
109
-
method. For example, the [System.Management.Automation.Cmdlet.EndProcessing](/dotnet/api/System.Management.Automation.Cmdlet.EndProcessing)
110
-
method might not be called if the cmdlet is canceled midway through its operation or if a
111
-
terminating error occurs in any part of the cmdlet. Therefore, the .NET Framework class for a cmdlet
112
-
that requires object cleanup should implement the complete [System.IDisposable](/dotnet/api/System.IDisposable)
113
-
interface pattern, including the finalizer, so that the Windows PowerShell runtime can call both the [System.Management.Automation.Cmdlet.EndProcessing](/dotnet/api/System.Management.Automation.Cmdlet.EndProcessing)
114
-
and [System.IDisposable.Dispose*](/dotnet/api/System.IDisposable.Dispose) methods at the end of
115
-
processing.
102
+
If your cmdlet has objects that aren't disposed of (written to the pipeline) by the
103
+
[System.Management.Automation.Cmdlet.ProcessRecord][11] method, your cmdlet might require additional
104
+
object disposal. For example, if your cmdlet opens a file handle in its
105
+
[System.Management.Automation.Cmdlet.BeginProcessing][09] method and keeps the handle open for use
106
+
by the [System.Management.Automation.Cmdlet.ProcessRecord][11] method, this handle has to be closed
107
+
at the end of processing.
108
+
109
+
The Windows PowerShell runtime doesn't always call the
110
+
[System.Management.Automation.Cmdlet.EndProcessing][10] method. For example, the
111
+
[System.Management.Automation.Cmdlet.EndProcessing][10] method might not be called if the cmdlet is
112
+
canceled midway through its operation or if a terminating error occurs in any part of the cmdlet.
113
+
Therefore, the .NET Framework class for a cmdlet that requires object cleanup should implement the
114
+
complete [System.IDisposable][07] interface pattern, including the finalizer, so that the Windows
115
+
PowerShell runtime can call both the [System.Management.Automation.Cmdlet.EndProcessing][10] and
116
+
[System.IDisposable.Dispose*][08] methods at the end of processing.
116
117
117
118
### Use Serialization-friendly Parameter Types (AC05)
118
119
119
-
To support running your cmdlet on remote computers, use types that can be easily serialized on the
120
-
client computer and then rehydrated on the server computer. The follow types are
121
-
serialization-friendly.
120
+
To support running your cmdlet on remote computers, use types that can be serialized on the client
121
+
computer and then rehydrated on the server computer. The follow types are serialization-friendly.
122
122
123
123
Primitive types:
124
124
125
125
- Byte, SByte, Decimal, Single, Double, Int16, Int32, Int64, Uint16, UInt32, and UInt64.
126
-
127
126
- Boolean, Guid, Byte[], TimeSpan, DateTime, Uri, and Version.
0 commit comments