about_Command_Syntax

Aplica-se a: Windows PowerShell 2.0, Windows PowerShell 3.0

Insira a introdução aqui.

TÓPICO

about_Command_Syntax

DESCRIÇÃO BREVE

Descreve os diagramas de sintaxe usados em Windows 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 um formulário válido do comando.

Para construir um comando, execute 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 Windows 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> 

A seguir está a sintaxe para o 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 está em maiúsculas para melhor legibilidade, mas Windows PowerShell diferencia maiúsculas de minúsculas.

O diagrama de sintaxe tem os seguintes elementos.

NOME DO COMANDO

------------

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

PARÂMETROS

----------

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

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

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

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

        -Name

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

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

VALORES DE PARÂMETRO

----------------

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

Por exemplo, o parâmetro Name de Get-Help tem um valor de cadeia de caracteres, que é uma cadeia de caracteres de texto, como uma única palavra ou diversas palavras entre aspas.

        [-Name] <string>

O tipo .NET de um valor de parâmetro está entre colchetes angulares (< >) para indicar que é 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 de tipo .NET por um objeto que tem o tipo .NET específico.

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

        -Name MyAlias

PARÂMETROS SEM VALORES

-------------------------

Alguns parâmetros não aceitam entrada, então eles não têm um valor de parâmetro. Parâmetros sem valores são chamados "parâmetros de opção" porque eles funcionam como comutadores liga/desliga. Você pode incluí-los (ativá-los) ou você pode omiti-los (desativá-los) de um comando.

Para usar um parâmetro de opção, digite o nome do parâmetro, precedido por um hífen.

Por exemplo, para usar o parâmetro WhatIf do cmdlet New-Alias, 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âmetro se parecem com parágrafos de um diagrama de sintaxe.

O cmdlet New-Alias tem um parâmetro definido, mas muitos cmdlets têm vários conjuntos de parâmetros. Alguns dos parâmetros de cmdlet são exclusivos para um conjunto de parâmetros, e os demais aparecem em vários conjuntos de parâmetros.

Cada conjunto de parâmetro representa o formato de um comando válido. Um conjunto de parâmetros inclui somente os parâmetros que podem ser usados juntos em um comando. Se os parâmetros não podem ser usados no mesmo comando, eles aparecem em conjuntos de parâmetros separados.

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

        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 Minimum e Maximum. O segundo conjunto de parâmetros, que retorna um objeto selecionado aleatoriamente de um conjunto de objetos, inclui os parâmetros InputObject e Count. Os dois conjuntos de parâmetros têm o parâmetro Set-Seed 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 você não pode usar os parâmetros Maximum e Count no mesmo comando.

Indique qual conjunto de parâmetros que deseja usar, usando os parâmetros nesse conjunto de parâmetro.

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 os parâmetros que são exclusivos para 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 da posição. A ordem dos parâmetros em um comando importa somente quando você omite os nomes de parâmetros opcionais. Quando nomes de parâmetro são omitidos, o Windows PowerShell atribui valores aos parâmetros por posição e tipo. Para obter informações sobre posição de parâmetros, 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 símbolos a seguir:

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

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

           -Name 

– Colchetes angulares (<>) indicam o texto do espaço reservado. Não digite os colchetes angulares ou o texto de 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 leva. Por exemplo, para usar o parâmetro Name do cmdlet New-Alias, substitua <string> pela 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 está entre colchetes porque são ambos opcionais.

   [-Description <string>]

Os parênteses indicam que o valor do parâmetro Name (<string>) é necessário, mas o nome do parâmetro "Name" é opcional.

         [-Name] <string>

-- Um colchete direito e esquerdo ([]) anexado a um tipo .NET indica que o parâmetro pode aceitar um ou vários valores do mesmo tipo. Digite os valores em uma lista separada por vírgulas.

Por exemplo, o parâmetro Name do cmdlet New-Alias usa apenas uma cadeia de caracteres, mas o parâmetro Name de Get-Process pode ter uma ou mais 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 de chaves são separados por barras verticais (|). Essas barras indicam uma escolha "exclusivo ou", o que significa que você pode escolher apenas um valor do conjunto de valores que são listados dentro das chaves.

Por exemplo, a sintaxe para o cmdlet New-Alias inclui a seguinte enumeração do valor para o parâmetro Option:

          -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.

          -Option ReadOnly

ITENS OPCIONAIS

Colchetes ([]) indicam itens opcionais. Por exemplo, na descrição de sintaxe do cmdlet New-Alias, o parâmetro Scope é opcional. Isso é indicado na sintaxe por colchetes em torno do nome do parâmetro e tipo:

          [-Scope <string>]

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

          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 para esse parâmetro for necessário. Isso é indicado na sintaxe por colchetes em torno do nome do parâmetro, mas não o tipo de parâmetro, como no exemplo do cmdlet New-Alias:

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

Os comandos a seguir usam corretamente o cmdlet New-Alias. 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 está incluído na instrução como digitado, o Windows PowerShell tenta usar a posição dos argumentos para atribuir os valores para parâmetros.

O exemplo a seguir não é completo:

          New-Alias utd

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

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

PALAVRAS-CHAVE

about_Symbols

about_Punctuation

about_Help_Syntax

CONSULTE TAMBÉM

about_Parameters

Get-Command

Get-Help