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
The source code is [KubeCmdletBase.cs](https://github.com/Azure/azure-powershell/blob/77b1e37e11179e59333edd825b2459435cab8726/src/Aks/Aks/Commands/KubeCmdletBase.cs).
The following are naming conventions to keep in mind when coming up with a name for your cmdlet.
6
29
7
-
####Verb-Noun Format
30
+
### Verb-Noun Format
8
31
9
32
Cmdlet names should follow the _Verb-Noun_ format, where the verb is from the [list of approved PowerShell verbs](https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands), and the noun is a specific noun describing a resource within your service.
10
33
11
-
####Noun Prefix
34
+
### Noun Prefix
12
35
13
36
For ARM cmdlets, the noun must be prefixed with `Az`.
14
37
15
-
####Pascal Case
38
+
### Pascal Case
16
39
17
40
From the [_Strongly Encouraged Development Guidelines_](https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/strongly-encouraged-development-guidelines#use-pascal-case-for-cmdlet-names-sd02):
18
41
19
42
> _Use Pascal case for cmdlet names. In other words, capitalize the first letter of the verb and all terms used in the noun. For example, "Clear-ItemProperty"._
20
43
21
-
####Acronyms
44
+
### Acronyms
22
45
Do capitalize both characters of two-character acronyms. For example, New-Az*VM*, Remove-AzCosmos*DB*Table.
23
46
24
-
Do capitalize only the first character of acronyms with three or more characters, which aligned with Pascal case. for example, Restart-Az*Vmss*, New-Az*Sql*Database.
47
+
Do capitalize only the first character of acronyms with three or more characters, which aligned with Pascal case. for example, Restart-Az*Vmss*, New-Az*Sql*Database.
25
48
26
-
####Specific Noun and Noun Singularity
49
+
### Specific Noun and Noun Singularity
27
50
28
51
From the [_Strongly Encouraged Development Guidelines_](https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/strongly-encouraged-development-guidelines#use-a-specific-noun-for-a-cmdlet-name-sd01):
29
52
30
53
> _Nouns used in cmdlet naming need to be very specific so that the user can discover your cmdlets. Prefix generic nouns such as "server" with a shortened version of the product name. For example, if a noun refers to a server that is running an instance of Microsoft SQL Server, use a noun such as "SQLServer". The combination of specific nouns and the short list of approved verbs enable the user to quickly discover and anticipate functionality while avoiding duplication among cmdlet names._
31
54
>
32
55
> _To enhance the user experience, the noun that you choose for a cmdlet name should be singular. For example, use the name `Get-Process` instead of `Get-Processes`. It is best to follow this rule for all cmdlet names, even when a cmdlet is likely to act upon more than one item._
33
56
34
-
####Set vs. Update
57
+
### Set vs. Update
35
58
36
59
If your cmdlet is performing a **PATCH** operation (_i.e._, a partial replacement on the server), then the cmdlet should use the verb `Update`.
37
60
38
61
If your cmdlet is performing a **PUT** operation (_i.e._, a full replacement on the server), the cmdlet should use the verb `Set`.
39
62
40
-
####Cmdlet Alias
63
+
### Cmdlet Alias
41
64
42
65
If you there is a separate nomenclature for your service and/or resource, or if you would like to shorten the name of the cmdlet so it's easier to remember, you can add an alias attribute to your cmdlet to allow for this functionality.
43
66
44
-
###Output Type
67
+
## Output Type
45
68
46
69
Specified by the `OutputType` attribute, this piece of metadata lets the user know what the type of the object returned by the cmdlet is (found in the **Outputs** section of a cmdlet's help content). The type specified here should always be a single element and not an enumeration of elements (_e.g._, `PSVirtualMachine` instead of `List<PSVirtualMachine>`).
47
70
48
-
####Valid Output Types
71
+
### Valid Output Types
49
72
50
73
If the cmdlet returns an object, the type of the object returned must be defined; the output type for a cmdlet should _never_ be `object`, `PSObject`, `PSCustomObject` or the like. Returning these types of objects makes it difficult for the user to anticipate what properties will be found on the object returned from the cmdlet, as well as makes it impossible for the breaking change analyzer to detect if a breaking change was introduced to the cmdlet as the type is not defined.
51
74
52
75
In order to preserve proper piping scenarios, the output type for a cmdlet should _never_ be a `string`. If a cmdlet is expected to return a `string`, the suggestion is to introduce a new type that encapsulates the `string` information as a property and return that object. The PowerShell language revolves around objects and passing them around cmdlets; returning `string` objects can introduce inconsistencies in the piping experience for users.
53
76
54
-
####Returning Wrapped SDK Types
77
+
### Returning Wrapped SDK Types
55
78
56
79
In most cases, cmdlets will be returning an object corresponding to a resource that a user is performing an action on. Rather than returning the .NET SDK type for that resource (exposing .NET SDK types in PowerShell cmdlets is _strongly_ discouraged), we suggest creating a new class that wraps this .NET SDK type, allowing for breaking changes in the underlying type while avoiding breaking changes in the PowerShell type.
57
80
58
81
For example, the `Get-AzVM` cmdlet uses the .NET SDK to retrieve objects of the `VirtualMachine` type, but a new class, `PSVirtualMachine`, was created to wrap the type from the .NET SDK, and is returned by the cmdlet. If, in the future, the `VirtualMachine` type in the .NET SDK has a property removed, that property can still be maintained in PowerShell by adding it to the `PSVirtualMachine` type and recreating the value, thus avoiding a breaking change in the corresponding cmdlet(s).
59
82
60
-
####Returning No Output
83
+
### Returning No Output
61
84
62
85
In the case where your cmdlet doesn't return any output (_e.g._, deleting, starting, stopping a resource), the cmdlet should implement the `-PassThru` parameter and the `OutputType` should be set to `bool`. The `-PassThru` parameter is a `SwitchParameter` set by the user to signal that they would like to receive output from a cmdlet which does not return anything. If the `-PassThru` parameter is provided, you should return the value `true` so the user is made aware that the operation was successful. If the operation was unsuccessful, then the cmdlet should throw an exception.
63
86
@@ -88,7 +111,7 @@ public class MySampleCmdlet : MyBaseCmdlet
88
111
}
89
112
```
90
113
91
-
####Enumerate Collection When WriteObject()
114
+
### Enumerate Collection When WriteObject()
92
115
93
116
When returning a collection of objects, the cmdlet should enumerate the collection. This ensures that the objects are written to the pipeline one at a time, which is the expected behavior for PowerShell cmdlets.
94
117
@@ -109,7 +132,32 @@ foreach (var resource in resources)
109
132
WriteObject(resources, true);
110
133
```
111
134
112
-
### `ShouldProcess`
135
+
## Output Format
136
+
137
+
PowerShell supports several output formats, including `table`, `list`, and `wide`. The default output format for Azure PowerShell cmdlets is `table`, which is the most readable for displaying a list of resources. Here's an example:
138
+
139
+
```powershell
140
+
PS > Get-AzVM
141
+
142
+
ResourceGroupName Name Location VmSize OsType NIC
143
+
----------------- ---- -------- ------ ------ ---
144
+
TEST1 test1 eastus Standard_DS1_v2 Windows test1
145
+
TEST1 test2 westus Standard_DS1_v2 Windows test2
146
+
TEST1 test3 eastus Standard_DS1_v2 Windows test3
147
+
TEST2 test4 westus Standard_DS1_v2 Windows test4
148
+
TEST2 test5 eastus Standard_DS1_v2 Windows test5
149
+
```
150
+
151
+
The idea about table format is for users to be able to quickly scan the output and find the information they are looking for. To achieve this, follow the golden rule of thumb: **show only the MVPs (most valuable properties)**.
152
+
153
+
It's obvious that important properties need to be displayed, but be careful not to overcrowd the output with too many properties. PowerShell console has a limited width, so if there are too many columns, the output may be truncated and lose the meaning of being quickly readable.
154
+
155
+
A practical way of designing the table format is:
156
+
157
+
1. List the properties from the most important to the least important.
158
+
2. Take the most important properties until (a) the width of the console is filled or (b) the rest of the properties are not important enough to be displayed.
159
+
160
+
## `ShouldProcess`
113
161
114
162
If a cmdlet makes any changes to an object on the server (_e.g._, create, delete, update, start, stop a resource), the cmdlet should implement `ShouldProcess`. This property adds the `-WhatIf` and `-Confirm` parameters to the cmdlet:
115
163
@@ -138,13 +186,13 @@ public class MySampleCmdlet : MyBaseCmdlet
138
186
139
187
More information about `ShouldProcess` can be found in the [_Should Process and Confirm Impact_](./should-process-confirm-impact.md) document.
140
188
141
-
####When to Add the Force Parameter
189
+
### When to Add the Force Parameter
142
190
143
191
The `-Force` parameter is reserved for special scenarios where additional confirmation from the user is required. From the above document on [_Should Process and Confirm Impact_](./should-process-confirm-impact.md) document:
144
192
145
193
> _Some cmdlets require additional confirmation. For example, if a cmdlet would destroy existing resources in some circumstances, the cmdlet might detect that condition and prompt the user to verify before continuing. Overwriting an existing resource during resource creation, overwriting a file when downloading data, deleting a resource that is currently in use, or deleting a container that contains additional resources are all example of this pattern. To implement additional confirmation, and allow scripts to opt out of additional prompts, the above pattern is enhanced with calls to `ShouldContinue()` and the `-Force` parameter._
146
194
147
-
###`AsJob`
195
+
## `AsJob`
148
196
149
197
All long running operations must implement the `-AsJob` parameter, which will allow the user to create jobs in the background. For more information about PowerShell jobs and the `-AsJob` parameter, read [this doc](https://learn.microsoft.com/en-us/powershell/azure/using-psjobs).
To set a custom job name, please use [`SetBackgroupJobDescription`](https://github.com/Azure/azure-powershell-common/blob/main/src/Common/AzurePSCmdlet.cs#L810). The default job description is: "Long Running Operation for '{cmdlet name}' on resource '{resource name}'"
169
217
170
-
###Required Parameter Sets
218
+
## Required Parameter Sets
171
219
172
220
In most Azure PowerShell cmdlets, there is a bare minimum of three parameter sets that need to be implemented.
173
221
174
-
####Interactive Parameter Set
222
+
### Interactive Parameter Set
175
223
176
224
This parameter set should be implemented by _every_ cmdlet - in most cases, the user provides the name of the resource that they are acting upon (`-Name`) and the resource group in which they are acting in (`-ResourceGroupName`).
177
225
178
226
The interactive parameter set **will always be the default parameter set** for a cmdlet (specified by the `DefaultParameterSetName` property in the `Cmdlet` attribute). This means that when PowerShell is unable to determine which parameter set a user is in, it will default to the interactive parameter set and prompt the user to provide values for the missing mandatory parameters.
179
227
180
-
####ResourceId Parameter Set
228
+
### ResourceId Parameter Set
181
229
182
230
This parameter set should be implemented by _every_ cmdlet - the user is able to provide a `-ResourceId` string or GUID from the Azure Portal, or from one of the generic resources cmdlets (more information about this scenario can be found in the [`piping-best-practices.md`](./piping-best-practices.md#using-the--resourceid-parameter) document), and act upon the given resource associated with the id. The typical `-Name` and `-ResourceGroupName` parameters are replaced by a single `-ResourceId` parameter of type string.
183
231
184
-
####InputObject Parameter Set
232
+
### InputObject Parameter Set
185
233
186
234
This parameter should be implemented by _most_ cmdlets - the user is able to take the object returned from the `Get`, `New`, or `Set` cmdlets (or other cmdlets that return the common resource) and provide it to the `-InputObject` parameter for a cmdlet that acts upon the same resource (more information about this scenario can be found in the [`piping-best-practices.md`](./piping-best-practices.md#using-the--inputobject-parameter) document). The typical `-Name` and `-ResourceGroupName` parameters are retrieved from the `-InputObject` that the user is passing through.
@@ -61,7 +88,7 @@ From the [_Strongly Encouraged Development Guidelines_](https://learn.microsoft.
61
88
62
89
For parameters whose type is string and which represent a value that should be kept secret in some fashion (such as a password, secret, key, etc.), the type of the parameter should be [SecureString](https://learn.microsoft.com/dotnet/api/system.security.securestring) to limit the exposure of sensitive string data from unexpected leakage during cmdlet execution. The practice also applies to output properties whose type is string and that should be kept in secret.
63
90
64
-
Please notice that DO NOT use `SecureString` for encryption purposes. We only recommend to use `SecureString` as a wrapper of string to prevent unexpected leakage of information as string may still be exposed to any process or operation that has access to raw memory.
91
+
Please notice that DO NOT use `SecureString` for encryption purposes. We only recommend to use `SecureString` as a wrapper of string to prevent unexpected leakage of information as string may still be exposed to any process or operation that has access to raw memory.
65
92
66
93
From [How secure is SecureString?](https://learn.microsoft.com/dotnet/api/system.security.securestring#how-secure-is-securestring)
67
94
@@ -170,8 +197,8 @@ Allowing the user to pipe an object from one cmdlet to another is a major scenar
170
197
171
198
## Appendix: Parameter Syntax
172
199
173
-
In PowerShell documentation, square brackets (`[]`) indicate optional.
174
-
Convention is as follows:
200
+
In PowerShell documentation, square brackets (`[]`) indicate optional.
201
+
Convention is as follows:
175
202
176
203
```powershell
177
204
command-name
@@ -181,18 +208,18 @@ command-name
181
208
[-OptionalParameterName] <RequiredParameterValue>
182
209
```
183
210
184
-
Using `New-Alias` cmdlet as an example:
211
+
Using `New-Alias` cmdlet as an example:
185
212
186
213
```powershell
187
-
New-Alias
188
-
[-Name] <string> -required 'positional' parameter
189
-
[-Value] <string>
190
-
[-Description <string>] -optional parameter
191
-
[-Force] -optional switch parameter (all switch parameters are optional, non-positional)
Copy file name to clipboardExpand all lines: documentation/development-docs/design-guidelines/piping-best-practices.md
+11Lines changed: 11 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,6 +2,17 @@
2
2
3
3
_Note_: for the below examples, the string "TopLevelResource" would be replaced with the name of your top-level resource (_e.g._, "VirtualMachine", "VirtualNetwork", "SqlServer"), and the string "ChildResource" would be replaced with the name of your child resource (_e.g._, "VirtualMachineExtension", "VirtualNetworkPeering", "SqlDatabase")
4
4
5
+
-[Piping in PowerShell](#piping-in-powershell)
6
+
-[Understanding Piping](#understanding-piping)
7
+
-[Piping in Azure PowerShell](#piping-in-azure-powershell)
8
+
-[Using the `-InputObject` Parameter](#using-the--inputobject-parameter)
9
+
-[Short explanation](#short-explanation)
10
+
-[Long explanation](#long-explanation)
11
+
-[Using the `-ResourceId` Parameter](#using-the--resourceid-parameter)
0 commit comments