about_Command_Syntax

Artigo
06/21/2023

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 tópico explica como interpretar os diagramas de sintaxe.

DIAGRAMAS DE SINTAXE

Cada parágrafo em um diagrama de sintaxe de comando representa uma forma válida do comando.

Para construir um comando, siga o diagrama de sintaxe da esquerda para a direita. Selecione entre os parâmetros opcionais e forneça valores para os espaços reservados.

O PowerShell usa a notação a seguir para diagramas de sintaxe.

<command-name> -<Required Parameter Name> <Required Parameter Value>
[-<Optional Parameter Name> <Optional Parameter Value>]
[-<Optional Switch Parameters>]
[-<Optional Parameter Name>] <Required Parameter Value>

Veja a seguir a sintaxe do cmdlet New-Alias .

New-Alias [-Name] <string> [-Value] <string> [-Description <string>]
[-Force] [-Option {None | ReadOnly | Constant | Private | AllScope}]
[-PassThru] [-Scope <string>] [-Confirm] [-WhatIf] [<CommonParameters>]

A sintaxe é capitalizada para facilitar a leitura, mas o PowerShell não diferencia maiúsculas de minúsculas.

O diagrama de sintaxe tem os elementos a seguir.

Nome de comando

Os comandos sempre começam com um nome de comando, como New-Alias. Digite o nome do comando ou seu alias, como um "gcm" para Get-Command.

Parâmetros

Os parâmetros de um comando são opções que determinam o que o comando faz. Alguns parâmetros usam um "valor" que é a entrada do usuário para o comando.

Por exemplo, o Get-Help comando tem um parâmetro Name que permite especificar o nome do tópico para o qual a ajuda é exibida. O nome do tópico é o valor do parâmetro Name .

Em um comando do PowerShell, os nomes de parâmetro sempre começam com um hífen. O hífen informa ao PowerShell que o item no comando é um nome de parâmetro.

Por exemplo, para usar o parâmetro Name de New-Alias, digite o seguinte:

-Name

Os parâmetros podem ser obrigatórios ou opcionais. Em um diagrama de sintaxe, os itens opcionais são colocados entre colchetes [ ].

Para obter mais informações sobre parâmetros, consulte about_Parameters.

Valores dos parâmetros

Um valor de parâmetro é a entrada que o parâmetro usa. Como Windows PowerShell se baseia no microsoft .NET Framework, os valores de parâmetro são representados no diagrama de sintaxe pelo tipo .NET.

Por exemplo, o parâmetro Name de Get-Help usa um valor "String", que é uma cadeia de caracteres de texto, como uma única palavra ou várias palavras entre aspas.

[-Name] <string>

O tipo .NET de um valor de parâmetro é colocado entre colchetes angulares < > para indicar que ele é um espaço reservado para um valor e não um literal que você digita em um comando.

Para usar o parâmetro , substitua o espaço reservado do tipo .NET por um objeto que tenha o tipo .NET especificado.

Por exemplo, para usar o parâmetro Name , digite "-Name" seguido por uma cadeia de caracteres, como a seguinte:

-Name MyAlias

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 chamados de "parâmetros de opção" porque funcionam como comutadores ativados/desativados. Inclua-as (ativadas) ou omita-as (desativadas) de um comando.

Para usar um parâmetro switch, basta digitar o nome do parâmetro, precedido por um hífen.

Por exemplo, para usar o parâmetro WhatIf do New-Alias cmdlet, digite o seguinte:

-WhatIf

Conjuntos de Parâmetros

Os parâmetros de um comando são listados em conjuntos de parâmetros. Os conjuntos de parâmetros se parecem com os parágrafos de um diagrama de sintaxe.

O New-Alias cmdlet tem um conjunto de parâmetros, mas muitos cmdlets têm vários conjuntos de parâmetros. 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. Se os parâmetros não puderem ser usados no mesmo comando, eles aparecerão em conjuntos de parâmetros separados.

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

Get-Random [[-Maximum] <Object>] [-Minimum <Object>] [-SetSeed <int>]
[<CommonParameters>]

Get-Random [-InputObject] <Object[]> [-Count <int>] [-SetSeed <int>]
[<CommonParameters>]

O primeiro conjunto de parâmetros, que retorna um número aleatório, tem os parâmetros Mínimo e Máximo . O segundo conjunto de parâmetros, que retorna um objeto selecionado aleatoriamente de um conjunto de objetos, inclui os parâmetros InputObject e Count . Ambos os conjuntos de parâmetros têm o parâmetro SetSeed e os parâmetros comuns.

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

Você indica qual conjunto de parâmetros deseja usar usando os parâmetros nesse conjunto de parâmetros.

No entanto, 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, Windows PowerShell pressupõe que você está usando o conjunto de parâmetros Number e retorna um número aleatório.

Em cada conjunto de parâmetros, os parâmetros aparecem na ordem de posição. A ordem dos parâmetros em um comando só importa quando você omite os nomes de parâmetro opcionais. Quando os nomes de parâmetro 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.

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. Ele também usa símbolos para mostrar como construir um comando válido.

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 New-Alias, digite:
```
-Name
```
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 ele descreve.

Colchetes angulares são usados para identificar o tipo .NET do valor que um parâmetro usa. Por exemplo, para usar o parâmetro Name do New-Alias cmdlet, substitua o <string> por uma cadeia de caracteres, que é uma única palavra ou um grupo de palavras entre aspas.
Colchetes [ ] indicam itens opcionais. Um parâmetro e seu valor podem ser opcionais ou o nome de um parâmetro necessário pode ser opcional.

Por exemplo, o parâmetro Description de New-Alias e seu valor são colocados entre colchetes porque ambos são opcionais.
```
[-Description <string>]
```
Os colchetes também indicam que o valor <string> do parâmetro Name é necessário, mas o nome do parâmetro, "Name", é opcional.
```
[-Name] <string>
```
Um colchete [] direito e esquerdo acrescentado a um tipo .NET indica que o parâmetro pode aceitar um ou vários valores desse tipo. Digite os valores em uma lista separada por vírgulas.

Por exemplo, o parâmetro Name do New-Alias cmdlet usa apenas uma cadeia de caracteres, mas o parâmetro Name de Get-Process pode usar uma ou muitas cadeias de caracteres.
```
New-Alias [-Name] <string>

New-Alias -Name MyAlias
```
```
Get-Process [-Name] <string[]>

Get-Process -Name Explorer, Winlogon, Services
```
{} 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 :
```
-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".
```
-Option ReadOnly
```

Itens opcionais

Colchetes [] envolvem itens opcionais. Por exemplo, na New-Alias descrição da sintaxe do cmdlet, o parâmetro Scope é opcional. Isso é indicado na sintaxe pelos colchetes ao redor do nome e do tipo do parâmetro:

[-Scope <string>]

Ambos os exemplos a seguir são usos corretos do New-Alias cmdlet :

New-Alias -Name utd -Value Update-TypeData
New-Alias -Name utd -Value Update-TypeData -Scope Global

Um nome de parâmetro pode ser opcional mesmo se o valor desse parâmetro for necessário. Isso é indicado na sintaxe pelos colchetes ao redor do nome do parâmetro, mas não pelo tipo de parâmetro, como neste exemplo do New-Alias cmdlet:

[-Name] <string> [-Value] <string>

Os comandos a seguir usam corretamente o New-Alias cmdlet . Os comandos produzem o mesmo resultado.

New-Alias -Name utd -Value Update-TypeData
New-Alias -Name utd Update-TypeData
New-Alias utd -Value Update-TypeData
New-Alias utd Update-TypeData

Se o nome do parâmetro não estiver incluído na instrução como digitado, Windows PowerShell tentará usar a posição dos argumentos para atribuir os valores aos parâmetros.

O exemplo a seguir não está completo:

New-Alias utd

Esse cmdlet requer valores para os parâmetros Name e Value .

Em exemplos de sintaxe, os colchetes também são usados na nomenclatura e na conversão para tipos de .NET Framework. Nesse contexto, colchetes não indicam que um elemento é opcional.

Share via