about_Parameters
Aplica-se a: Windows PowerShell 2.0, Windows PowerShell 3.0
TÓPICO
about_Parameters
DESCRIÇÃO BREVE
Descreve como trabalhar com parâmetros de comando no Windows PowerShell.
DESCRIÇÃO LONGA
A maioria dos comandos do Windows PowerShell, como cmdlets, funções e scripts, conta com parâmetros para permitir que os usuários selecionem opções ou façam contribuições. Os parâmetros seguem o nome do comando e têm o seguinte formato:
-<parameter_name> <parameter_value>
O nome do parâmetro é precedido por um hífen (-), que sinaliza para o Windows PowerShell que a palavra após o hífen é um nome de parâmetro. Alguns parâmetros não precisam ou aceitam um valor. 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 são variáveis. Para obter informações sobre os parâmetros de um comando, use o cmdlet Get-Help. Por exemplo, para localizar informações sobre os parâmetros do cmdlet Get-ChildItem, digite:
Get-Help Get-ChildItem
Para obter 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 cmdlet Get-Help retorna 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 usar os parâmetros em um comando.
Você também pode usar o parâmetro Parameter do cmdlet Get-Help para obter informações sobre um determinado parâmetro. Ou pode usar o parâmetro Parameter com o valor do caractere curinga (*) para localizar 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 cmdlet Get-Member:
Get-Help Get-Member -Parameter *
VALORES PADRÃO DO PARÂMETRO
Os parâmetros opcionais têm um valor padrão, que é o valor usado ou suposto quando o parâmetro não é especificado no comando.
Por exemplo, o valor padrão do parâmetro ComputerName de vários 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 padrão do parâmetro, consulte o tópico de ajuda para o cmdlet. A descrição do parâmetro deve incluir o valor padrão.
Você também pode configurar um valor padrão personalizado para qualquer parâmetro de um cmdlet ou uma função avançada. Para obter informações sobre como configurar valores padrão personalizados, consulte about_Parameters_Default_Values.
TABELA DE ATRIBUTOS DO PARÂMETRO
Quando você usa os parâmetros Full, Parameter ou Online do cmdlet Get-Help, o Get-Help exibe uma tabela de atributos 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 de ajuda para o cmdlet Get-ChildItem 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? 1
Default value Current directory
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? true
As informações de 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 do parâmetro.
PARAMETER REQUIRED?
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 for "True" e o parâmetro estiver ausente do comando, o Windows PowerShell solicita um valor para o parâmetro.
PARAMETER POSITION?
Essa configuração indica se você pode fornecer o valor de um parâmetro sem precedê-lo com o nome do parâmetro. Se ela for configurada como "0" ou "named", é necessário fornecer um nome de parâmetro. Esse tipo de parâmetro é chamado de parâmetro nomeado. Um parâmetro nomeado pode ser listado em qualquer posição após o nome do cmdlet.
Se a configuração "Parameter position?" for definida para um número inteiro diferente de 0, o nome do parâmetro não é necessário. Esse tipo de parâmetro é conhecido como parâmetro posicional, e o número indica a posição na qual o parâmetro deve aparecer em relação aos outros parâmetros posicionais. Se você incluir o nome para um parâmetro posicional, o parâmetro pode ser listado em qualquer posição após o nome do cmdlet.
Por exemplo, o cmdlet Get-ChildItem tem parâmetros Path e Exclude. A configuração "Parameter position?" de Path é 1, o que significa que ele é um parâmetro posicional. A configuração "Parameter position?" de Exclude é 0, o que significa que ele é um parâmetro nomeado.
Isso significa que Path não exige 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, já que o parâmetro Exclude é um parâmetro nomeado, você poderá colocá-lo em qualquer posição no comando.
Como resultado das configurações "Parameter position?" desses 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ê quiser incluir outro parâmetro posicional sem incluir o nome do parâmetro, esse parâmetro precisaria ser colocado na ordem especificada pela configuração "Parameter Position?".
PARAMETER TYPE
Essa 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 número 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 (').
DEFAULT VALUE
Essa configuração especifica o valor que o parâmetro assumirá se nenhum outro valor for fornecido. Por exemplo, geralmente, o valor padrão do parâmetro Path é o diretório atual. Os parâmetros obrigatórios nunca têm um valor padrão. Para muitos parâmetros opcionais, não há nenhum padrão porque o parâmetro não tem nenhum efeito se não for usado.
ACCEPTS MULTIPLE VALUES?
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 ServiceName do cmdlet Get-Service aceita vários valores. Os comandos a seguir são válidos:
get-service -servicename winrm, netlogon
$s = "winrm", "netlogon"
get-service -servicename $s
ACCEPTS PIPELINE INPUT?
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.
When a parameter is "True (by Value)", Windows
PowerShell tries to associate any piped values
with that parameter before it tries other methods
to interpret the command.
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.
For example, you can pipe a value to a Name
parameter only when the value has a property
called "Name".
ACCEPTS WILDCARD CHARACTERS?
Essa configuração indica se o valor do parâmetro pode conter caracteres curinga para que o valor do parâmetro possa ser combinado com mais de um item existente no contêiner de destino.
COMMON PARAMETERS
Parâmetros comuns são parâmetros que podem ser usados com qualquer cmdlet. Para obter mais informações sobre os parâmetros comuns, consulte about_CommonParameters.
CONSULTE TAMBÉM
about_Command_syntax
about_Comment_Based_Help
about_Functions_Advanced
about_Parameters_Default_Values
about_Pipelines
about_Wildcards