From 9a2abd91607f82081c9b7e4e5f3fe99b3c4d61c4 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 31 Oct 2023 09:43:56 -0500 Subject: [PATCH 1/2] Remove copy/paste error in description (#10600) --- .../Add-Content.md | 29 ++++++++-------- .../Add-Content.md | 33 +++++++++---------- .../Add-Content.md | 33 +++++++++---------- .../Add-Content.md | 33 +++++++++---------- 4 files changed, 62 insertions(+), 66 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Management/Add-Content.md b/reference/5.1/Microsoft.PowerShell.Management/Add-Content.md index 1458dba7a5e0..525bf0482099 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Add-Content.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Add-Content.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 10/12/2023 +ms.date: 10/31/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/add-content?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Add-Content @@ -36,8 +36,7 @@ Add-Content [-Value] -LiteralPath [-PassThru] [-Filter [!NOTE] -> This parameter is not supported by any providers installed with PowerShell. +> This parameter isn't supported by any providers installed with PowerShell. > To impersonate another user, or elevate your credentials when running this cmdlet, > use [Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md). @@ -241,7 +240,7 @@ installed PowerShell provider that supports the use of filters. You can find the **FileSystem** filter language in [about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather -than having PowerShell filter the objects after they are retrieved. +than having PowerShell filter the objects after they're retrieved. ```yaml Type: System.String @@ -258,7 +257,7 @@ Accept wildcard characters: True ### -Force Overrides the read-only attribute, allowing you to add content to a read-only file. For example, -**Force** overrides the read-only attribute but it does not change file permissions. +**Force** overrides the read-only attribute but it doesn't change file permissions. ```yaml Type: System.Management.Automation.SwitchParameter @@ -294,7 +293,7 @@ Accept wildcard characters: True ### -LiteralPath -Specifies a path to one or more locations. The value of **LiteralPath** is used exactly as it is +Specifies a path to one or more locations. The value of **LiteralPath** is used exactly as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -316,7 +315,7 @@ Accept wildcard characters: False ### -NoNewline -Indicates that this cmdlet does not add a new line or carriage return to the content. +Indicates that this cmdlet doesn't add a new line or carriage return to the content. The string representations of the input objects are concatenated to form the output. No spaces or newlines are inserted between the output strings. No newline is added after the last output string. @@ -335,7 +334,7 @@ Accept wildcard characters: False ### -PassThru -Returns an object representing the added content. By default, this cmdlet does not generate any +Returns an object representing the added content. By default, this cmdlet doesn't generate any output. ```yaml @@ -371,14 +370,14 @@ Accept wildcard characters: True ### -Stream -Specifies an alternative data stream for content. If the stream does not exist, this cmdlet creates -it. Wildcard characters are not supported. +Specifies an alternative data stream for content. If the stream doesn't exist, this cmdlet creates +it. Wildcard characters aren't supported. **Stream** is a dynamic parameter that the FileSystem provider adds to `Add-Content`. This parameter works only in file system drives. You can use the `Add-Content` cmdlet to change the content of any alternate data stream, such as -`Zone.Identifier`. However, we do not recommend this as a way to eliminate security checks that +`Zone.Identifier`. However, we don't recommend this as a way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the `Unblock-File` cmdlet. @@ -419,7 +418,7 @@ Specifies the content to be added. Type a quoted string, such as **This data is only**, or specify an object that contains content, such as the **DateTime** object that `Get-Date` generates. -You cannot specify the contents of a file by typing its path, because the path is just a string. +You can't specify the contents of a file by typing its path, because the path is just a string. You can use a `Get-Content` command to get the content and pass it to the **Value** parameter. ```yaml @@ -452,7 +451,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: System.Management.Automation.SwitchParameter @@ -500,7 +499,7 @@ Windows PowerShell includes the following aliases for `Add-Content`: - `ac` -- When you pipe an object to `Add-Content`, the object is converted to a string before it is added +- When you pipe an object to `Add-Content`, the object is converted to a string before it's added to the item. The object type determines the string format, but the format might be different than the default display of the object. To control the string format, use the formatting parameters of the sending cmdlet. diff --git a/reference/7.2/Microsoft.PowerShell.Management/Add-Content.md b/reference/7.2/Microsoft.PowerShell.Management/Add-Content.md index 5721372009e6..ed6aabbb7df3 100644 --- a/reference/7.2/Microsoft.PowerShell.Management/Add-Content.md +++ b/reference/7.2/Microsoft.PowerShell.Management/Add-Content.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 10/12/2023 +ms.date: 10/31/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/add-content?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: Add-Content @@ -36,8 +36,7 @@ Add-Content [-Value] -LiteralPath [-PassThru] [-Filter [!NOTE] -> This parameter is not supported by any providers installed with PowerShell. +> This parameter isn't supported by any providers installed with PowerShell. > To impersonate another user, or elevate your credentials when running this cmdlet, > use [Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md). @@ -281,7 +280,7 @@ installed PowerShell provider that supports the use of filters. You can find the **FileSystem** filter language in [about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather -than having PowerShell filter the objects after they are retrieved. +than having PowerShell filter the objects after they're retrieved. ```yaml Type: System.String @@ -298,7 +297,7 @@ Accept wildcard characters: True ### -Force Overrides the read-only attribute, allowing you to add content to a read-only file. For example, -**Force** overrides the read-only attribute but it does not change file permissions. +**Force** overrides the read-only attribute but it doesn't change file permissions. ```yaml Type: System.Management.Automation.SwitchParameter @@ -334,7 +333,7 @@ Accept wildcard characters: True ### -LiteralPath -Specifies a path to one or more locations. The value of **LiteralPath** is used exactly as it is +Specifies a path to one or more locations. The value of **LiteralPath** is used exactly as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -356,7 +355,7 @@ Accept wildcard characters: False ### -NoNewline -Indicates that this cmdlet does not add a new line or carriage return to the content. +Indicates that this cmdlet doesn't add a new line or carriage return to the content. The string representations of the input objects are concatenated to form the output. No spaces or newlines are inserted between the output strings. No newline is added after the last output string. @@ -375,7 +374,7 @@ Accept wildcard characters: False ### -PassThru -Returns an object representing the added content. By default, this cmdlet does not generate any +Returns an object representing the added content. By default, this cmdlet doesn't generate any output. ```yaml @@ -414,14 +413,14 @@ Accept wildcard characters: True > [!NOTE] > This Parameter is only available on Windows. -Specifies an alternative data stream for content. If the stream does not exist, this cmdlet creates -it. Wildcard characters are not supported. +Specifies an alternative data stream for content. If the stream doesn't exist, this cmdlet creates +it. Wildcard characters aren't supported. **Stream** is a dynamic parameter that the FileSystem provider adds to `Add-Content`. This parameter works only in file system drives. You can use the `Add-Content` cmdlet to change the content of any alternate data stream, such as -`Zone.Identifier`. However, we do not recommend this as a way to eliminate security checks that +`Zone.Identifier`. However, we don't recommend this as a way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the `Unblock-File` cmdlet. @@ -447,7 +446,7 @@ Specifies the content to be added. Type a quoted string, such as **This data is only**, or specify an object that contains content, such as the **DateTime** object that `Get-Date` generates. -You cannot specify the contents of a file by typing its path, because the path is just a string. +You can't specify the contents of a file by typing its path, because the path is just a string. You can use a `Get-Content` command to get the content and pass it to the **Value** parameter. ```yaml @@ -480,7 +479,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: System.Management.Automation.SwitchParameter @@ -529,7 +528,7 @@ PowerShell includes the following aliases for `Add-Content`: - Windows: - `ac` -- When you pipe an object to `Add-Content`, the object is converted to a string before it is added +- When you pipe an object to `Add-Content`, the object is converted to a string before it's added to the item. The object type determines the string format, but the format might be different than the default display of the object. To control the string format, use the formatting parameters of the sending cmdlet. diff --git a/reference/7.3/Microsoft.PowerShell.Management/Add-Content.md b/reference/7.3/Microsoft.PowerShell.Management/Add-Content.md index 038d426ec09a..2f6ed33bcd64 100644 --- a/reference/7.3/Microsoft.PowerShell.Management/Add-Content.md +++ b/reference/7.3/Microsoft.PowerShell.Management/Add-Content.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 10/12/2023 +ms.date: 10/31/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/add-content?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: Add-Content @@ -36,8 +36,7 @@ Add-Content [-Value] -LiteralPath [-PassThru] [-Filter [!NOTE] -> This parameter is not supported by any providers installed with PowerShell. +> This parameter isn't supported by any providers installed with PowerShell. > To impersonate another user, or elevate your credentials when running this cmdlet, > use [Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md). @@ -281,7 +280,7 @@ installed PowerShell provider that supports the use of filters. You can find the **FileSystem** filter language in [about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather -than having PowerShell filter the objects after they are retrieved. +than having PowerShell filter the objects after they're retrieved. ```yaml Type: System.String @@ -298,7 +297,7 @@ Accept wildcard characters: True ### -Force Overrides the read-only attribute, allowing you to add content to a read-only file. For example, -**Force** overrides the read-only attribute but it does not change file permissions. +**Force** overrides the read-only attribute but it doesn't change file permissions. ```yaml Type: System.Management.Automation.SwitchParameter @@ -334,7 +333,7 @@ Accept wildcard characters: True ### -LiteralPath -Specifies a path to one or more locations. The value of **LiteralPath** is used exactly as it is +Specifies a path to one or more locations. The value of **LiteralPath** is used exactly as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -356,7 +355,7 @@ Accept wildcard characters: False ### -NoNewline -Indicates that this cmdlet does not add a new line or carriage return to the content. +Indicates that this cmdlet doesn't add a new line or carriage return to the content. The string representations of the input objects are concatenated to form the output. No spaces or newlines are inserted between the output strings. No newline is added after the last output string. @@ -375,7 +374,7 @@ Accept wildcard characters: False ### -PassThru -Returns an object representing the added content. By default, this cmdlet does not generate any +Returns an object representing the added content. By default, this cmdlet doesn't generate any output. ```yaml @@ -414,14 +413,14 @@ Accept wildcard characters: True > [!NOTE] > This Parameter is only available on Windows. -Specifies an alternative data stream for content. If the stream does not exist, this cmdlet creates -it. Wildcard characters are not supported. +Specifies an alternative data stream for content. If the stream doesn't exist, this cmdlet creates +it. Wildcard characters aren't supported. **Stream** is a dynamic parameter that the FileSystem provider adds to `Add-Content`. This parameter works only in file system drives. You can use the `Add-Content` cmdlet to change the content of any alternate data stream, such as -`Zone.Identifier`. However, we do not recommend this as a way to eliminate security checks that +`Zone.Identifier`. However, we don't recommend this as a way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the `Unblock-File` cmdlet. @@ -447,7 +446,7 @@ Specifies the content to be added. Type a quoted string, such as **This data is only**, or specify an object that contains content, such as the **DateTime** object that `Get-Date` generates. -You cannot specify the contents of a file by typing its path, because the path is just a string. +You can't specify the contents of a file by typing its path, because the path is just a string. You can use a `Get-Content` command to get the content and pass it to the **Value** parameter. ```yaml @@ -480,7 +479,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: System.Management.Automation.SwitchParameter @@ -529,7 +528,7 @@ PowerShell includes the following aliases for `Add-Content`: - Windows: - `ac` -- When you pipe an object to `Add-Content`, the object is converted to a string before it is added +- When you pipe an object to `Add-Content`, the object is converted to a string before it's added to the item. The object type determines the string format, but the format might be different than the default display of the object. To control the string format, use the formatting parameters of the sending cmdlet. diff --git a/reference/7.4/Microsoft.PowerShell.Management/Add-Content.md b/reference/7.4/Microsoft.PowerShell.Management/Add-Content.md index 4912c6130d65..0704020c3c27 100644 --- a/reference/7.4/Microsoft.PowerShell.Management/Add-Content.md +++ b/reference/7.4/Microsoft.PowerShell.Management/Add-Content.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 10/12/2023 +ms.date: 10/31/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.management/add-content?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: Add-Content @@ -36,8 +36,7 @@ Add-Content [-Value] -LiteralPath [-PassThru] [-Filter [!NOTE] -> This parameter is not supported by any providers installed with PowerShell. +> This parameter isn't supported by any providers installed with PowerShell. > To impersonate another user, or elevate your credentials when running this cmdlet, > use [Invoke-Command](../Microsoft.PowerShell.Core/Invoke-Command.md). @@ -286,7 +285,7 @@ installed PowerShell provider that supports the use of filters. You can find the **FileSystem** filter language in [about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). Filters are more efficient than other parameters, because the provider applies them when the cmdlet gets the objects rather -than having PowerShell filter the objects after they are retrieved. +than having PowerShell filter the objects after they're retrieved. ```yaml Type: System.String @@ -303,7 +302,7 @@ Accept wildcard characters: True ### -Force Overrides the read-only attribute, allowing you to add content to a read-only file. For example, -**Force** overrides the read-only attribute but it does not change file permissions. +**Force** overrides the read-only attribute but it doesn't change file permissions. ```yaml Type: System.Management.Automation.SwitchParameter @@ -339,7 +338,7 @@ Accept wildcard characters: True ### -LiteralPath -Specifies a path to one or more locations. The value of **LiteralPath** is used exactly as it is +Specifies a path to one or more locations. The value of **LiteralPath** is used exactly as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences. @@ -361,7 +360,7 @@ Accept wildcard characters: False ### -NoNewline -Indicates that this cmdlet does not add a new line or carriage return to the content. +Indicates that this cmdlet doesn't add a new line or carriage return to the content. The string representations of the input objects are concatenated to form the output. No spaces or newlines are inserted between the output strings. No newline is added after the last output string. @@ -380,7 +379,7 @@ Accept wildcard characters: False ### -PassThru -Returns an object representing the added content. By default, this cmdlet does not generate any +Returns an object representing the added content. By default, this cmdlet doesn't generate any output. ```yaml @@ -419,14 +418,14 @@ Accept wildcard characters: True > [!NOTE] > This Parameter is only available on Windows. -Specifies an alternative data stream for content. If the stream does not exist, this cmdlet creates -it. Wildcard characters are not supported. +Specifies an alternative data stream for content. If the stream doesn't exist, this cmdlet creates +it. Wildcard characters aren't supported. **Stream** is a dynamic parameter that the FileSystem provider adds to `Add-Content`. This parameter works only in file system drives. You can use the `Add-Content` cmdlet to change the content of any alternate data stream, such as -`Zone.Identifier`. However, we do not recommend this as a way to eliminate security checks that +`Zone.Identifier`. However, we don't recommend this as a way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the `Unblock-File` cmdlet. @@ -452,7 +451,7 @@ Specifies the content to be added. Type a quoted string, such as **This data is only**, or specify an object that contains content, such as the **DateTime** object that `Get-Date` generates. -You cannot specify the contents of a file by typing its path, because the path is just a string. +You can't specify the contents of a file by typing its path, because the path is just a string. You can use a `Get-Content` command to get the content and pass it to the **Value** parameter. ```yaml @@ -485,7 +484,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: System.Management.Automation.SwitchParameter @@ -534,7 +533,7 @@ PowerShell includes the following aliases for `Add-Content`: - Windows: - `ac` -- When you pipe an object to `Add-Content`, the object is converted to a string before it is added +- When you pipe an object to `Add-Content`, the object is converted to a string before it's added to the item. The object type determines the string format, but the format might be different than the default display of the object. To control the string format, use the formatting parameters of the sending cmdlet. From 075cbf1c6319a737486b9d0a74a656f2f4143c40 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 31 Oct 2023 13:43:39 -0500 Subject: [PATCH 2/2] Fixes #10569 - Refactor descriptions of syntax (#10602) * Refactor descriptions of syntax * Copy changes to all versions --- .../About/about_Command_Syntax.md | 332 ++++++++--------- .../About/about_Command_Syntax.md | 333 ++++++++---------- .../About/about_Command_Syntax.md | 333 ++++++++---------- .../About/about_Command_Syntax.md | 333 ++++++++---------- 4 files changed, 602 insertions(+), 729 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Command_Syntax.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Command_Syntax.md index 64cc5c1b8dc6..1eab5b9869ef 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Command_Syntax.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Command_Syntax.md @@ -1,7 +1,7 @@ --- description: Describes the syntax diagrams that are used in PowerShell. Locale: en-US -ms.date: 05/30/2023 +ms.date: 10/31/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_command_syntax?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Command Syntax @@ -14,109 +14,96 @@ Describes the syntax diagrams that are used in PowerShell. ## Long description The [Get-Help][03] and [Get-Command][02] cmdlets display syntax diagrams to -help you construct commands correctly. This topic explains how to interpret the -syntax diagrams. +help you construct commands correctly. This article explains how to interpret +the syntax diagrams. -## SYNTAX DIAGRAMS +## Get the syntax for a command -Each paragraph in a command syntax diagram represents a valid form of the -command. +There are two ways to get the syntax for a command: `Get-Help` and +`Get-Command`. -To construct a command, follow the syntax diagram from left to right. Select -from among the optional parameters and provide values for the placeholders. +### Get-Command -PowerShell uses the following notation for syntax diagrams. +The `Get-Command` command can be used to get information about any command on +your system. Use the **Syntax** parameter to get the syntax for a command. -```Syntax - - - [- ] - [-] - [-] +```powershell +Get-Command Get-Command -Syntax ``` -`Get-Help` shows the following syntax for the [New-Alias][06] cmdlet. - -```Syntax -New-Alias [-Name] [-Value] [-Description ] [-Force] - [-Option {None | ReadOnly | Constant | Private | AllScope | Unspecified}] - [-PassThru] [-Scope ] [-Confirm] [-WhatIf] [] +```Output +Get-Command [[-ArgumentList] ] [-Verb ] [-Noun ] + [-Module ] [-FullyQualifiedModule ] + [-TotalCount ] [-Syntax] [-ShowCommandInfo] [-All] [-ListImported] + [-ParameterName ] [-ParameterType ] + [] + +Get-Command [[-Name] ] [[-ArgumentList] ] + [-Module ] [-FullyQualifiedModule ] + [-CommandType ] [-TotalCount ] [-Syntax] [-ShowCommandInfo] + [-All] [-ListImported] [-ParameterName ] + [-ParameterType ] [-UseFuzzyMatching] + [-FuzzyMinimumDistance ] [-UseAbbreviationExpansion] + [] ``` -The syntax is capitalized for readability, but PowerShell is case-insensitive. - -The syntax diagram has the following elements. - -## Command name - -Commands always begin with a command name, such as `New-Alias`. Type the -command name or its alias, such a "gcm" for `Get-Command`. - -## Parameters - -The parameters of a command are options that determine what the command does. -Some parameters take a value as user input to the command. - -For example, the `Get-Help` command has a **Name** parameter that lets you -specify the name of the topic for which help is displayed. The topic name is -the value of the **Name** parameter. - -In a PowerShell command, parameter names always begin with a hyphen. The hyphen -tells PowerShell that the item in the command is a parameter name. +### Get-Help -For example, to use the **Name** parameter of `New-Alias`, you type the -following: `New-Alias -Name` +The `Get-Help` command provides detailed information about PowerShell commands +including, syntax, detailed description of the cmdlet and parameters, and +examples. The output `Get-Help` command starts with a brief description of the +command followed by the syntax. -Parameters can be mandatory or optional. In a syntax diagram, optional items -are enclosed in brackets `[]`. - -For more information about parameters, see [about_Parameters][01]. - -## Parameter Values - -A parameter value is the input that the parameter takes. Because Windows -PowerShell is based on the Microsoft .NET Framework, parameter values are -represented in the syntax diagram by their .NET type. - -For example, the Name parameter of `Get-Help` takes a "String" value, which is -a text string, such as a single word or multiple words enclosed in quotation -marks. - -```Syntax -New-Alias [-Name] +```powershell +Get-Help Get-Command ``` -The .NET type of a parameter value is enclosed in angle brackets `<>` to -indicate that it's placeholder for a value and not a literal that you type in a -command. - -To use the parameter, replace the .NET type placeholder with an object that has -the specified .NET type. - -For example, to use the **Name** parameter, type `-Name` followed by a string, -such as the following: `-Name MyAlias` - -## Parameters with no values - -Some parameters don't accept input, so they don't have a parameter value. -Parameters without values are called _switch parameters_ because they work like -on/off switches. You include them (on) or you omit them (off) from a command. +The following output has been shortened to focus on the syntax description. -To use a switch parameter, just type the parameter name, preceded by a hyphen. +```Output +NAME + Get-Command + +SYNOPSIS + Gets all commands. + +SYNTAX + + Get-Command [[-Name] ] [[-ArgumentList] ] + [-All] [-CommandType {Alias | Function | Filter | Cmdlet | ExternalScript | + Application | Script | Workflow | Configuration | All}] + [-FullyQualifiedModule ] + [-ListImported] [-Module ] [-ParameterName ] + [-ParameterType ] + [-ShowCommandInfo] [-Syntax] [-TotalCount ] + [-UseAbbreviationExpansion] [-UseFuzzyMatching] [] + + Get-Command [[-ArgumentList] ] [-All] + [-FullyQualifiedModule ] + [-ListImported] [-Module ] [-Noun ] + [-ParameterName ] + [-ParameterType ] + [-ShowCommandInfo] [-Syntax] [-TotalCount ] + [-Verb ] [] +... +``` -For example, to use the **WhatIf** parameter of the `New-Alias` cmdlet, type -the following: `New-Alias -WhatIf`. +The output of `Get-Help` is slightly different from the output of +`Get-Command`. Notice the difference in the syntax for the **CommandType** +parameter. `Get-Command` shows the parameter type as the `[CommandTypes]` +enumeration, while `Get-Help` show the possible values for the enumeration. ## Parameter Sets -The parameters of a command are listed in parameter sets. Parameter sets look -like the paragraphs of a syntax diagram. +The parameters of a PowerShell command are listed in parameter sets. A +PowerShell command can have one or more parameter sets. The `Get-Command` +cmdlet has two parameter sets, as shown in the previous examples. -The `New-Alias` cmdlet has one parameter set, but many cmdlets have multiple -parameter sets. Some of the cmdlet parameters are unique to a parameter set, -and others appear in multiple parameter sets. Each parameter set represents the -format of a valid command. A parameter set includes only parameters that can be -used together in a command. If parameters can't be used in the same command, -they appear in separate parameter sets. +Some of the cmdlet parameters are unique to a parameter set, and others appear +in multiple parameter sets. Each parameter set represents the format for a +valid command. A parameter set includes only parameters that can be used +together in a command. When parameters can't be used in the same command, they +are listed in separate parameter sets. For example, the [Get-Random][05] cmdlet has the following parameter sets: @@ -131,33 +118,36 @@ $cmd.ParameterSets | Name IsDefault Parameters ---- --------- ---------- RandomNumberParameterSet True [[-Maximum] ] [-SetSeed ] - [-Minimum ] [] + [-Minimum ] [-Count ] + [] RandomListItemParameterSet False [-InputObject] [-SetSeed ] [-Count ] [] +ShuffleParameterSet False [-InputObject] -Shuffle + [-SetSeed ] [] ``` -The first parameter set returns one or more random numbers and has the -**Minimum** and **Maximum** parameters. The second parameter set returns a -randomly selected object from a set of objects and includes the **InputObject** -and **Count** parameters. All parameter sets have the **SetSeed** parameter and -the common parameters. +- The first parameter set returns one or more random numbers and has the + **Minimum**, **Maximum**, and **Count** parameters. +- The second parameter set returns a randomly selected object from a set of + objects and includes the **InputObject** and **Count** parameters. +- The third parameter set has the **Shuffle** parameter that returns a + collection of objects in a random order, like shuffling a deck of cards. +- All parameter sets have the **SetSeed** parameter and the common parameters. -These parameter sets indicate that you can use the **InputObject** and -**Count** parameters in the same command, but you can't use the **Maximum** and -**Count** parameters in the same command. +These parameter sets show that you can use the **InputObject** and **Count** +parameters in the same command, but you can't use the **Maximum** and +**Shuffle** parameters together. -You indicate which parameter set you want to use by using the parameters in -that parameter set. However, every cmdlet also has a default parameter set. The -default parameter set is used when you don't specify parameters that are unique -to a parameter set. For example, if you use `Get-Random` without parameters, -Windows PowerShell assumes that you are using the **RandomNumberParameterSet** -parameter set and it returns a random number. +Every cmdlet also has a default parameter set. The default parameter set is +used when you don't specify parameters that are unique to a parameter set. For +example, if you use `Get-Random` without parameters, PowerShell assumes that +you're using the **RandomNumberParameterSet** parameter set and it returns a +random number. ## Symbols in Syntax Diagrams The syntax diagram lists the command name, the command parameters, and the -parameter values. It also uses symbols to show how to construct a valid -command. +parameter values. The syntax diagrams use the following symbols: @@ -165,46 +155,33 @@ The syntax diagrams use the following symbols: immediately before the parameter name with no intervening spaces, as shown in the syntax diagram. - For example, to use the **Name** parameter of `New-Alias`, type: - `New-Alias -Name`. + For example, to use the **Name** parameter of `Get-Command`, type: + `Get-Command -Name`. -- Angle brackets `<>` indicate placeholder text. You don't type the angle + +- Angle brackets `< >` indicate placeholder text. You don't type the angle brackets or the placeholder text in a command. Instead, you replace it with the item that it describes. The placeholder inside the angle brackets identifies the .NET type of the value that a parameter takes. For example, to use the **Name** parameter of - the `New-Alias` cmdlet, you replace the `` with a string, which is a - single word or a group of words that are enclosed in quotation marks. - -- Brackets `[]` around parameters indicate optional items. A parameter and its - value can be optional, or the name of a required parameter can be optional. - - For example, the **Description** parameter of `New-Alias` and its value are - enclosed in brackets because they're both optional. - - The brackets also indicate that the value of the **Name** parameter is - required, but the parameter name, `-Name`, is optional. - - In each parameter set, the parameters appear in position order. The order of - parameters in a command matters only when you omit the optional parameter - names. When parameter names are omitted, PowerShell assigns values to - parameters by position and type. For more information about parameter - position, see [about_Parameters][01]. + the `Get-Command ` cmdlet, you replace the `` with one or more + strings separated by commas (`,`). + - Brackets `[]` appended to a .NET type indicate that the parameter can accept one or more values of that type. Enter the values as a comma-separated list. - For example, the **Name** parameter of the `New-Alias` cmdlet takes only one - string. + For example, the **Name** and **Value** parameters of the `New-Alias` cmdlet + only take one string each. ```Syntax - New-Alias [-Name] + New-Alias [-Name] [-Value] ``` ```powershell - New-Alias -Name MyAlias + New-Alias -Name MyAlias -Value mycommand.exe ``` But the **Name** parameter of [Get-Process][04] can take one or more strings. @@ -217,78 +194,74 @@ The syntax diagrams use the following symbols: Get-Process -Name Explorer, Winlogon, Services ``` -- Braces `{}` indicate an "enumeration," which is a set of valid values for a - parameter. +- Parameters with no values - The values in the braces are separated by vertical bars `|`. These bars - indicate an _exclusive-OR_ choice, meaning that you can choose only one value - from the set of values that are listed inside the braces. + Some parameters don't accept input, so they don't have a parameter value. + Parameters without values are _switch parameters_. Switch parameters are used + like boolean values. They default to `$false`. When you use a switch + parameter, the value is set to `$true`. - For example, the syntax for the `New-Alias` cmdlet includes the following - value enumeration for the **Option** parameter: + For example, the **ListImported** parameter of `Get-Command` is a switch + parameter. When you use the **ListImported** parameter, the cmdlet return + only commands that were imported from modules in the current session. ```Syntax - New-Alias -Option {None | ReadOnly | Constant | Private | AllScope} + Get-Command [-ListImported] ``` - The braces and vertical bars indicate that you can choose any one of the - listed values for the **Option** parameter, such as "ReadOnly" or "AllScope". + +- Brackets `[ ]` around parameters indicate optional items. A parameter and + its value can be optional. For example, the **CommandType** parameter of + `Get-Command` and its value are enclosed in brackets because they're both + optional. - ```powershell - New-Alias -Option ReadOnly + ```Syntax + Get-Command [-CommandType ] ``` -## Optional Items - -Brackets `[]` surround optional items. For example, in the `New-Alias` cmdlet -syntax description, the **Scope** parameter is optional. This is indicated in -the syntax by the brackets around the parameter name and type: + Brackets around the parameter name, but not the parameter value, indicate + that the parameter name is optional. These parameters are known as positional + parameters. The parameter values must be presented in the correct order for + the values to be bound to the correct parameter. -```powershell -New-Alias [-Scope ] -``` - -Both the following examples are correct uses of the `New-Alias` cmdlet: - -```powershell -New-Alias -Name utd -Value Update-TypeData -New-Alias -Name utd -Value Update-TypeData -Scope Global -``` + For example, for the `New-Alias` cmdlet, the **Name** and **Value** parameter + values are required, but the parameter names, `-Name` and `-Value`, are + optional. -A parameter name can be optional even if the value for that parameter is -required. This is indicated in the syntax by the brackets around the parameter -name but not the parameter type, as in this example from the `New-Alias` -cmdlet: + ```Syntax + New-Alias [-Name] [-Value] + ``` -```Syntax -New-Alias [-Name] [-Value] -``` + ```powershell + New-Alias MyAlias mycommand.exe + ``` -The following commands correctly use the `New-Alias` cmdlet. The commands -produce the same result. + In each parameter set, the parameters appear in position order. The order of + parameters in a command matters only when you omit the optional parameter + names. When parameter names are omitted, PowerShell assigns values to + parameters by position and type. For more information about parameter + position, see [about_Parameters][01]. -```powershell -New-Alias -Name utd -Value Update-TypeData -New-Alias -Name utd Update-TypeData -New-Alias utd -Value Update-TypeData -New-Alias utd Update-TypeData -``` +- Braces `{}` indicate an "enumeration," which is a set of valid values for a + parameter. -If the parameter name isn't included in the statement as typed, Windows -PowerShell tries to use the position of the arguments to assign the values to -parameters. + The values in the braces are separated by vertical bars `|`. These bars + indicate an _exclusive-OR_ choice, meaning that you can choose only one value + from the set of values that are listed inside the braces. -The following example isn't complete: + For example, the syntax for the `New-Alias` cmdlet includes the following + value enumeration for the **Option** parameter: -```powershell -New-Alias utd -``` + ```Syntax + New-Alias -Option {None | ReadOnly | Constant | Private | AllScope} + ``` -This cmdlet requires values for both the **Name** and **Value** parameters. + The braces and vertical bars indicate that you can choose any one of the + listed values for the **Option** parameter, such as `ReadOnly` or `AllScope`. -In syntax examples, brackets are also used in naming and casting to .NET -Framework types. In this context, brackets don't indicate an element is -optional. + ```powershell + New-Alias -Option ReadOnly + ``` ## See also @@ -302,4 +275,3 @@ optional. [03]: xref:Microsoft.PowerShell.Core.Get-Help [04]: xref:Microsoft.PowerShell.Management.Get-Process [05]: xref:Microsoft.PowerShell.Utility.Get-Random -[06]: xref:Microsoft.PowerShell.Utility.New-Alias diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Command_Syntax.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Command_Syntax.md index 1949616545db..d9676819550f 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Command_Syntax.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Command_Syntax.md @@ -1,7 +1,7 @@ --- description: Describes the syntax diagrams that are used in PowerShell. Locale: en-US -ms.date: 05/30/2023 +ms.date: 10/31/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_command_syntax?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Command Syntax @@ -14,109 +14,96 @@ Describes the syntax diagrams that are used in PowerShell. ## Long description The [Get-Help][03] and [Get-Command][02] cmdlets display syntax diagrams to -help you construct commands correctly. This topic explains how to interpret the -syntax diagrams. +help you construct commands correctly. This article explains how to interpret +the syntax diagrams. -## SYNTAX DIAGRAMS +## Get the syntax for a command -Each paragraph in a command syntax diagram represents a valid form of the -command. +There are two ways to get the syntax for a command: `Get-Help` and +`Get-Command`. -To construct a command, follow the syntax diagram from left to right. Select -from among the optional parameters and provide values for the placeholders. +### Get-Command -PowerShell uses the following notation for syntax diagrams. +The `Get-Command` command can be used to get information about any command on +your system. Use the **Syntax** parameter to get the syntax for a command. -```Syntax - - - [- ] - [-] - [-] +```powershell +Get-Command Get-Command -Syntax ``` -`Get-Help` shows the following syntax for the [New-Alias][06] cmdlet. - -```Syntax -New-Alias [-Name] [-Value] [-Description ] [-Force] - [-Option {None | ReadOnly | Constant | Private | AllScope | Unspecified}] - [-PassThru] [-Scope ] [-Confirm] [-WhatIf] [] +```Output +Get-Command [[-ArgumentList] ] [-Verb ] [-Noun ] + [-Module ] [-FullyQualifiedModule ] + [-TotalCount ] [-Syntax] [-ShowCommandInfo] [-All] [-ListImported] + [-ParameterName ] [-ParameterType ] + [] + +Get-Command [[-Name] ] [[-ArgumentList] ] + [-Module ] [-FullyQualifiedModule ] + [-CommandType ] [-TotalCount ] [-Syntax] [-ShowCommandInfo] + [-All] [-ListImported] [-ParameterName ] + [-ParameterType ] [-UseFuzzyMatching] + [-FuzzyMinimumDistance ] [-UseAbbreviationExpansion] + [] ``` -The syntax is capitalized for readability, but PowerShell is case-insensitive. - -The syntax diagram has the following elements. - -## Command name - -Commands always begin with a command name, such as `New-Alias`. Type the -command name or its alias, such a "gcm" for `Get-Command`. - -## Parameters - -The parameters of a command are options that determine what the command does. -Some parameters take a value as user input to the command. - -For example, the `Get-Help` command has a **Name** parameter that lets you -specify the name of the topic for which help is displayed. The topic name is -the value of the **Name** parameter. - -In a PowerShell command, parameter names always begin with a hyphen. The hyphen -tells PowerShell that the item in the command is a parameter name. +### Get-Help -For example, to use the **Name** parameter of `New-Alias`, you type the -following: `New-Alias -Name` +The `Get-Help` command provides detailed information about PowerShell commands +including, syntax, detailed description of the cmdlet and parameters, and +examples. The output `Get-Help` command starts with a brief description of the +command followed by the syntax. -Parameters can be mandatory or optional. In a syntax diagram, optional items -are enclosed in brackets `[]`. - -For more information about parameters, see [about_Parameters][01]. - -## Parameter Values - -A parameter value is the input that the parameter takes. Because Windows -PowerShell is based on the Microsoft .NET Framework, parameter values are -represented in the syntax diagram by their .NET type. - -For example, the Name parameter of `Get-Help` takes a "String" value, which is -a text string, such as a single word or multiple words enclosed in quotation -marks. - -```Syntax -New-Alias [-Name] +```powershell +Get-Help Get-Command ``` -The .NET type of a parameter value is enclosed in angle brackets `<>` to -indicate that it's placeholder for a value and not a literal that you type in a -command. - -To use the parameter, replace the .NET type placeholder with an object that has -the specified .NET type. - -For example, to use the **Name** parameter, type `-Name` followed by a string, -such as the following: `-Name MyAlias` - -## Parameters with no values - -Some parameters don't accept input, so they don't have a parameter value. -Parameters without values are called _switch parameters_ because they work like -on/off switches. You include them (on) or you omit them (off) from a command. +The following output has been shortened to focus on the syntax description. -To use a switch parameter, just type the parameter name, preceded by a hyphen. +```Output +NAME + Get-Command + +SYNOPSIS + Gets all commands. + +SYNTAX + + Get-Command [[-Name] ] [[-ArgumentList] ] + [-All] [-CommandType {Alias | Function | Filter | Cmdlet | ExternalScript | + Application | Script | Workflow | Configuration | All}] + [-FullyQualifiedModule ] + [-ListImported] [-Module ] [-ParameterName ] + [-ParameterType ] + [-ShowCommandInfo] [-Syntax] [-TotalCount ] + [-UseAbbreviationExpansion] [-UseFuzzyMatching] [] + + Get-Command [[-ArgumentList] ] [-All] + [-FullyQualifiedModule ] + [-ListImported] [-Module ] [-Noun ] + [-ParameterName ] + [-ParameterType ] + [-ShowCommandInfo] [-Syntax] [-TotalCount ] + [-Verb ] [] +... +``` -For example, to use the **WhatIf** parameter of the `New-Alias` cmdlet, type -the following: `New-Alias -WhatIf`. +The output of `Get-Help` is slightly different from the output of +`Get-Command`. Notice the difference in the syntax for the **CommandType** +parameter. `Get-Command` shows the parameter type as the `[CommandTypes]` +enumeration, while `Get-Help` show the possible values for the enumeration. ## Parameter Sets -The parameters of a command are listed in parameter sets. Parameter sets look -like the paragraphs of a syntax diagram. +The parameters of a PowerShell command are listed in parameter sets. A +PowerShell command can have one or more parameter sets. The `Get-Command` +cmdlet has two parameter sets, as shown in the previous examples. -The `New-Alias` cmdlet has one parameter set, but many cmdlets have multiple -parameter sets. Some of the cmdlet parameters are unique to a parameter set, -and others appear in multiple parameter sets. Each parameter set represents the -format of a valid command. A parameter set includes only parameters that can be -used together in a command. If parameters can't be used in the same command, -they appear in separate parameter sets. +Some of the cmdlet parameters are unique to a parameter set, and others appear +in multiple parameter sets. Each parameter set represents the format for a +valid command. A parameter set includes only parameters that can be used +together in a command. When parameters can't be used in the same command, they +are listed in separate parameter sets. For example, the [Get-Random][05] cmdlet has the following parameter sets: @@ -139,30 +126,28 @@ ShuffleParameterSet False [-InputObject] -Shuffle [-SetSeed ] [] ``` -The first parameter set returns one or more random numbers and has the -**Minimum**, **Maximum**, and **Count** parameters. The second parameter set -returns a randomly selected object from a set of objects and includes the -**InputObject** and **Count** parameters. The third parameter set has the -**Shuffle** parameters that returns a collection of objects in a random order, -like shuffling a deck of cards. All parameter sets have the **SetSeed** -parameter and the common parameters. - -These parameter sets indicate that you can use the **InputObject** and -**Count** parameters in the same command, but you can't use the **Maximum** and -**Shuffle** parameters in the same command. - -You indicate which parameter set you want to use by using the parameters in -that parameter set. However, every cmdlet also has a default parameter set. The -default parameter set is used when you don't specify parameters that are unique -to a parameter set. For example, if you use `Get-Random` without parameters, -Windows PowerShell assumes that you are using the **RandomNumberParameterSet** -parameter set and it returns a random number. +- The first parameter set returns one or more random numbers and has the + **Minimum**, **Maximum**, and **Count** parameters. +- The second parameter set returns a randomly selected object from a set of + objects and includes the **InputObject** and **Count** parameters. +- The third parameter set has the **Shuffle** parameter that returns a + collection of objects in a random order, like shuffling a deck of cards. +- All parameter sets have the **SetSeed** parameter and the common parameters. + +These parameter sets show that you can use the **InputObject** and **Count** +parameters in the same command, but you can't use the **Maximum** and +**Shuffle** parameters together. + +Every cmdlet also has a default parameter set. The default parameter set is +used when you don't specify parameters that are unique to a parameter set. For +example, if you use `Get-Random` without parameters, PowerShell assumes that +you're using the **RandomNumberParameterSet** parameter set and it returns a +random number. ## Symbols in Syntax Diagrams The syntax diagram lists the command name, the command parameters, and the -parameter values. It also uses symbols to show how to construct a valid -command. +parameter values. The syntax diagrams use the following symbols: @@ -170,46 +155,33 @@ The syntax diagrams use the following symbols: immediately before the parameter name with no intervening spaces, as shown in the syntax diagram. - For example, to use the **Name** parameter of `New-Alias`, type: - `New-Alias -Name`. + For example, to use the **Name** parameter of `Get-Command`, type: + `Get-Command -Name`. -- Angle brackets `<>` indicate placeholder text. You don't type the angle + +- Angle brackets `< >` indicate placeholder text. You don't type the angle brackets or the placeholder text in a command. Instead, you replace it with the item that it describes. The placeholder inside the angle brackets identifies the .NET type of the value that a parameter takes. For example, to use the **Name** parameter of - the `New-Alias` cmdlet, you replace the `` with a string, which is a - single word or a group of words that are enclosed in quotation marks. - -- Brackets `[]` around parameters indicate optional items. A parameter and its - value can be optional, or the name of a required parameter can be optional. - - For example, the **Description** parameter of `New-Alias` and its value are - enclosed in brackets because they're both optional. - - The brackets also indicate that the value of the **Name** parameter is - required, but the parameter name, `-Name`, is optional. - - In each parameter set, the parameters appear in position order. The order of - parameters in a command matters only when you omit the optional parameter - names. When parameter names are omitted, PowerShell assigns values to - parameters by position and type. For more information about parameter - position, see [about_Parameters][01]. + the `Get-Command ` cmdlet, you replace the `` with one or more + strings separated by commas (`,`). + - Brackets `[]` appended to a .NET type indicate that the parameter can accept one or more values of that type. Enter the values as a comma-separated list. - For example, the **Name** parameter of the `New-Alias` cmdlet takes only one - string. + For example, the **Name** and **Value** parameters of the `New-Alias` cmdlet + only take one string each. ```Syntax - New-Alias [-Name] + New-Alias [-Name] [-Value] ``` ```powershell - New-Alias -Name MyAlias + New-Alias -Name MyAlias -Value mycommand.exe ``` But the **Name** parameter of [Get-Process][04] can take one or more strings. @@ -222,78 +194,74 @@ The syntax diagrams use the following symbols: Get-Process -Name Explorer, Winlogon, Services ``` -- Braces `{}` indicate an "enumeration," which is a set of valid values for a - parameter. +- Parameters with no values - The values in the braces are separated by vertical bars `|`. These bars - indicate an _exclusive-OR_ choice, meaning that you can choose only one value - from the set of values that are listed inside the braces. + Some parameters don't accept input, so they don't have a parameter value. + Parameters without values are _switch parameters_. Switch parameters are used + like boolean values. They default to `$false`. When you use a switch + parameter, the value is set to `$true`. - For example, the syntax for the `New-Alias` cmdlet includes the following - value enumeration for the **Option** parameter: + For example, the **ListImported** parameter of `Get-Command` is a switch + parameter. When you use the **ListImported** parameter, the cmdlet return + only commands that were imported from modules in the current session. ```Syntax - New-Alias -Option {None | ReadOnly | Constant | Private | AllScope} + Get-Command [-ListImported] ``` - The braces and vertical bars indicate that you can choose any one of the - listed values for the **Option** parameter, such as "ReadOnly" or "AllScope". + +- Brackets `[ ]` around parameters indicate optional items. A parameter and + its value can be optional. For example, the **CommandType** parameter of + `Get-Command` and its value are enclosed in brackets because they're both + optional. - ```powershell - New-Alias -Option ReadOnly + ```Syntax + Get-Command [-CommandType ] ``` -## Optional Items - -Brackets `[]` surround optional items. For example, in the `New-Alias` cmdlet -syntax description, the **Scope** parameter is optional. This is indicated in -the syntax by the brackets around the parameter name and type: - -```powershell -New-Alias [-Scope ] -``` - -Both the following examples are correct uses of the `New-Alias` cmdlet: + Brackets around the parameter name, but not the parameter value, indicate + that the parameter name is optional. These parameters are known as positional + parameters. The parameter values must be presented in the correct order for + the values to be bound to the correct parameter. -```powershell -New-Alias -Name utd -Value Update-TypeData -New-Alias -Name utd -Value Update-TypeData -Scope Global -``` + For example, for the `New-Alias` cmdlet, the **Name** and **Value** parameter + values are required, but the parameter names, `-Name` and `-Value`, are + optional. -A parameter name can be optional even if the value for that parameter is -required. This is indicated in the syntax by the brackets around the parameter -name but not the parameter type, as in this example from the `New-Alias` -cmdlet: + ```Syntax + New-Alias [-Name] [-Value] + ``` -```Syntax -New-Alias [-Name] [-Value] -``` + ```powershell + New-Alias MyAlias mycommand.exe + ``` -The following commands correctly use the `New-Alias` cmdlet. The commands -produce the same result. + In each parameter set, the parameters appear in position order. The order of + parameters in a command matters only when you omit the optional parameter + names. When parameter names are omitted, PowerShell assigns values to + parameters by position and type. For more information about parameter + position, see [about_Parameters][01]. -```powershell -New-Alias -Name utd -Value Update-TypeData -New-Alias -Name utd Update-TypeData -New-Alias utd -Value Update-TypeData -New-Alias utd Update-TypeData -``` +- Braces `{}` indicate an "enumeration," which is a set of valid values for a + parameter. -If the parameter name isn't included in the statement as typed, Windows -PowerShell tries to use the position of the arguments to assign the values to -parameters. + The values in the braces are separated by vertical bars `|`. These bars + indicate an _exclusive-OR_ choice, meaning that you can choose only one value + from the set of values that are listed inside the braces. -The following example isn't complete: + For example, the syntax for the `New-Alias` cmdlet includes the following + value enumeration for the **Option** parameter: -```powershell -New-Alias utd -``` + ```Syntax + New-Alias -Option {None | ReadOnly | Constant | Private | AllScope} + ``` -This cmdlet requires values for both the **Name** and **Value** parameters. + The braces and vertical bars indicate that you can choose any one of the + listed values for the **Option** parameter, such as `ReadOnly` or `AllScope`. -In syntax examples, brackets are also used in naming and casting to .NET -Framework types. In this context, brackets don't indicate an element is -optional. + ```powershell + New-Alias -Option ReadOnly + ``` ## See also @@ -307,4 +275,3 @@ optional. [03]: xref:Microsoft.PowerShell.Core.Get-Help [04]: xref:Microsoft.PowerShell.Management.Get-Process [05]: xref:Microsoft.PowerShell.Utility.Get-Random -[06]: xref:Microsoft.PowerShell.Utility.New-Alias diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Command_Syntax.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Command_Syntax.md index f572385d0d81..0a6456a03a08 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Command_Syntax.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Command_Syntax.md @@ -1,7 +1,7 @@ --- description: Describes the syntax diagrams that are used in PowerShell. Locale: en-US -ms.date: 05/30/2023 +ms.date: 10/31/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_command_syntax?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Command Syntax @@ -14,109 +14,96 @@ Describes the syntax diagrams that are used in PowerShell. ## Long description The [Get-Help][03] and [Get-Command][02] cmdlets display syntax diagrams to -help you construct commands correctly. This topic explains how to interpret the -syntax diagrams. +help you construct commands correctly. This article explains how to interpret +the syntax diagrams. -## SYNTAX DIAGRAMS +## Get the syntax for a command -Each paragraph in a command syntax diagram represents a valid form of the -command. +There are two ways to get the syntax for a command: `Get-Help` and +`Get-Command`. -To construct a command, follow the syntax diagram from left to right. Select -from among the optional parameters and provide values for the placeholders. +### Get-Command -PowerShell uses the following notation for syntax diagrams. +The `Get-Command` command can be used to get information about any command on +your system. Use the **Syntax** parameter to get the syntax for a command. -```Syntax - - - [- ] - [-] - [-] +```powershell +Get-Command Get-Command -Syntax ``` -`Get-Help` shows the following syntax for the [New-Alias][06] cmdlet. - -```Syntax -New-Alias [-Name] [-Value] [-Description ] [-Force] - [-Option {None | ReadOnly | Constant | Private | AllScope | Unspecified}] - [-PassThru] [-Scope ] [-Confirm] [-WhatIf] [] +```Output +Get-Command [[-ArgumentList] ] [-Verb ] [-Noun ] + [-Module ] [-FullyQualifiedModule ] + [-TotalCount ] [-Syntax] [-ShowCommandInfo] [-All] [-ListImported] + [-ParameterName ] [-ParameterType ] + [] + +Get-Command [[-Name] ] [[-ArgumentList] ] + [-Module ] [-FullyQualifiedModule ] + [-CommandType ] [-TotalCount ] [-Syntax] [-ShowCommandInfo] + [-All] [-ListImported] [-ParameterName ] + [-ParameterType ] [-UseFuzzyMatching] + [-FuzzyMinimumDistance ] [-UseAbbreviationExpansion] + [] ``` -The syntax is capitalized for readability, but PowerShell is case-insensitive. - -The syntax diagram has the following elements. - -## Command name - -Commands always begin with a command name, such as `New-Alias`. Type the -command name or its alias, such a "gcm" for `Get-Command`. - -## Parameters - -The parameters of a command are options that determine what the command does. -Some parameters take a value as user input to the command. - -For example, the `Get-Help` command has a **Name** parameter that lets you -specify the name of the topic for which help is displayed. The topic name is -the value of the **Name** parameter. - -In a PowerShell command, parameter names always begin with a hyphen. The hyphen -tells PowerShell that the item in the command is a parameter name. +### Get-Help -For example, to use the **Name** parameter of `New-Alias`, you type the -following: `New-Alias -Name` +The `Get-Help` command provides detailed information about PowerShell commands +including, syntax, detailed description of the cmdlet and parameters, and +examples. The output `Get-Help` command starts with a brief description of the +command followed by the syntax. -Parameters can be mandatory or optional. In a syntax diagram, optional items -are enclosed in brackets `[]`. - -For more information about parameters, see [about_Parameters][01]. - -## Parameter Values - -A parameter value is the input that the parameter takes. Because Windows -PowerShell is based on the Microsoft .NET Framework, parameter values are -represented in the syntax diagram by their .NET type. - -For example, the Name parameter of `Get-Help` takes a "String" value, which is -a text string, such as a single word or multiple words enclosed in quotation -marks. - -```Syntax -New-Alias [-Name] +```powershell +Get-Help Get-Command ``` -The .NET type of a parameter value is enclosed in angle brackets `<>` to -indicate that it's placeholder for a value and not a literal that you type in a -command. - -To use the parameter, replace the .NET type placeholder with an object that has -the specified .NET type. - -For example, to use the **Name** parameter, type `-Name` followed by a string, -such as the following: `-Name MyAlias` - -## Parameters with no values - -Some parameters don't accept input, so they don't have a parameter value. -Parameters without values are called _switch parameters_ because they work like -on/off switches. You include them (on) or you omit them (off) from a command. +The following output has been shortened to focus on the syntax description. -To use a switch parameter, just type the parameter name, preceded by a hyphen. +```Output +NAME + Get-Command + +SYNOPSIS + Gets all commands. + +SYNTAX + + Get-Command [[-Name] ] [[-ArgumentList] ] + [-All] [-CommandType {Alias | Function | Filter | Cmdlet | ExternalScript | + Application | Script | Workflow | Configuration | All}] + [-FullyQualifiedModule ] + [-ListImported] [-Module ] [-ParameterName ] + [-ParameterType ] + [-ShowCommandInfo] [-Syntax] [-TotalCount ] + [-UseAbbreviationExpansion] [-UseFuzzyMatching] [] + + Get-Command [[-ArgumentList] ] [-All] + [-FullyQualifiedModule ] + [-ListImported] [-Module ] [-Noun ] + [-ParameterName ] + [-ParameterType ] + [-ShowCommandInfo] [-Syntax] [-TotalCount ] + [-Verb ] [] +... +``` -For example, to use the **WhatIf** parameter of the `New-Alias` cmdlet, type -the following: `New-Alias -WhatIf`. +The output of `Get-Help` is slightly different from the output of +`Get-Command`. Notice the difference in the syntax for the **CommandType** +parameter. `Get-Command` shows the parameter type as the `[CommandTypes]` +enumeration, while `Get-Help` show the possible values for the enumeration. ## Parameter Sets -The parameters of a command are listed in parameter sets. Parameter sets look -like the paragraphs of a syntax diagram. +The parameters of a PowerShell command are listed in parameter sets. A +PowerShell command can have one or more parameter sets. The `Get-Command` +cmdlet has two parameter sets, as shown in the previous examples. -The `New-Alias` cmdlet has one parameter set, but many cmdlets have multiple -parameter sets. Some of the cmdlet parameters are unique to a parameter set, -and others appear in multiple parameter sets. Each parameter set represents the -format of a valid command. A parameter set includes only parameters that can be -used together in a command. If parameters can't be used in the same command, -they appear in separate parameter sets. +Some of the cmdlet parameters are unique to a parameter set, and others appear +in multiple parameter sets. Each parameter set represents the format for a +valid command. A parameter set includes only parameters that can be used +together in a command. When parameters can't be used in the same command, they +are listed in separate parameter sets. For example, the [Get-Random][05] cmdlet has the following parameter sets: @@ -139,30 +126,28 @@ ShuffleParameterSet False [-InputObject] -Shuffle [-SetSeed ] [] ``` -The first parameter set returns one or more random numbers and has the -**Minimum**, **Maximum**, and **Count** parameters. The second parameter set -returns a randomly selected object from a set of objects and includes the -**InputObject** and **Count** parameters. The third parameter set has the -**Shuffle** parameters that returns a collection of objects in a random order, -like shuffling a deck of cards. All parameter sets have the **SetSeed** -parameter and the common parameters. - -These parameter sets indicate that you can use the **InputObject** and -**Count** parameters in the same command, but you can't use the **Maximum** and -**Shuffle** parameters in the same command. - -You indicate which parameter set you want to use by using the parameters in -that parameter set. However, every cmdlet also has a default parameter set. The -default parameter set is used when you don't specify parameters that are unique -to a parameter set. For example, if you use `Get-Random` without parameters, -Windows PowerShell assumes that you are using the **RandomNumberParameterSet** -parameter set and it returns a random number. +- The first parameter set returns one or more random numbers and has the + **Minimum**, **Maximum**, and **Count** parameters. +- The second parameter set returns a randomly selected object from a set of + objects and includes the **InputObject** and **Count** parameters. +- The third parameter set has the **Shuffle** parameter that returns a + collection of objects in a random order, like shuffling a deck of cards. +- All parameter sets have the **SetSeed** parameter and the common parameters. + +These parameter sets show that you can use the **InputObject** and **Count** +parameters in the same command, but you can't use the **Maximum** and +**Shuffle** parameters together. + +Every cmdlet also has a default parameter set. The default parameter set is +used when you don't specify parameters that are unique to a parameter set. For +example, if you use `Get-Random` without parameters, PowerShell assumes that +you're using the **RandomNumberParameterSet** parameter set and it returns a +random number. ## Symbols in Syntax Diagrams The syntax diagram lists the command name, the command parameters, and the -parameter values. It also uses symbols to show how to construct a valid -command. +parameter values. The syntax diagrams use the following symbols: @@ -170,46 +155,33 @@ The syntax diagrams use the following symbols: immediately before the parameter name with no intervening spaces, as shown in the syntax diagram. - For example, to use the **Name** parameter of `New-Alias`, type: - `New-Alias -Name`. + For example, to use the **Name** parameter of `Get-Command`, type: + `Get-Command -Name`. -- Angle brackets `<>` indicate placeholder text. You don't type the angle + +- Angle brackets `< >` indicate placeholder text. You don't type the angle brackets or the placeholder text in a command. Instead, you replace it with the item that it describes. The placeholder inside the angle brackets identifies the .NET type of the value that a parameter takes. For example, to use the **Name** parameter of - the `New-Alias` cmdlet, you replace the `` with a string, which is a - single word or a group of words that are enclosed in quotation marks. - -- Brackets `[]` around parameters indicate optional items. A parameter and its - value can be optional, or the name of a required parameter can be optional. - - For example, the **Description** parameter of `New-Alias` and its value are - enclosed in brackets because they're both optional. - - The brackets also indicate that the value of the **Name** parameter is - required, but the parameter name, `-Name`, is optional. - - In each parameter set, the parameters appear in position order. The order of - parameters in a command matters only when you omit the optional parameter - names. When parameter names are omitted, PowerShell assigns values to - parameters by position and type. For more information about parameter - position, see [about_Parameters][01]. + the `Get-Command ` cmdlet, you replace the `` with one or more + strings separated by commas (`,`). + - Brackets `[]` appended to a .NET type indicate that the parameter can accept one or more values of that type. Enter the values as a comma-separated list. - For example, the **Name** parameter of the `New-Alias` cmdlet takes only one - string. + For example, the **Name** and **Value** parameters of the `New-Alias` cmdlet + only take one string each. ```Syntax - New-Alias [-Name] + New-Alias [-Name] [-Value] ``` ```powershell - New-Alias -Name MyAlias + New-Alias -Name MyAlias -Value mycommand.exe ``` But the **Name** parameter of [Get-Process][04] can take one or more strings. @@ -222,78 +194,74 @@ The syntax diagrams use the following symbols: Get-Process -Name Explorer, Winlogon, Services ``` -- Braces `{}` indicate an "enumeration," which is a set of valid values for a - parameter. +- Parameters with no values - The values in the braces are separated by vertical bars `|`. These bars - indicate an _exclusive-OR_ choice, meaning that you can choose only one value - from the set of values that are listed inside the braces. + Some parameters don't accept input, so they don't have a parameter value. + Parameters without values are _switch parameters_. Switch parameters are used + like boolean values. They default to `$false`. When you use a switch + parameter, the value is set to `$true`. - For example, the syntax for the `New-Alias` cmdlet includes the following - value enumeration for the **Option** parameter: + For example, the **ListImported** parameter of `Get-Command` is a switch + parameter. When you use the **ListImported** parameter, the cmdlet return + only commands that were imported from modules in the current session. ```Syntax - New-Alias -Option {None | ReadOnly | Constant | Private | AllScope} + Get-Command [-ListImported] ``` - The braces and vertical bars indicate that you can choose any one of the - listed values for the **Option** parameter, such as "ReadOnly" or "AllScope". + +- Brackets `[ ]` around parameters indicate optional items. A parameter and + its value can be optional. For example, the **CommandType** parameter of + `Get-Command` and its value are enclosed in brackets because they're both + optional. - ```powershell - New-Alias -Option ReadOnly + ```Syntax + Get-Command [-CommandType ] ``` -## Optional Items - -Brackets `[]` surround optional items. For example, in the `New-Alias` cmdlet -syntax description, the **Scope** parameter is optional. This is indicated in -the syntax by the brackets around the parameter name and type: - -```powershell -New-Alias [-Scope ] -``` - -Both the following examples are correct uses of the `New-Alias` cmdlet: + Brackets around the parameter name, but not the parameter value, indicate + that the parameter name is optional. These parameters are known as positional + parameters. The parameter values must be presented in the correct order for + the values to be bound to the correct parameter. -```powershell -New-Alias -Name utd -Value Update-TypeData -New-Alias -Name utd -Value Update-TypeData -Scope Global -``` + For example, for the `New-Alias` cmdlet, the **Name** and **Value** parameter + values are required, but the parameter names, `-Name` and `-Value`, are + optional. -A parameter name can be optional even if the value for that parameter is -required. This is indicated in the syntax by the brackets around the parameter -name but not the parameter type, as in this example from the `New-Alias` -cmdlet: + ```Syntax + New-Alias [-Name] [-Value] + ``` -```Syntax -New-Alias [-Name] [-Value] -``` + ```powershell + New-Alias MyAlias mycommand.exe + ``` -The following commands correctly use the `New-Alias` cmdlet. The commands -produce the same result. + In each parameter set, the parameters appear in position order. The order of + parameters in a command matters only when you omit the optional parameter + names. When parameter names are omitted, PowerShell assigns values to + parameters by position and type. For more information about parameter + position, see [about_Parameters][01]. -```powershell -New-Alias -Name utd -Value Update-TypeData -New-Alias -Name utd Update-TypeData -New-Alias utd -Value Update-TypeData -New-Alias utd Update-TypeData -``` +- Braces `{}` indicate an "enumeration," which is a set of valid values for a + parameter. -If the parameter name isn't included in the statement as typed, Windows -PowerShell tries to use the position of the arguments to assign the values to -parameters. + The values in the braces are separated by vertical bars `|`. These bars + indicate an _exclusive-OR_ choice, meaning that you can choose only one value + from the set of values that are listed inside the braces. -The following example isn't complete: + For example, the syntax for the `New-Alias` cmdlet includes the following + value enumeration for the **Option** parameter: -```powershell -New-Alias utd -``` + ```Syntax + New-Alias -Option {None | ReadOnly | Constant | Private | AllScope} + ``` -This cmdlet requires values for both the **Name** and **Value** parameters. + The braces and vertical bars indicate that you can choose any one of the + listed values for the **Option** parameter, such as `ReadOnly` or `AllScope`. -In syntax examples, brackets are also used in naming and casting to .NET -Framework types. In this context, brackets don't indicate an element is -optional. + ```powershell + New-Alias -Option ReadOnly + ``` ## See also @@ -307,4 +275,3 @@ optional. [03]: xref:Microsoft.PowerShell.Core.Get-Help [04]: xref:Microsoft.PowerShell.Management.Get-Process [05]: xref:Microsoft.PowerShell.Utility.Get-Random -[06]: xref:Microsoft.PowerShell.Utility.New-Alias diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Command_Syntax.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Command_Syntax.md index 9089009f7a46..a5889de8c0b3 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Command_Syntax.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Command_Syntax.md @@ -1,7 +1,7 @@ --- description: Describes the syntax diagrams that are used in PowerShell. Locale: en-US -ms.date: 05/30/2023 +ms.date: 10/31/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_command_syntax?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Command Syntax @@ -14,109 +14,96 @@ Describes the syntax diagrams that are used in PowerShell. ## Long description The [Get-Help][03] and [Get-Command][02] cmdlets display syntax diagrams to -help you construct commands correctly. This topic explains how to interpret the -syntax diagrams. +help you construct commands correctly. This article explains how to interpret +the syntax diagrams. -## SYNTAX DIAGRAMS +## Get the syntax for a command -Each paragraph in a command syntax diagram represents a valid form of the -command. +There are two ways to get the syntax for a command: `Get-Help` and +`Get-Command`. -To construct a command, follow the syntax diagram from left to right. Select -from among the optional parameters and provide values for the placeholders. +### Get-Command -PowerShell uses the following notation for syntax diagrams. +The `Get-Command` command can be used to get information about any command on +your system. Use the **Syntax** parameter to get the syntax for a command. -```Syntax - - - [- ] - [-] - [-] +```powershell +Get-Command Get-Command -Syntax ``` -`Get-Help` shows the following syntax for the [New-Alias][06] cmdlet. - -```Syntax -New-Alias [-Name] [-Value] [-Description ] [-Force] - [-Option {None | ReadOnly | Constant | Private | AllScope | Unspecified}] - [-PassThru] [-Scope ] [-Confirm] [-WhatIf] [] +```Output +Get-Command [[-ArgumentList] ] [-Verb ] [-Noun ] + [-Module ] [-FullyQualifiedModule ] + [-TotalCount ] [-Syntax] [-ShowCommandInfo] [-All] [-ListImported] + [-ParameterName ] [-ParameterType ] + [] + +Get-Command [[-Name] ] [[-ArgumentList] ] + [-Module ] [-FullyQualifiedModule ] + [-CommandType ] [-TotalCount ] [-Syntax] [-ShowCommandInfo] + [-All] [-ListImported] [-ParameterName ] + [-ParameterType ] [-UseFuzzyMatching] + [-FuzzyMinimumDistance ] [-UseAbbreviationExpansion] + [] ``` -The syntax is capitalized for readability, but PowerShell is case-insensitive. - -The syntax diagram has the following elements. - -## Command name - -Commands always begin with a command name, such as `New-Alias`. Type the -command name or its alias, such a "gcm" for `Get-Command`. - -## Parameters - -The parameters of a command are options that determine what the command does. -Some parameters take a value as user input to the command. - -For example, the `Get-Help` command has a **Name** parameter that lets you -specify the name of the topic for which help is displayed. The topic name is -the value of the **Name** parameter. - -In a PowerShell command, parameter names always begin with a hyphen. The hyphen -tells PowerShell that the item in the command is a parameter name. +### Get-Help -For example, to use the **Name** parameter of `New-Alias`, you type the -following: `New-Alias -Name` +The `Get-Help` command provides detailed information about PowerShell commands +including, syntax, detailed description of the cmdlet and parameters, and +examples. The output `Get-Help` command starts with a brief description of the +command followed by the syntax. -Parameters can be mandatory or optional. In a syntax diagram, optional items -are enclosed in brackets `[]`. - -For more information about parameters, see [about_Parameters][01]. - -## Parameter Values - -A parameter value is the input that the parameter takes. Because Windows -PowerShell is based on the Microsoft .NET Framework, parameter values are -represented in the syntax diagram by their .NET type. - -For example, the Name parameter of `Get-Help` takes a "String" value, which is -a text string, such as a single word or multiple words enclosed in quotation -marks. - -```Syntax -New-Alias [-Name] +```powershell +Get-Help Get-Command ``` -The .NET type of a parameter value is enclosed in angle brackets `<>` to -indicate that it's placeholder for a value and not a literal that you type in a -command. - -To use the parameter, replace the .NET type placeholder with an object that has -the specified .NET type. - -For example, to use the **Name** parameter, type `-Name` followed by a string, -such as the following: `-Name MyAlias` - -## Parameters with no values - -Some parameters don't accept input, so they don't have a parameter value. -Parameters without values are called _switch parameters_ because they work like -on/off switches. You include them (on) or you omit them (off) from a command. +The following output has been shortened to focus on the syntax description. -To use a switch parameter, just type the parameter name, preceded by a hyphen. +```Output +NAME + Get-Command + +SYNOPSIS + Gets all commands. + +SYNTAX + + Get-Command [[-Name] ] [[-ArgumentList] ] + [-All] [-CommandType {Alias | Function | Filter | Cmdlet | ExternalScript | + Application | Script | Workflow | Configuration | All}] + [-FullyQualifiedModule ] + [-ListImported] [-Module ] [-ParameterName ] + [-ParameterType ] + [-ShowCommandInfo] [-Syntax] [-TotalCount ] + [-UseAbbreviationExpansion] [-UseFuzzyMatching] [] + + Get-Command [[-ArgumentList] ] [-All] + [-FullyQualifiedModule ] + [-ListImported] [-Module ] [-Noun ] + [-ParameterName ] + [-ParameterType ] + [-ShowCommandInfo] [-Syntax] [-TotalCount ] + [-Verb ] [] +... +``` -For example, to use the **WhatIf** parameter of the `New-Alias` cmdlet, type -the following: `New-Alias -WhatIf`. +The output of `Get-Help` is slightly different from the output of +`Get-Command`. Notice the difference in the syntax for the **CommandType** +parameter. `Get-Command` shows the parameter type as the `[CommandTypes]` +enumeration, while `Get-Help` show the possible values for the enumeration. ## Parameter Sets -The parameters of a command are listed in parameter sets. Parameter sets look -like the paragraphs of a syntax diagram. +The parameters of a PowerShell command are listed in parameter sets. A +PowerShell command can have one or more parameter sets. The `Get-Command` +cmdlet has two parameter sets, as shown in the previous examples. -The `New-Alias` cmdlet has one parameter set, but many cmdlets have multiple -parameter sets. Some of the cmdlet parameters are unique to a parameter set, -and others appear in multiple parameter sets. Each parameter set represents the -format of a valid command. A parameter set includes only parameters that can be -used together in a command. If parameters can't be used in the same command, -they appear in separate parameter sets. +Some of the cmdlet parameters are unique to a parameter set, and others appear +in multiple parameter sets. Each parameter set represents the format for a +valid command. A parameter set includes only parameters that can be used +together in a command. When parameters can't be used in the same command, they +are listed in separate parameter sets. For example, the [Get-Random][05] cmdlet has the following parameter sets: @@ -139,30 +126,28 @@ ShuffleParameterSet False [-InputObject] -Shuffle [-SetSeed ] [] ``` -The first parameter set returns one or more random numbers and has the -**Minimum**, **Maximum**, and **Count** parameters. The second parameter set -returns a randomly selected object from a set of objects and includes the -**InputObject** and **Count** parameters. The third parameter set has the -**Shuffle** parameters that returns a collection of objects in a random order, -like shuffling a deck of cards. All parameter sets have the **SetSeed** -parameter and the common parameters. - -These parameter sets indicate that you can use the **InputObject** and -**Count** parameters in the same command, but you can't use the **Maximum** and -**Shuffle** parameters in the same command. - -You indicate which parameter set you want to use by using the parameters in -that parameter set. However, every cmdlet also has a default parameter set. The -default parameter set is used when you don't specify parameters that are unique -to a parameter set. For example, if you use `Get-Random` without parameters, -Windows PowerShell assumes that you are using the **RandomNumberParameterSet** -parameter set and it returns a random number. +- The first parameter set returns one or more random numbers and has the + **Minimum**, **Maximum**, and **Count** parameters. +- The second parameter set returns a randomly selected object from a set of + objects and includes the **InputObject** and **Count** parameters. +- The third parameter set has the **Shuffle** parameter that returns a + collection of objects in a random order, like shuffling a deck of cards. +- All parameter sets have the **SetSeed** parameter and the common parameters. + +These parameter sets show that you can use the **InputObject** and **Count** +parameters in the same command, but you can't use the **Maximum** and +**Shuffle** parameters together. + +Every cmdlet also has a default parameter set. The default parameter set is +used when you don't specify parameters that are unique to a parameter set. For +example, if you use `Get-Random` without parameters, PowerShell assumes that +you're using the **RandomNumberParameterSet** parameter set and it returns a +random number. ## Symbols in Syntax Diagrams The syntax diagram lists the command name, the command parameters, and the -parameter values. It also uses symbols to show how to construct a valid -command. +parameter values. The syntax diagrams use the following symbols: @@ -170,46 +155,33 @@ The syntax diagrams use the following symbols: immediately before the parameter name with no intervening spaces, as shown in the syntax diagram. - For example, to use the **Name** parameter of `New-Alias`, type: - `New-Alias -Name`. + For example, to use the **Name** parameter of `Get-Command`, type: + `Get-Command -Name`. -- Angle brackets `<>` indicate placeholder text. You don't type the angle + +- Angle brackets `< >` indicate placeholder text. You don't type the angle brackets or the placeholder text in a command. Instead, you replace it with the item that it describes. The placeholder inside the angle brackets identifies the .NET type of the value that a parameter takes. For example, to use the **Name** parameter of - the `New-Alias` cmdlet, you replace the `` with a string, which is a - single word or a group of words that are enclosed in quotation marks. - -- Brackets `[]` around parameters indicate optional items. A parameter and its - value can be optional, or the name of a required parameter can be optional. - - For example, the **Description** parameter of `New-Alias` and its value are - enclosed in brackets because they're both optional. - - The brackets also indicate that the value of the **Name** parameter is - required, but the parameter name, `-Name`, is optional. - - In each parameter set, the parameters appear in position order. The order of - parameters in a command matters only when you omit the optional parameter - names. When parameter names are omitted, PowerShell assigns values to - parameters by position and type. For more information about parameter - position, see [about_Parameters][01]. + the `Get-Command ` cmdlet, you replace the `` with one or more + strings separated by commas (`,`). + - Brackets `[]` appended to a .NET type indicate that the parameter can accept one or more values of that type. Enter the values as a comma-separated list. - For example, the **Name** parameter of the `New-Alias` cmdlet takes only one - string. + For example, the **Name** and **Value** parameters of the `New-Alias` cmdlet + only take one string each. ```Syntax - New-Alias [-Name] + New-Alias [-Name] [-Value] ``` ```powershell - New-Alias -Name MyAlias + New-Alias -Name MyAlias -Value mycommand.exe ``` But the **Name** parameter of [Get-Process][04] can take one or more strings. @@ -222,78 +194,74 @@ The syntax diagrams use the following symbols: Get-Process -Name Explorer, Winlogon, Services ``` -- Braces `{}` indicate an "enumeration," which is a set of valid values for a - parameter. +- Parameters with no values - The values in the braces are separated by vertical bars `|`. These bars - indicate an _exclusive-OR_ choice, meaning that you can choose only one value - from the set of values that are listed inside the braces. + Some parameters don't accept input, so they don't have a parameter value. + Parameters without values are _switch parameters_. Switch parameters are used + like boolean values. They default to `$false`. When you use a switch + parameter, the value is set to `$true`. - For example, the syntax for the `New-Alias` cmdlet includes the following - value enumeration for the **Option** parameter: + For example, the **ListImported** parameter of `Get-Command` is a switch + parameter. When you use the **ListImported** parameter, the cmdlet return + only commands that were imported from modules in the current session. ```Syntax - New-Alias -Option {None | ReadOnly | Constant | Private | AllScope} + Get-Command [-ListImported] ``` - The braces and vertical bars indicate that you can choose any one of the - listed values for the **Option** parameter, such as "ReadOnly" or "AllScope". + +- Brackets `[ ]` around parameters indicate optional items. A parameter and + its value can be optional. For example, the **CommandType** parameter of + `Get-Command` and its value are enclosed in brackets because they're both + optional. - ```powershell - New-Alias -Option ReadOnly + ```Syntax + Get-Command [-CommandType ] ``` -## Optional Items - -Brackets `[]` surround optional items. For example, in the `New-Alias` cmdlet -syntax description, the **Scope** parameter is optional. This is indicated in -the syntax by the brackets around the parameter name and type: - -```powershell -New-Alias [-Scope ] -``` - -Both the following examples are correct uses of the `New-Alias` cmdlet: + Brackets around the parameter name, but not the parameter value, indicate + that the parameter name is optional. These parameters are known as positional + parameters. The parameter values must be presented in the correct order for + the values to be bound to the correct parameter. -```powershell -New-Alias -Name utd -Value Update-TypeData -New-Alias -Name utd -Value Update-TypeData -Scope Global -``` + For example, for the `New-Alias` cmdlet, the **Name** and **Value** parameter + values are required, but the parameter names, `-Name` and `-Value`, are + optional. -A parameter name can be optional even if the value for that parameter is -required. This is indicated in the syntax by the brackets around the parameter -name but not the parameter type, as in this example from the `New-Alias` -cmdlet: + ```Syntax + New-Alias [-Name] [-Value] + ``` -```Syntax -New-Alias [-Name] [-Value] -``` + ```powershell + New-Alias MyAlias mycommand.exe + ``` -The following commands correctly use the `New-Alias` cmdlet. The commands -produce the same result. + In each parameter set, the parameters appear in position order. The order of + parameters in a command matters only when you omit the optional parameter + names. When parameter names are omitted, PowerShell assigns values to + parameters by position and type. For more information about parameter + position, see [about_Parameters][01]. -```powershell -New-Alias -Name utd -Value Update-TypeData -New-Alias -Name utd Update-TypeData -New-Alias utd -Value Update-TypeData -New-Alias utd Update-TypeData -``` +- Braces `{}` indicate an "enumeration," which is a set of valid values for a + parameter. -If the parameter name isn't included in the statement as typed, Windows -PowerShell tries to use the position of the arguments to assign the values to -parameters. + The values in the braces are separated by vertical bars `|`. These bars + indicate an _exclusive-OR_ choice, meaning that you can choose only one value + from the set of values that are listed inside the braces. -The following example isn't complete: + For example, the syntax for the `New-Alias` cmdlet includes the following + value enumeration for the **Option** parameter: -```powershell -New-Alias utd -``` + ```Syntax + New-Alias -Option {None | ReadOnly | Constant | Private | AllScope} + ``` -This cmdlet requires values for both the **Name** and **Value** parameters. + The braces and vertical bars indicate that you can choose any one of the + listed values for the **Option** parameter, such as `ReadOnly` or `AllScope`. -In syntax examples, brackets are also used in naming and casting to .NET -Framework types. In this context, brackets don't indicate an element is -optional. + ```powershell + New-Alias -Option ReadOnly + ``` ## See also @@ -307,4 +275,3 @@ optional. [03]: xref:Microsoft.PowerShell.Core.Get-Help [04]: xref:Microsoft.PowerShell.Management.Get-Process [05]: xref:Microsoft.PowerShell.Utility.Get-Random -[06]: xref:Microsoft.PowerShell.Utility.New-Alias