about_Command_Syntax

Artigo
11/06/2024

Descrição breve

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 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 os comandos do PowerShell, incluindo sintaxe, descrição detalhada do cmdlet e dos parâmetros e exemplos. O comando de saída Get-Help começa com uma breve descrição do comando seguida 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 de 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 exclusivos de um conjunto de parâmetros. Por exemplo, se você usar Get-Random sem parâmetros, o PowerShell pressupõe que você está usando o conjunto de parâmetros RandomNumberParameterSet e retorna 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 intermediários, 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 caracteres separadas por vírgulas Get-Command (,).

Os colchetes [] acrescentados 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írgulas.

Por exemplo, os parâmetros Name e Value do New-Alias 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 usar 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, 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. O padrão é $false. Quando você usa um parâmetro switch, o valor é definido como $true.

Por exemplo, o parâmetro ListImported de Get-Command é um parâmetro switch. 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]
```

Os 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>]
```
Os 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 associados 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 de parâmetro 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 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 as 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