about_Parameters

Artigo
10/04/2023

Breve descrição

Descreve como trabalhar com parâmetros de comando no PowerShell.

Descrição longa

A maioria dos comandos do PowerShell, como cmdlets, funções e scripts, depende de parâmetros para permitir que os usuários selecionem opções ou forneçam entrada. Os parâmetros seguem o nome do comando e têm a seguinte forma:

-<parameter_name> <parameter_value>
-<parameter_name>:<parameter_value>

O nome do parâmetro é precedido por um hífen (-), que sinaliza ao PowerShell que a palavra que segue o hífen é um nome de parâmetro. O nome e o valor do parâmetro podem ser separados por um espaço ou dois pontos. Alguns parâmetros não exigem ou aceitam um valor de parâmetro. Outros parâmetros exigem um valor, mas não exigem o nome do parâmetro no comando.

O tipo de parâmetros e os requisitos para esses parâmetros variam. Para encontrar informações sobre os parâmetros de um comando, use o Get-Help cmdlet. Por exemplo, para encontrar informações sobre os parâmetros do Get-ChildItem cmdlet, digite:

Get-Help Get-ChildItem

Para encontrar informações sobre os parâmetros de um script, use o caminho completo para o arquivo de script. Por exemplo:

Get-Help $HOME\Documents\Scripts\Get-Function.ps1

O Get-Help cmdlet retorna vários detalhes sobre o comando, incluindo uma descrição, a sintaxe do comando, informações sobre os parâmetros e exemplos mostrando como usar os parâmetros em um comando.

Você também pode usar o parâmetro Parameter do Get-Help cmdlet para encontrar informações sobre um parâmetro específico. Ou, você pode usar o parâmetro Parameter com o valor do caractere curinga ( * ) para encontrar informações sobre todos os parâmetros do comando. Por exemplo, o comando a seguir obtém informações sobre todos os parâmetros do Get-Member cmdlet:

Get-Help Get-Member -Parameter *

Valores de parâmetros padrão

Os parâmetros opcionais têm um valor padrão, que é o valor que é usado ou assumido quando o parâmetro não é especificado no comando.

Por exemplo, o valor padrão do parâmetro ComputerName de muitos cmdlets é o nome do computador local. Como resultado, o nome do computador local é usado no comando, a menos que o parâmetro ComputerName seja especificado.

Para localizar o valor do parâmetro padrão, consulte o tópico da ajuda do cmdlet. A descrição do parâmetro deve incluir o valor padrão.

Você também pode definir um valor padrão personalizado para qualquer parâmetro de um cmdlet ou função avançada. Para obter informações sobre como definir valores padrão personalizados, consulte about_Parameters_Default_Values.

Tabela de atributos de parâmetros

Quando você usa os parâmetros Full, Parameter ou Online do Get-Help cmdlet, Get-Help exibe uma tabela de atributos de parâmetro com informações detalhadas sobre o parâmetro.

Essas informações incluem os detalhes que você precisa saber para usar o parâmetro. Por exemplo, o tópico da Ajuda do Get-ChildItem cmdlet inclui os seguintes detalhes sobre seu parâmetro Path:

-Path <string[]>
    Specifies a path of one or more locations. Wildcard characters are
    permitted. The default location is the current directory (.).

Required?                    false
Position?                    0
Default value                Current directory
Accept pipeline input?       true (ByValue, ByPropertyName)
Accept wildcard characters?  true

As informações do parâmetro incluem a sintaxe do parâmetro, uma descrição do parâmetro e os atributos do parâmetro. As seções a seguir descrevem os atributos de parâmetro.

Parâmetro necessário

Essa configuração indica se o parâmetro é obrigatório, ou seja, se todos os comandos que usam esse cmdlet devem incluir esse parâmetro. Quando o valor é True e o parâmetro está ausente do comando, o PowerShell solicita um valor para o parâmetro.

Posição do parâmetro

Se a Position configuração for definida como um número inteiro não negativo, o nome do parâmetro não será necessário. Este tipo de parâmetro é referido como um parâmetro posicional, e o número indica a posição em que o parâmetro deve aparecer em relação a outros parâmetros posicionais. Um parâmetro nomeado pode ser listado em qualquer posição após o nome do cmdlet. Se você incluir o nome do parâmetro para um parâmetro posicional, o parâmetro poderá ser listado em qualquer posição após o nome do cmdlet.

Por exemplo, o Get-ChildItem cmdlet tem parâmetros Path e Exclude. A Position configuração para Path é 0, o que significa que é um parâmetro posicional. A Position configuração para Excluir é nomeada.

Isso significa que Path não requer o nome do parâmetro, mas seu valor de parâmetro deve ser o primeiro ou o único valor de parâmetro sem nome no comando. No entanto, como o parâmetro Exclude é um parâmetro nomeado, você pode colocá-lo em qualquer posição no comando.

Como resultado das Position configurações para esses dois parâmetros, você pode usar qualquer um dos seguintes comandos:

Get-ChildItem -Path c:\techdocs -Exclude *.ppt
Get-ChildItem c:\techdocs -Exclude *.ppt
Get-ChildItem -Exclude *.ppt -Path c:\techdocs
Get-ChildItem -Exclude *.ppt c:\techdocs

Se você incluir outro parâmetro posicional sem incluir o nome do parâmetro, esse parâmetro deverá ser colocado na ordem especificada pela Position configuração.

Tipo de parâmetro

Esta configuração especifica o tipo Microsoft .NET Framework do valor do parâmetro. Por exemplo, se o tipo for Int32, o valor do parâmetro deve ser um inteiro. Se o tipo for string, o valor do parâmetro deve ser uma cadeia de caracteres. Se a cadeia de caracteres contiver espaços, o valor deve ser colocado entre aspas ou os espaços devem ser precedidos pelo caractere de escape (`).

Valor Predefinido

Essa configuração especifica o valor que o parâmetro assumirá se nenhum outro valor for fornecido. Por exemplo, o valor padrão do parâmetro Path geralmente é o diretório atual. Os parâmetros necessários nunca têm um valor padrão. Para muitos parâmetros opcionais, não há padrão porque o parâmetro não tem efeito se não for usado.

Aceita vários valores

Essa configuração indica se um parâmetro aceita vários valores de parâmetro. Quando um parâmetro aceita vários valores, você pode digitar uma lista separada por vírgulas como o valor do parâmetro no comando ou salvar uma lista separada por vírgulas (uma matriz) em uma variável e, em seguida, especificar a variável como o valor do parâmetro.

Por exemplo, o parâmetro Name do Get-Service cmdlet aceita vários valores. Os comandos a seguir são válidos:

Get-Service -Name winrm, netlogon

$s = "winrm", "netlogon"
Get-Service -Name $s

Aceita entrada de pipeline

Essa configuração indica se você pode usar o operador de pipeline (|) para enviar um valor para o parâmetro.

Value                    Description
-----                    -----------
False                    Indicates that you cannot pipe a value to the
                         parameter.

True (by Value)          Indicates that you can pipe any value to the
                         parameter, just so the value has the .NET
                         Framework type specified for the parameter or the
                         value can be converted to the specified .NET
                         Framework type.

Quando um parâmetro é "True (by Value)", o PowerShell tenta associar quaisquer valores canalizados a esse parâmetro antes de tentar outros métodos para interpretar o comando.

True (by Property Name)  Indicates that you can pipe a value to the
                         parameter, but the .NET Framework type of the
                         parameter must include a property with the same
                         name as the parameter.

Por exemplo, você pode canalizar um valor para um parâmetro Name somente quando o valor tiver uma propriedade chamada Name.

Nota

Um parâmetro tipado que aceita a entrada de pipeline (by Value) ou (by PropertyName) permite o uso de blocos de script de ligação de atraso no parâmetro.

O bloco de script delay-bind é executado automaticamente durante ParameterBinding. O resultado está vinculado ao parâmetro. A vinculação de atraso não funciona para parâmetros definidos como tipo ScriptBlock ou System.Object, o bloco de script é passado sem ser invocado.

Você pode ler sobre blocos de script de vinculação de atraso aqui about_Script_Blocks.md

Aceita caracteres curinga

Essa configuração indica se o valor do parâmetro pode conter caracteres curinga para que o valor do parâmetro possa ser correspondido a mais de um item existente no contêiner de destino.

Parâmetros comuns

Parâmetros comuns são parâmetros que você pode usar com qualquer cmdlet. Para obter mais informações sobre parâmetros comuns, consulte about_CommonParameters.

Partilhar via