about_Command_Syntax

Artigo
11/03/2023

Breve descrição

Descreve os diagramas de sintaxe usados no PowerShell.

Descrição longa

Os cmdlets Get-Help e Get-Command exibem diagramas de sintaxe para ajudá-lo a construir comandos corretamente. Este artigo explica como interpretar os diagramas de sintaxe.

Obter a sintaxe de um comando

Há duas maneiras de obter a sintaxe de um comando: Get-Help e Get-Command.

Get-Command

O Get-Command comando pode ser usado para obter informações sobre qualquer comando no seu sistema. Use o parâmetro Syntax para obter a sintaxe de um comando.

Get-Command Get-Command -Syntax

Get-Command [[-ArgumentList] <Object[]>] [-Verb <string[]>] [-Noun <string[]>]
 [-Module <string[]>] [-FullyQualifiedModule <ModuleSpecification[]>]
 [-TotalCount <int>] [-Syntax] [-ShowCommandInfo] [-All] [-ListImported]
 [-ParameterName <string[]>] [-ParameterType <PSTypeName[]>]
 [<CommonParameters>]

Get-Command [[-Name] <string[]>] [[-ArgumentList] <Object[]>]
 [-Module <string[]>] [-FullyQualifiedModule <ModuleSpecification[]>]
 [-CommandType <CommandTypes>] [-TotalCount <int>] [-Syntax] [-ShowCommandInfo]
 [-All] [-ListImported] [-ParameterName <string[]>]
 [-ParameterType <PSTypeName[]>] [-UseFuzzyMatching]
 [-FuzzyMinimumDistance <uint>] [-UseAbbreviationExpansion]
 [<CommonParameters>]

Get-Help

O Get-Help comando fornece informações detalhadas sobre comandos do PowerShell, incluindo sintaxe, descrição detalhada do cmdlet e parâmetros e exemplos. O comando output Get-Help começa com uma breve descrição do comando seguido pela sintaxe.

Get-Help Get-Command

A saída a seguir foi encurtada para se concentrar na descrição da sintaxe.

NAME
    Get-Command

SYNOPSIS
    Gets all commands.

SYNTAX

    Get-Command [[-Name] <System.String[]>] [[-ArgumentList] <System.Object[]>]
    [-All] [-CommandType {Alias | Function | Filter | Cmdlet | ExternalScript |
    Application | Script | Workflow | Configuration | All}]
    [-FullyQualifiedModule <Microsoft.PowerShell.Commands.ModuleSpecification[]>]
    [-ListImported] [-Module <System.String[]>] [-ParameterName <System.String[]>]
    [-ParameterType <System.Management.Automation.PSTypeName[]>]
    [-ShowCommandInfo] [-Syntax] [-TotalCount <System.Int32>]
    [-UseAbbreviationExpansion] [-UseFuzzyMatching] [<CommonParameters>]

    Get-Command [[-ArgumentList] <System.Object[]>] [-All]
    [-FullyQualifiedModule <Microsoft.PowerShell.Commands.ModuleSpecification[]>]
    [-ListImported] [-Module <System.String[]>] [-Noun <System.String[]>]
    [-ParameterName <System.String[]>]
    [-ParameterType <System.Management.Automation.PSTypeName[]>]
    [-ShowCommandInfo] [-Syntax] [-TotalCount <System.Int32>]
    [-Verb <System.String[]>] [<CommonParameters>]
...

A saída de Get-Help é ligeiramente diferente da saída de Get-Command. Observe a diferença na sintaxe do parâmetro CommandType . Get-Command mostra o tipo de parâmetro como a [CommandTypes] enumeração, enquanto Get-Help mostra os valores possíveis para a enumeração.

Conjuntos de parâmetros

Os parâmetros de um comando do PowerShell são listados em conjuntos de parâmetros. Um comando do PowerShell pode ter um ou mais conjuntos de parâmetros. O Get-Command cmdlet tem dois conjuntos de parâmetros, como mostrado nos exemplos anteriores.

Alguns dos parâmetros do cmdlet são exclusivos de um conjunto de parâmetros e outros aparecem em vários conjuntos de parâmetros. Cada conjunto de parâmetros representa o formato de um comando válido. Um conjunto de parâmetros inclui apenas parâmetros que podem ser usados juntos em um comando. Quando os parâmetros não podem ser usados no mesmo comando, eles são listados em conjuntos de parâmetros separados.

Por exemplo, o cmdlet Get-Random tem os seguintes conjuntos de parâmetros:

$cmd = Get-Command Get-Random
$cmd.ParameterSets |
    Select-Object Name, IsDefault, @{n='Parameters';e={$_.ToString()}} |
    Format-Table -Wrap

Name                       IsDefault Parameters
----                       --------- ----------
RandomNumberParameterSet        True [[-Maximum] <Object>] [-SetSeed <int>]
                                     [-Minimum <Object>] [-Count <int>]
                                     [<CommonParameters>]
RandomListItemParameterSet     False [-InputObject] <Object[]> [-SetSeed <int>]
                                     [-Count <int>] [<CommonParameters>]
ShuffleParameterSet            False [-InputObject] <Object[]> -Shuffle
                                     [-SetSeed <int>] [<CommonParameters>]

O primeiro conjunto de parâmetros retorna um ou mais números aleatórios e tem os parâmetros Minimum, Maximum e Count.
O segundo conjunto de parâmetros retorna um objeto selecionado aleatoriamente de um conjunto de objetos e inclui os parâmetros InputObject e Count .
O terceiro conjunto de parâmetros tem o parâmetro Shuffle que retorna uma coleção de objetos em uma ordem aleatória, como embaralhar um baralho de cartas.
Todos os conjuntos de parâmetros têm o parâmetro SetSeed e os parâmetros comuns.

Esses conjuntos de parâmetros mostram que você pode usar os parâmetros InputObject e Count no mesmo comando, mas não pode usar os parâmetros Maximum e Shuffle juntos.

Cada cmdlet também tem um conjunto de parâmetros padrão. O conjunto de parâmetros padrão é usado quando você não especifica parâmetros que são exclusivos para um conjunto de parâmetros. Por exemplo, se você usar Get-Random sem parâmetros, o PowerShell assumirá que você está usando o conjunto de parâmetros RandomNumberParameterSet e retornará um número aleatório.

Símbolos em diagramas de sintaxe

O diagrama de sintaxe lista o nome do comando, os parâmetros do comando e os valores dos parâmetros.

Os diagramas de sintaxe usam os seguintes símbolos:

Um hífen - indica um nome de parâmetro. Em um comando, digite o hífen imediatamente antes do nome do parâmetro sem espaços intervenientes, conforme mostrado no diagrama de sintaxe.

Por exemplo, para usar o parâmetro Name de Get-Command, digite: Get-Command -Name.

Os colchetes < > angulares indicam texto de espaço reservado. Você não digita os colchetes angulares ou o texto do espaço reservado em um comando. Em vez disso, substitua-o pelo item que descreve.

O espaço reservado dentro dos colchetes angulares identifica o tipo .NET do valor que um parâmetro assume. Por exemplo, para usar o parâmetro Name do cmdlet, substitua o <string[]> por uma ou mais cadeias de Get-Command caracteres separadas por vírgulas (,).

Colchetes [] anexados a um tipo .NET indicam que o parâmetro pode aceitar um ou mais valores desse tipo. Insira os valores como uma lista separada por vírgula.

Por exemplo, os parâmetros Name e Value do cmdlet usam apenas uma cadeia de New-Alias caracteres cada.
```
New-Alias [-Name] <string> [-Value] <string>
```
```
New-Alias -Name MyAlias -Value mycommand.exe
```
Mas o parâmetro Name de Get-Process pode ter uma ou mais cadeias de caracteres.
```
Get-Process [-Name] <string[]>
```
```
Get-Process -Name Explorer, Winlogon, Services
```
Parâmetros sem valores

Alguns parâmetros não aceitam entrada, por isso não têm um valor de parâmetro. Parâmetros sem valores são parâmetros de switch. Os parâmetros do switch são usados como valores booleanos. Eles não têm como $falsepadrão . Quando você usa um parâmetro switch, o valor é definido como $true.

Por exemplo, o parâmetro ListImported de é um parâmetro switch Get-Command . Quando você usa o parâmetro ListImported , o cmdlet retorna somente comandos que foram importados de módulos na sessão atual.
```
Get-Command [-ListImported]
```

Colchetes em torno de [ ] parâmetros indicam itens opcionais. Um parâmetro e seu valor podem ser opcionais. Por exemplo, o parâmetro CommandType de Get-Command e seu valor estão entre colchetes porque ambos são opcionais.
```
Get-Command [-CommandType <CommandTypes>]
```
Colchetes ao redor do nome do parâmetro, mas não o valor do parâmetro, indicam que o nome do parâmetro é opcional. Estes parâmetros são conhecidos como parâmetros posicionais. Os valores dos parâmetros devem ser apresentados na ordem correta para que os valores sejam vinculados ao parâmetro correto.

Por exemplo, para o New-Alias cmdlet, os valores dos parâmetros Name e Value são necessários, mas os nomes -Name dos parâmetros e -Value, são opcionais.
```
New-Alias [-Name] <string> [-Value] <string>
```
```
New-Alias MyAlias mycommand.exe
```
Em cada conjunto de parâmetros, os parâmetros aparecem em ordem de posição. A ordem dos parâmetros em um comando é importante apenas quando você omite os nomes de parâmetros opcionais. Quando os nomes dos parâmetros são omitidos, o PowerShell atribui valores aos parâmetros por posição e tipo. Para obter mais informações sobre a posição do parâmetro, consulte about_Parameters.
As chaves indicam uma "enumeração", que é um conjunto de valores válidos {} para um parâmetro.

Os valores nas chaves são separados por barras |verticais. Essas barras indicam uma opção exclusive-OR , o que significa que você pode escolher apenas um valor do conjunto de valores listados dentro das chaves.

Por exemplo, a sintaxe do New-Alias cmdlet inclui a seguinte enumeração de valor para o parâmetro Option :
```
New-Alias -Option {None | ReadOnly | Constant | Private | AllScope}
```
As chaves e barras verticais indicam que você pode escolher qualquer um dos valores listados para o parâmetro Option , como ReadOnly ou AllScope.
```
New-Alias -Option ReadOnly
```