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
Copy file name to clipboardExpand all lines: developer/cmdlet/approved-verbs-for-windows-powershell-commands.md
+62-43Lines changed: 62 additions & 43 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,5 @@
1
1
---
2
-
title: "Approved Verbs for Windows PowerShell Commands | Microsoft Docs"
2
+
title: "Approved Verbs for PowerShell Commands | Microsoft Docs"
3
3
ms.custom: ""
4
4
ms.date: "06/21/2018"
5
5
ms.reviewer: ""
@@ -13,58 +13,70 @@ helpviewer_keywords:
13
13
ms.assetid: 2d4e58a9-05bc-437c-86b9-d8d55cba7d48
14
14
caps.latest.revision: 36
15
15
---
16
-
# Approved Verbs for Windows PowerShell Commands
16
+
# Approved Verbs for PowerShell Commands
17
17
18
-
Windows PowerShell uses a verb-noun pair for the names of cmdlets and for their derived Microsoft .NET Framework classes. For example, the `Get-Command` cmdlet provided by Windows PowerShell is used to retrieve all the commands that are registered in Windows PowerShell. The verb part of the name identifies the action that the cmdlet performs. The noun part of the name identifies the entity on which the action is performed.
18
+
PowerShell uses a verb-noun pair for the names of cmdlets and for their derived Microsoft .NET Framework classes.
19
+
For example, the `Get-Command` cmdlet provided by PowerShell is used to retrieve all the commands that are registered in PowerShell.
20
+
The verb part of the name identifies the action that the cmdlet performs.
21
+
The noun part of the name identifies the entity on which the action is performed.
19
22
20
23
> [!NOTE]
21
-
> Windows PowerShell uses the term *verb* to describe a word that implies an action even if that word is not a standard verb in the English language. For example, the term *New* is a valid Windows PowerShell verb name because it implies an action even though it is not a verb in the English language.
24
+
> PowerShell uses the term *verb* to describe a word that implies an action even if that word is not a standard verb in the English language.
25
+
> For example, the term *New* is a valid PowerShell verb name because it implies an action even though it is not a verb in the English language.
22
26
23
27
## Verb Naming Rules
24
28
25
29
The following list provides guidelines to consider when you choose the verb for a cmdlet name:
26
30
27
-
- When you specify the verb, we recommend that you use one of the predefined verb names provided by Windows PowerShell (aliases for these predefined verbs are included in the following tables). When you use a predefined verb, you ensure consistency between the cmdlets that you create, the cmdlets that are provided by Windows PowerShell, and the cmdlets that are designed by others.
31
+
* When you specify the verb, we recommend that you use one of the predefined verb names provided by PowerShell (aliases for these predefined verbs are included in the following tables).
32
+
When you use a predefined verb, you ensure consistency between the cmdlets that you create, the cmdlets that are provided by PowerShell, and the cmdlets that are designed by others.
28
33
29
-
- Use the predefined verbs to describe the general scope of the action, and use parameters to further refine the action of the cmdlet.
34
+
* Use the predefined verbs to describe the general scope of the action, and use parameters to further refine the action of the cmdlet.
30
35
31
-
- To enforce consistency across cmdlets, do not use a synonym of an approved verb.
36
+
* To enforce consistency across cmdlets, do not use a synonym of an approved verb.
32
37
33
-
- Use only the form of each verb that is listed in this topic. For example, use "Get", but do not use "Getting" or "Gets".
38
+
* Use only the form of each verb that is listed in this topic.
39
+
For example, use "Get", but do not use "Getting" or "Gets".
34
40
35
-
- Use Pascal casing for verbs. In Pascal casing the initial letter of each word is capitalized, such as "ForEach".
41
+
* Use Pascal casing for verbs.
42
+
In Pascal casing the initial letter of each word is capitalized, such as "ForEach".
36
43
37
-
- Do not use the following reserved verbs or aliases. These verbs are used by the Windows PowerShell language, or by special case cmdlets provided by Windows PowerShell.
38
-
39
-
- ForEach (foreach)
40
-
41
-
- Format (f)
42
-
43
-
- Group (gp)
44
-
45
-
- Sort (sr)
46
-
47
-
- Tee (te)
48
-
49
-
- Where (wh)
44
+
* Do not use the following reserved verbs or aliases.
45
+
These verbs are used by the PowerShell language, or by special case cmdlets provided by PowerShell.
46
+
- ForEach (foreach)
47
+
- Format (f)
48
+
- Group (gp)
49
+
- Sort (sr)
50
+
- Tee (te)
51
+
- Where (wh)
50
52
51
53
## Similar Verbs for Different Actions
52
54
53
55
The following similar verbs represent different actions.
54
56
55
-
-`New` vs. `Set`: The `New` verb is used to create a new resource. The `Set` verb is used to modify an existing resource, optionally creating the resource if it does not exist, such as the `Set-Variable` cmdlet.
57
+
### New vs. Set
58
+
The `New` verb is used to create a new resource.
59
+
The `Set` verb is used to modify an existing resource, optionally creating the resource if it does not exist, such as the `Set-Variable` cmdlet.
56
60
57
-
-`Find` vs. `Search`: The `Find` verb is used to look for an object. The `Search` verb is used to create a reference to a resource in a container.
61
+
### Find vs. Search
62
+
The `Find` verb is used to look for an object.
63
+
The `Search` verb is used to create a reference to a resource in a container.
58
64
59
-
-`Get` vs. `Read`: The `Get` verb is used to retrieve a resource, such as a file. The `Read` verb is used to get information from a source, such as a file.
65
+
### Get vs. Read
66
+
The `Get` verb is used to retrieve a resource, such as a file.
67
+
The `Read` verb is used to get information from a source, such as a file.
60
68
61
-
-`Invoke` vs. `Start`: The `Invoke` verb is used to perform an operation that is generally a synchronous operation, such as running a command. The `Start` verb is used to begin an operation that is generally an asynchronous operation, such as starting a process.
69
+
### Invoke vs. Start
70
+
The `Invoke` verb is used to perform an operation that is generally a synchronous operation, such as running a command.
71
+
The `Start` verb is used to begin an operation that is generally an asynchronous operation, such as starting a process.
62
72
63
-
-`Ping` vs. `Test`: Use the `Test` verb.
73
+
### Ping vs. Test
74
+
Use the `Test` verb.
64
75
65
76
## Common Verbs
66
77
67
-
Windows PowerShell uses the [System.Management.Automation.Verbscommon](/dotnet/api/System.Management.Automation.VerbsCommon) enumeration class to define generic actions that can apply to almost any cmdlet. The following table lists most of the defined verbs.
78
+
PowerShell uses the [System.Management.Automation.VerbsCommon](/dotnet/api/System.Management.Automation.VerbsCommon) enumeration class to define generic actions that can apply to almost any cmdlet.
79
+
The following table lists most of the defined verbs.
@@ -91,7 +103,7 @@ Windows PowerShell uses the [System.Management.Automation.Verbscommon](/dotnet/a
91
103
|[Reset](/dotnet/api/System.Management.Automation.VerbsCommon.Reset) (rs)|Sets a resource back to its original state.||
92
104
|[Search](/dotnet/api/System.Management.Automation.VerbsCommon.Search) (sr)|Creates a reference to a resource in a container.|For this action, do not use verbs such as Find or Locate.|
93
105
|[Select](/dotnet/api/System.Management.Automation.VerbsCommon.Select) (sc)|Locates a resource in a container. For example, the `Select-String` cmdlet finds text in strings and files.|For this action, do not use verbs such as Find or Locate.|
94
-
|[Set](/dotnet/api/System.Management.Automation.VerbsCommon.Set) (s)|Replaces data on an existing resource or creates a resource that contains some data. For example, the `Set-Date` cmdlet changes the system time on the local computer. (The New verb can also be used to create a resource.) This verb is paired with `Get`.|For this action, do not use verbs such as Write, Reset, Assign, or Configure.|
106
+
|[Set](/dotnet/api/System.Management.Automation.VerbsCommon.Set) (s)|Replaces data on an existing resource or creates a resource that contains some data. For example, the `Set-Date` cmdlet changes the system time on the local computer. (The `New` verb can also be used to create a resource.) This verb is paired with `Get`.|For this action, do not use verbs such as Write, Reset, Assign, or Configure.|
95
107
|[Show](/dotnet/api/System.Management.Automation.VerbsCommon.Show) (sh)|Makes a resource visible to the user. This verb is paired with `Hide`.|For this action, do not use verbs such as Display or Produce.|
96
108
|[Skip](/dotnet/api/System.Management.Automation.VerbsCommon.Skip) (sk)|Bypasses one or more resources or points in a sequence.|For this action, do not use a verb such as Bypass or Jump.|
97
109
|[Split](/dotnet/api/System.Management.Automation.VerbsCommon.Split) (sl)|Separates parts of a resource. For example, the `Split-Path` cmdlet returns different parts of a path. This verb is paired with `Join`.|For this action, do not use a verb such Separate.|
@@ -103,7 +115,8 @@ Windows PowerShell uses the [System.Management.Automation.Verbscommon](/dotnet/a
103
115
104
116
## Communications Verbs
105
117
106
-
Windows PowerShell uses the [System.Management.Automation.Verbscommunications](/dotnet/api/System.Management.Automation.VerbsCommunications) class to define actions that apply to communications. The following table lists most of the defined verbs.
118
+
PowerShell uses the [System.Management.Automation.VerbsCommunications](/dotnet/api/System.Management.Automation.VerbsCommunications) class to define actions that apply to communications.
119
+
The following table lists most of the defined verbs.
@@ -116,7 +129,8 @@ Windows PowerShell uses the [System.Management.Automation.Verbscommunications](/
116
129
117
130
## Data Verbs
118
131
119
-
Windows PowerShell uses the [System.Management.Automation.Verbsdata](/dotnet/api/System.Management.Automation.VerbsData) class to define actions that apply to data handling. The following table lists most of the defined verbs.
132
+
PowerShell uses the [System.Management.Automation.VerbsData](/dotnet/api/System.Management.Automation.VerbsData) class to define actions that apply to data handling.
133
+
The following table lists most of the defined verbs.
@@ -143,11 +157,12 @@ Windows PowerShell uses the [System.Management.Automation.Verbsdata](/dotnet/api
143
157
|[Save](/dotnet/api/System.Management.Automation.VerbsData.Save) (sv)|Preserves data to avoid loss.||
144
158
|[Sync](/dotnet/api/System.Management.Automation.VerbsData.Sync) (sy)|Assures that two or more resources are in the same state.|For this action, do not use verbs such as Replicate, Coerce, or Match.|
145
159
|[Unpublish](/dotnet/api/System.Management.Automation.VerbsData.Unpublish) (ub)|Makes a resource unavailable to others. This verb is paired with `Publish`.|For this action, do not use verbs such as Uninstall, Revert, or Hide.|
146
-
|[Update](/dotnet/api/System.Management.Automation.VerbsData.Update) (ud)|Brings a resource up-to-date to maintain its state, accuracy, conformance, or compliance. For example, the `Update-FormatData` cmdlet updates and adds formatting files to the current Windows PowerShell console.|For this action, do not use verbs such as Refresh, Renew, Recalculate, or Re-index.|
160
+
|[Update](/dotnet/api/System.Management.Automation.VerbsData.Update) (ud)|Brings a resource up-to-date to maintain its state, accuracy, conformance, or compliance. For example, the `Update-FormatData` cmdlet updates and adds formatting files to the current PowerShell console.|For this action, do not use verbs such as Refresh, Renew, Recalculate, or Re-index.|
147
161
148
162
## Diagnostic Verbs
149
163
150
-
Windows PowerShell uses the [System.Management.Automation.Verbsdiagnostic](/dotnet/api/System.Management.Automation.VerbsDiagnostic) class to define actions that apply to diagnostics. The following table lists most of the defined verbs.
164
+
PowerShell uses the [System.Management.Automation.VerbsDiagnostic](/dotnet/api/System.Management.Automation.VerbsDiagnostic) class to define actions that apply to diagnostics.
165
+
The following table lists most of the defined verbs.
@@ -161,7 +176,8 @@ Windows PowerShell uses the [System.Management.Automation.Verbsdiagnostic](/dotn
161
176
162
177
## Lifecycle Verbs
163
178
164
-
Windows PowerShell uses the [System.Management.Automation.Verbslifecycle](/dotnet/api/System.Management.Automation.VerbsLifeCycle) class to define actions that apply to the lifecycle of a resource. The following table lists most of the defined verbs.
179
+
PowerShell uses the [System.Management.Automation.VerbsLifeCycle](/dotnet/api/System.Management.Automation.VerbsLifeCycle) class to define actions that apply to the lifecycle of a resource.
180
+
The following table lists most of the defined verbs.
@@ -184,11 +200,12 @@ Windows PowerShell uses the [System.Management.Automation.Verbslifecycle](/dotne
184
200
|[Suspend](/dotnet/api/System.Management.Automation.VerbsLifecycle.Suspend) (ss)|Pauses an activity. For example, the `Suspend-Service` cmdlet pauses a service. This verb is paired with `Resume`.|For this action, do not use a verb such as Pause.|
185
201
|[Uninstall](/dotnet/api/System.Management.Automation.VerbsLifecycle.Uninstall) (us)|Removes a resource from an indicated location. This verb is paired with `Install`.||
186
202
|[Unregister](/dotnet/api/System.Management.Automation.VerbsLifecycle.Unregister) (ur)|Removes the entry for a resource from a repository. This verb is paired with `Register`.|For this action, do not use a verb such as Remove.|
187
-
|[Wait](/dotnet/api/System.Management.Automation.VerbsLifecycle.Wait) (w)|Pauses an operation until a specified event occurs. For example, the **Wait-PSJob** cmdlet pauses operations until one or more of the background jobs are complete.|For this action, do not use verbs such as Sleep or Pause.|
203
+
|[Wait](/dotnet/api/System.Management.Automation.VerbsLifecycle.Wait) (w)|Pauses an operation until a specified event occurs. For example, the `Wait-Job` cmdlet pauses operations until one or more of the background jobs are complete.|For this action, do not use verbs such as Sleep or Pause.|
188
204
189
205
## Security Verbs
190
206
191
-
Windows PowerShell uses the [System.Management.Automation.Verbssecurity](/dotnet/api/System.Management.Automation.VerbsSecurity) class to define actions that apply to security. The following table lists most of the defined verbs.
207
+
PowerShell uses the [System.Management.Automation.VerbsSecurity](/dotnet/api/System.Management.Automation.VerbsSecurity) class to define actions that apply to security.
208
+
The following table lists most of the defined verbs.
@@ -201,25 +218,27 @@ Windows PowerShell uses the [System.Management.Automation.Verbssecurity](/dotnet
201
218
202
219
## Other Verbs
203
220
204
-
Windows PowerShell uses the [System.Management.Automation.Verbsother](/dotnet/api/System.Management.Automation.VerbsOther) class to define canonical verb names that do not fit into a specific verb name category such as the common, communications, data, lifecycle, or security verb names verbs.
221
+
PowerShell uses the [System.Management.Automation.VerbsOther](/dotnet/api/System.Management.Automation.VerbsOther) class to define canonical verb names that do not fit into a specific verb name category such as the common, communications, data, lifecycle, or security verb names verbs.
0 commit comments