Sobre Parâmetros

Breve descrição

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

Longa descrição

A maioria dos comandos PowerShell, tais como cmdlets, funções e scripts, dependem de parâmetros para permitir que os utilizadores selecionem opções ou forneçam entrada. Os parâmetros seguem o nome de comando e têm o seguinte formulário:

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

O nome do parâmetro é precedido por um hífen (-), que indica 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 um personagem do cólon. Alguns parâmetros não requerem ou aceitam um valor de parâmetro. Outros parâmetros requerem um valor, mas não requerem 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, utilize o Get-Help cmdlet. Por exemplo, para encontrar informações sobre os parâmetros do Get-ChildItem cmdlet, escreva:

Get-Help Get-ChildItem

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

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

O Get-Help cmdlet devolve vários detalhes sobre o comando, incluindo uma descrição, a sintaxe de comando, informações sobre os parâmetros e exemplos que mostram como usar os parâmetros num comando.

Também pode utilizar o parâmetro do Get-Help cmdlet para encontrar informações sobre um determinado parâmetro. Ou, pode usar o parâmetro parâmetro com o caráter wildcard * () para encontrar informações sobre todos os parâmetros do comando. Por exemplo, o seguinte comando obtém informações sobre todos os parâmetros do Get-Member cmdlet:

Get-Help Get-Member -Parameter *

Valores de parâmetro padrão

Os parâmetros opcionais têm um valor predefinido, 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 encontrar o valor do parâmetro padrão, consulte o tópico de ajuda para o cmdlet. A descrição do parâmetro deve incluir o valor predefinido.

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 a definição de valores padrão personalizados, consulte about_Parameters_Default_Values.

Tabela de atributos de parâmetro

Quando utiliza os parâmetros Completos, Parâmetrosou Online do Get-Help cmdlet, Get-Help apresenta uma tabela de atributos de parâmetro com informações detalhadas sobre o parâmetro.

Estas informações incluem os detalhes que precisa de saber para utilizar o parâmetro. Por exemplo, o tópico de ajuda para o Get-ChildItem cmdlet inclui os seguintes detalhes sobre o seu parâmetro Caminho:

-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

A informação do parâmetro inclui a sintaxe do parâmetro, uma descrição do parâmetro e os atributos do parâmetro. As seguintes secções descrevem os atributos do parâmetro.

Parâmetro necessário

Esta definição indica se o parâmetro é obrigatório, ou seja, se todos os comandos que utilizam este cmdlet devem incluir este parâmetro. Quando o valor é verdadeiro e o parâmetro falta do comando, o PowerShell pede-lhe um valor para o parâmetro.

Posição do parâmetro

Se a Position regulação for definida para um inteiro positivo, o nome do parâmetro não é 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 cmdlet. Se incluir o nome do parâmetro para um parâmetro posicional, o parâmetro pode ser listado em qualquer posição após o nome cmdlet.

Por exemplo, o Get-ChildItem cmdlet tem parâmetros Caminho e Exclusão. A Position definição para Caminho é 0, o que significa que é um parâmetro posicional. A Position definição para Excluir está nomeada.

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

Como resultado das Position definições para estes dois parâmetros, pode utilizar 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 incluir outro parâmetro posicional sem incluir o nome do parâmetro, esse parâmetro deve ser colocado na ordem especificada pela Position definição.

Tipo de parâmetro

Esta definição especifica o tipo de quadro Microsoft .NET 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 corda de caracteres. Se a corda contiver espaços, o valor deve ser incluído em aspas, ou os espaços devem ser precedidos pelo carácter de fuga (' ).

Valor Predefinido

Esta definição especifica o valor que o parâmetro assumirá se não for fornecido outro valor. Por exemplo, o valor padrão do parâmetro Path é frequentemente 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 utilizado.

Aceita vários valores

Esta definição indica se um parâmetro aceita vários valores de parâmetros. Quando um parâmetro aceita vários valores, pode escrever uma lista separada de vírgula como o valor do parâmetro no comando, ou guardar uma lista separada de vírgula (uma matriz) numa variável e, em seguida, especificar a variável como o valor do parâmetro.

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

Get-Service -servicename winrm, netlogon

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

Aceita entrada de gasoduto

Esta definição indica se pode utilizar o operador do gasoduto | 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 é "Verdadeiro (por Valor)", a 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, só pode canalizar um valor para um parâmetro nome quando o valor tiver uma propriedade chamada Nome.

Nota

Um parâmetro dactilografado que aceita a entrada do gasoduto by Value () ou ( by PropertyName ) permite a utilização de blocos de script de ligação de atraso no parâmetro.

O bloco de scripts de ligação de atraso é executado automaticamente durante a ParâmetroBinding. O resultado está ligado ao parâmetro. A ligação de atraso não funciona para parâmetros definidos como tipo ScriptBlock ou , o bloco de System.Object scripts é passado sem ser invocado.

Você pode ler sobre blocos de scripts de atraso aqui about_Script_Blocks.md

Aceita personagens wildcard

Esta definição indica se o valor do parâmetro pode conter caracteres wildcard para que o valor do parâmetro possa ser igualado a mais do que um item existente no recipiente-alvo.

Parâmetros comuns

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