Sobre a sintaxe de comando
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, colchetes também são usados na nomenclatura e conversão para tipos de .NET Framework. Nesse contexto, colchetes não indicam que um elemento é opcional.