about_Parameters
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, dependem de parâmetros para permitir que os utilizadores selecionem opções ou forneçam entrada. Os parâmetros seguem o nome do 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 se segue ao hífen é um nome de parâmetro. O nome e o valor do parâmetro podem ser separados por um espaço ou um caráter de dois pontos. Alguns parâmetros não requerem nem 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, utilize o caminho completo para o ficheiro de 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 do comando, informações sobre os parâmetros e exemplos que mostram como utilizar os parâmetros num comando.
Também pode utilizar o parâmetro Parameter do Get-Help cmdlet para encontrar informações sobre um parâmetro específico. Em alternativa, pode utilizar o parâmetro Parameter com o valor caráter universal ( * ) 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âmetros predefinidos
Os parâmetros opcionais têm um valor predefinido, que é o valor que é utilizado ou assumido quando o parâmetro não é especificado no comando.
Por exemplo, o valor predefinido do parâmetro ComputerName de muitos cmdlets é o nome do computador local. Como resultado, o nome do computador local é utilizado no comando, a menos que o parâmetro ComputerName seja especificado.
Para localizar o valor do parâmetro predefinido, veja o tópico de ajuda do cmdlet . A descrição do parâmetro deve incluir o valor predefinido.
Também pode definir um valor predefinido personalizado para qualquer parâmetro de um cmdlet ou função avançada. Para obter informações sobre como definir valores predefinidos personalizados, consulte about_Parameters_Default_Values.
Tabela de atributos de parâmetros
Quando utiliza os parâmetros Completo, Parâmetro ou Online do Get-Help cmdlet, Get-Help apresenta uma tabela de atributos de parâmetros 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 do Get-ChildItem cmdlet inclui os seguintes detalhes sobre o respetivo 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 secções seguintes descrevem os atributos dos parâmetros.
Parâmetro Necessário
Esta definição indica se o parâmetro é obrigatório, ou seja, se todos os comandos que utilizam este cmdlet têm de incluir este parâmetro. Quando o valor é Verdadeiro e o parâmetro está em falta no comando, o PowerShell pede-lhe um valor para o parâmetro .
Posição do Parâmetro
Se a Position definição estiver definida para um número inteiro não negativo, 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 tem de 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 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 do cmdlet.
Por exemplo, o Get-ChildItem cmdlet tem os parâmetros Path e Exclude. A Position definição de Caminho é 0, o que significa que é um parâmetro posicional. A Position definição de Excluir tem o nome .
Isto significa que Path não requer o nome do parâmetro, mas o respetivo valor de parâmetro tem de ser o primeiro ou apenas valor de parâmetro sem nome no comando. No entanto, como o parâmetro Exclude é um parâmetro com nome, 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 tem de ser colocado na ordem especificada pela Position definição.
Tipo de Parâmetro
Esta definição especifica o tipo de .NET Framework Microsoft do valor do parâmetro. Por exemplo, se o tipo for Int32, o valor do parâmetro tem de ser um número inteiro. Se o tipo for cadeia, o valor do parâmetro tem de ser uma cadeia de carateres.
Se a cadeia contiver espaços, o valor tem de estar entre aspas ou os espaços têm de ser precedidos pelo caráter de escape (`).
Valor Predefinido
Esta definição especifica o valor que o parâmetro assumirá se não for fornecido outro valor. Por exemplo, o valor predefinido do parâmetro Path é, muitas vezes, o diretório atual. Os parâmetros necessários nunca têm um valor predefinido. Para muitos parâmetros opcionais, não existe uma predefinição porque o parâmetro não tem efeito se não for utilizado.
Aceita Múltiplos 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 por vírgulas como o valor do parâmetro no comando ou guardar uma lista separada por vírgulas (uma matriz) numa variável e, em seguida, especificar a variável como o valor do parâmetro.
Por exemplo, o parâmetro Nome do Get-Service cmdlet aceita vários valores. Os seguintes comandos são ambos válidos:
Get-Service -Name winrm, netlogon
$s = "winrm", "netlogon"
Get-Service -Name $s
Aceita Entrada de Pipeline
Esta definição indica se pode utilizar 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 é "Verdadeiro (por Valor)", 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, pode encaminhar um valor para um parâmetro Nome apenas quando o valor tiver uma propriedade chamada Nome.
Nota
Um parâmetro escrito que aceita entrada de pipeline (by Value) ou (by PropertyName) permite a utilização de blocos de script delay-bind no parâmetro .
O bloco de script delay-bind é executado automaticamente durante o ParameterBinding. O resultado está vinculado ao parâmetro . O enlace de atraso não funciona para parâmetros definidos como tipo ScriptBlock ou System.Object, o bloco de script é transmitido sem ser invocado.
Pode ler sobre os blocos de script de atraso-enlace aqui about_Script_Blocks.md
Aceita Carateres Universais
Esta definição indica se o valor do parâmetro pode conter carateres universais para que o valor do parâmetro possa ser correspondido a mais do que um item existente no contentor de destino.
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, veja about_CommonParameters.