TÓPICO
about_Parameters
DESCRIÇÃO RESUMIDA
Descreve como trabalhar com os parâmetros cmdlet no Windows PowerShell.
DESCRIÇÃO LONGA
A maioria dos cmdlets e das funções do Windows PowerShell contam
com os parâmetros para permitir aos usuários selecionar opções ou
fornecer entrada. Os parâmetros seguem o nome do cmdlet ou da função e
normalmente têm o seguinte formato:
-<nome_parâmetro> <valor_parâmetro>
O nome do parâmetro é precedido por um hífen (-), que indica ao
Windows PowerShell que a palavra após o hífen é um parâmetro e
não um valor que está sendo transmitido ao Cmdlet ou à função.
Nem todos os parâmetros exigem um valor, e nem todos os nomes de
parâmetros devem ser especificados. Em alguns casos, o nome do
parâmetro está implícito e não há necessidade de incluí-lo
explicitamente no comando.
O tipo de parâmetros e os requisitos para esses parâmetros variam
por Cmdlet e por função e de cmdlet para cmdlet. Para localizar
informações sobre os parâmetros de um cmdlet, 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 localizar informações sobre os parâmetros de uma função,
revise as definições de parâmetro. Os parâmetros são definidos
depois do nome de função ou dentro do corpo da função, usando a
palavra-chave Param. Para obter mais informações, consulte
about_Functions.
Algumas funções também contêm Ajuda baseada em comentário sobre
parâmetros. Use o cmdlet Get-Help com estas funções. Para obter mais
informações, consulte o tópico da ajuda para Get-Help e
about_Comment_Based_Help.
O cmdlet Get-Help retorna vários detalhes sobre o cmdlet ou a função,
inclusive uma descrição do cmdlet ou da função, a sintaxe de comando,
informações sobre os parâmetros e exemplos que mostram como usar o
cmdlet ou a função.
Você também pode usar o parâmetro Parameter do cmdlet Get-Help ou
da função para localizar informações sobre um parâmetro
específico. Ou é possível usar o caractere curinga (*) com o parâmetro
Parameter para localizar informações sobre todos os parâmetros do
cmdlet ou da função. Por exemplo, o comando a seguir obtém
informações sobre todos os parâmetros do cmdlet Get-Member ou da função:
get-help get-member -parameter *
Essa informação inclui os detalhes necessários para saber como usar o
parâmetro. Por exemplo, o tópico da Ajuda para o cmdlet Get-ChildItem
inclui os seguintes detalhes sobre seu parâmetro Path:
-path <string[]>
Especifica o caminho de um ou mais locais. São permitidos
caracteres curinga. O local padrão é o diretório atual (.).
Necessário? false
Posição? 1
Valor padrão Diretório atual
Aceitar entrada do pipeline? true (ByValue, ByPropertyName)
Aceitar caracteres curinga? true
As informações de parâmetro incluem a sintaxe de parâmetro, uma
descrição do parâmetro e os atributos do parâmetro.
As seções abaixo descrevem os atributos do parâmetro.
Parâmetro necessário?
Essa configuração indica se o parâmetro é obrigatório, isto é, se
todos os comandos que usam esse cmdlet devem incluir esse
parâmetro. Quando o valor é "True" e o parâmetro não está presente no
comando, o Windows PowerShell solicita a você um valor para o parâmetro.
Posição do parâmetro?
Essa configuração indica se você pode fornecer o valor de um
parâmetro sem precedê-lo com o nome do parâmetro. Se definido
como "0" ou "named", um nome de parâmetro será obrigatório. Esse
tipo de parâmetro é apresentado como um parâmetro nomeado. Um
parâmetro nomeado pode ser listado em qualquer posição depois do
nome do cmdlet.
Se a configuração "Posição do parâmetro?" for definida como um inteiro
diferente de 0, o nome do parâmetro não será necessário. Esse tipo de
parâmetro é denominado parâmetro posicional, e o número indica a
posição em que o parâmetro deverá ser exibido em relação aos outros
parâmetros posicionais. Se incluir o nome do parâmetro para um parâmetro
posicional, o parâmetro poderá ser listado em qualquer posição depois
do nome do cmdlet.
Por exemplo, o cmdlet Get-ChildItem tem os parâmetros Path e
Exclude. A configuração "Posição do parâmetro?" para Path é 1, o que
significa que é um parâmetro posicional. A configuração "Posição do
parâmetro"? para Exclude é 0, o que significa que é um parâmetro nomeado.
Isso significa que Path não requer o nome de parâmetro, mas seu
valor de parâmetro deve ser o primeiro ou somente o valor de
parâmetro sem nome no comando. Porém, porque o parâmetro Exclude é um
parâmetro nomeado, você pode colocar isto em qualquer posição no comando.
Como resultado das configurações "Posição do parâmetro?" para
esses dois parâmetros, é possível usar um destes 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 fosse necessário incluir outro parâmetro posicional sem
incluir o nome do parâmetro, aquele parâmetro teria que ser
colocado na ordem especificada pela configuração "Posição do
parâmetro?".
Tipo de parâmetro
Essa configuração especifica o tipo do valor de parâmetro do
Microsoft .NET Framework. Por exemplo, se o tipo for Int32, o valor de
parâmetro deverá ser um inteiro. Se o tipo for cadeia de caracteres,
o valor de parâmetro deverá ser uma cadeia de caracteres. Se a cadeia
de caracteres contiver espaços, o valor deverá ser colocado entre aspas,
ou os espaços devem ser precedidos pelo caractere inverso (`).
Valor padrão
Essa configuração especifica o valor que o parâmetro assumirá,
caso não seja fornecido nenhum 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á nenhum padrão porque o parâmetro não terá
nenhum efeito se não for usado.
Aceita vários valores?
Essa configuração indica se um parâmetro aceita vários valores de
parâmetros. Quando um parâmetro aceitar diversos valores, você poderá
digitar uma lista separada por vírgula como o valor do parâmetro no
comando ou salvar uma lista separada por vírgula (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
diversos valores. Os comandos a seguir são válidos:
get-service -servicename winrm, netlogon
$s = "winrm", "netlogon"
get-service -servicename $s
Aceita entrada do pipeline?
Essa configuração indica se você pode usar o operador de pipeline
(|) para enviar um valor ao parâmetro.
Valor Descrição
----- -----------
False Indica que você não pode enviar um valor ao
parâmetro.
True (by Value) Indica que você pode enviar qualquer valor ao
parâmetro, apenas para que o valor tenha o tipo
do .NET Framework especificado para o parâmetro
ou o valor possa ser convertido para o tipo
do .NET Framework especificado.
Quando um parâmetro é "True (by Value)",
o Windows PowerShell tenta associar
qualquer valor enviado com aquele
parâmetro antes de tentar outros métodos para
interpretar o comando.
True (by Property Name) Indica que você pode enviar um valor ao parâmetro,
mas o tipo de parâmetro do .NET Framework deve
incluir uma propriedade com o mesmo nome do parâmetro.
Por exemplo, você pode enviar um valor a um
parâmetro Name somente quando o valor tiver uma
propriedade chamada "Name".
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
corresponder a mais de um item existente no contêiner de destino.
Parâmetros comuns
Os parâmetros comuns são parâmetros que você pode usar com
qualquer cmdlet.
Para obter mais informações sobre parâmetros comuns, digite:
help about_commonparameters
CONSULTE TAMBÉM
about_Command_syntax
about_Comment_Based_Help
about_Functions_Advanced
about_Pipelines
about_Wildcards