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




Sumário