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 7b0301b5a84f..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,8 +14,8 @@ 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 article explains how to interpret the -syntax diagrams. +help you construct commands correctly. This article explains how to interpret +the syntax diagrams. ## Get the syntax for a command @@ -103,7 +103,7 @@ 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 -listed in separate parameter sets. +are listed in separate parameter sets. For example, the [Get-Random][05] cmdlet has the following parameter sets: @@ -159,7 +159,7 @@ The syntax diagrams use the following symbols: `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. @@ -257,7 +257,7 @@ The syntax diagrams use the following symbols: ``` 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". + listed values for the **Option** parameter, such as `ReadOnly` or `AllScope`. ```powershell New-Alias -Option ReadOnly @@ -275,4 +275,3 @@ The syntax diagrams use the following symbols: [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