about_Command_Syntax

Artigo
11/03/2023

Descrição breve

Descreve os diagramas de sintaxe que são 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 em 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 de saída 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, conforme 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 Mínimo, Máximo e Contagem .
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 exclusivos de 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 ele retornará um número aleatório.

Símbolos em diagramas de sintaxe

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

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 o texto do < > espaço reservado. Você não digita os colchetes angulares ou o texto do espaço reservado em um comando. Em vez disso, você o substitui pelo item que ele descreve.

O espaço reservado dentro dos colchetes angulares identifica o tipo .NET do valor que um parâmetro usa. 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 New-Alias parâmetros Name e Value do cmdlet usam apenas uma cadeia de 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, portanto, eles não têm um valor de parâmetro. Parâmetros sem valores são parâmetros de comutação. Os parâmetros de switch são usados como valores booleanos. Eles têm como $falsepadrão . Quando você usa um parâmetro de opção, o valor é definido como $true.

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

Colchetes ao redor dos [ ] 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 são colocados entre colchetes porque ambos são opcionais.
```
Get-Command [-CommandType <CommandTypes>]
```
Colchetes ao redor do nome do parâmetro, mas não do valor do parâmetro, indicam que o nome do parâmetro é opcional. Esses 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 obrigató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 importa somente quando você omite os nomes de parâmetros opcionais. Quando os nomes de parâmetros são omitidos, o PowerShell atribui valores a 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 OR exclusiva, 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
```

Compartilhar via