Compartilhar via


about_Commonparameters

TÓPICO
    about_CommonParameters

DESCRIÇÃO RESUMIDA
    Descreve os parâmetros que podem ser usados com qualquer cmdlet.


DESCRIÇÃO LONGA
    Os parâmetros comuns são um conjunto de parâmetros de cmdlet que 
    você pode usar com qualquer cmdlet. Eles são implementados pelo 
    Windows PowerShell, não pelo desenvolvedor do cmdlet, e ficam 
    automaticamente disponíveis para qualquer cmdlet.


    Você pode usar os parâmetros comuns com qualquer cmdlet, mas 
    talvez eles não tenham efeitos sobre todos os cmdlets. Por 
    exemplo, se um cmdlet não gerar uma saída detalhada, usar o 
    parâmetro comum Verbose não terá qualquer efeito.


    Vários parâmetros comuns substituem padrões ou preferências do 
    sistema que você define usando as variáveis de preferência do Windows 
    PowerShell. Ao contrário das variáveis de preferência, os parâmetros 
    comuns afetam apenas os comandos nos quais são usados.
 
    
    Além dos parâmetros comuns, muitos cmdlets oferecem os parâmetros 
    de redução de risco WhatIf e Confirm. Os cmdlets que envolvem 
    risco para o sistema ou para os dados de usuários normalmente 
    oferecem esses parâmetros.


    Os parâmetros comuns são:


       -Verbose
       -Debug
       -WarningAction
       -WarningVariable
       -ErrorAction
       -ErrorVariable
       -OutVariable
       -OutBuffer  

 
    Os parâmetros de redução de risco são:


       -WhatIf
       -Confirm


    Para obter mais informações sobre variáveis de preferência, digite:

  
       help about_preference_variables


  Descrições de parâmetros comuns       

    -Verbose[:{$true | $false}]

        Exibe informações detalhadas sobre a operação executada pelo 
        comando. Essas informações são semelhantes às encontradas em 
        um log de rastreamento ou de transação. Esse parâmetro só funciona 
        quando o comando gera uma mensagem detalhada. Por exemplo, esse 
        parâmetro funciona quando um comando contém o cmdlet Write-Verbose.
        
        O parâmetro Verbose substitui o valor da variável 
        $VerbosePreference para o comando atual. Como o valor padrão 
        da variável $VerbosePreference é SilentlyContinue, as mensagens 
        detalhadas não são exibidas por padrão.

        Valores válidos:

            $true (-Verbose:$true) tem o mesmo efeito que -Verbose.

            $false (-Verbose:$false) suprime a exibição da mensagem 
            detalhada. Use esse parâmetro quando o valor de $ 
            VerbosePreference não for SilentlyContinue (o padrão). 



    -Debug[:{$true | $false}]

        Exibe detalhes no nível do programador sobre a operação 
        executada pelo comando. Esse parâmetro só funciona quando o 
        comando gera uma mensagem de depuração. Por exemplo, esse 
        parâmetro funciona quando um comando contém o cmdlet Write-Debug.
    
        O parâmetro Debug substitui o valor da variável 
        $DebugPreference para o comando atual. Como o valor padrão da 
        variável $DebugPreference é SilentlyContinue, as mensagens de 
        depuração não são exibidas por padrão.
       
        Valores válidos:

            $true (-Debug:$true). Tem o mesmo efeito que -Debug.

            $false (-Debug:$false). Suprime a exibição de mensagens 
            de depuração quando o valor de $DebugPreference não é 
            SilentlyContinue (o padrão). 



    -WarningAction[:{SilentlyContinue | Continue | Inquire | Stop}]  

        Determina como o cmdlet responde a um aviso do comando.
        "Continue" é o valor padrão. Esse parâmetro só funciona 
        quando o comando gera uma mensagem de aviso. Por exemplo, 
        esse parâmetro funciona quando um comando contém o cmdlet 
        Write-Warning.

        O parâmetro WarningAction substitui o valor da variável 
        $WarningPreference para o comando atual. Como o valor padrão da variável 
        $WarningPreference é Continue, são exibidos avisos e a execução 
        continua a menos que você use o parâmetro WarningAction. 

         Valores válidos:

            SilentlyContinue. Suprime a mensagem de aviso e continua 
            executando o comando.

            Continue. Exibe a mensagem de aviso e continua executando 
            o comando. "Continue" é o valor padrão.
 
            Inquire. Exibe a mensagem de aviso e solicita sua 
            confirmação antes de continuar a execução. Esse valor 
            raramente é usado.

            Stop. Exibe a mensagem de aviso e para de executar o comando.



    -WarningVariable [+]<nome-da-variável>

        Armazena avisos sobre o comando na variável especificada.

        Para acrescentar os avisos ao conteúdo da variável, em vez de 
        substituir avisos que talvez já estejam armazenados, digite 
        um sinal de adição (+) antes do nome da variável. 

        Por exemplo, o comando a seguir cria a variável $a e armazena 
        qualquer aviso nela:

            get-process -id 6 -WarningVariable a  

        O comando a seguir adiciona avisos à variável $a:

            get-process -id 2 -WarningVariable +a 

        O comando a seguir exibe o conteúdo de $a:

            $a                                     

        Você pode usar esse parâmetro para criar uma variável que 
        contém apenas avisos de comandos específicos. Você pode usar 
        a notação de matriz, como $a[0] ou $warning[1,2] para fazer 
        referência a avisos específicos armazenados na variável.


    -ErrorAction[:{SilentlyContinue | Continue | Inquire | Stop)]  

        Determina como o cmdlet responde a um erro de não-encerramento do 
        comando. Esse parâmetro só funciona quando o comando gera uma mensagem 
        de depuração. Por exemplo, esse parâmetro funciona quando um comando 
        contém o cmdlet Write-Error.

        O parâmetro ErrorAction substitui o valor da variável 
        $ErrorActionPreference para o comando atual. Como o valor padrão da 
        variável $ErrorActionPreference é Continue, são exibidas mensagens de 
        erro e a execução continua a menos que você use o parâmetro ErrorAction. 

        O parâmetro ErrorAction não tem efeito sobre erros de 
        encerramento (como dados perdidos, parâmetros inválidos ou 
        permissões insuficientes) que impedem a execução bem-sucedida 
        de um comando.

        Valores válidos:

            SilentlyContinue. Suprime a mensagem de erro e continua 
            executando o comando.

            Continue. Exibe a mensagem de erro e continua executando 
            o comando. "Continue" é o valor padrão.
 
            Inquire. Exibe a mensagem de erro e solicita sua 
            confirmação antes de continuar a execução. Esse valor 
            raramente é usado.

            Stop. Exibe a mensagem de erro e para de executar o comando.

            
    -ErrorVariable [+]<nome-da-variável>

        Armazena mensagens de erro sobre o comando na variável 
        especificada e na variável automática $Error. Para obter mais 
        informações, digite o seguinte comando:

            get-help about_automatic_variables

        Por padrão, novas mensagens de erro substituem mensagens de 
        erro que já estão armazenadas na variável. Para acrescentar a 
        mensagem de erro ao conteúdo da variável, digite um sinal de 
        adição (+) antes do nome da variável. 

        Por exemplo, o comando a seguir cria a variável $a e armazena 
        qualquer erro nela:

            get-process -id 6 -ErrorVariable a

        O comando a seguir adiciona mensagens de erro à variável $a:


            get-process -id 2 -ErrorVariable +a

        O comando a seguir exibe o conteúdo de $a:

            $a                                     

        Você pode usar esse parâmetro para criar uma variável que 
        contém apenas mensagens de erro de comandos específicos. A 
        variável automática $Error contém mensagens de erro de todos 
        os comandos na sessão.Você pode usar a notação de matriz, 
        como $a[0] ou $error[1,2] para fazer referência a erros 
        específicos armazenados nas variáveis.


    -OutVariable [+]<nome-da-variável>

        Armazena objetos de saída do comando na variável especificada 
        e a exibe na linha de comando.

        Para adicionar a saída à variável, em vez de substituir 
        qualquer saída que já possa estar armazenada nela, digite um 
        sinal de adição (+) antes do nome da variável. 

        Por exemplo, o comando a seguir cria a variável $out e 
        armazena o objeto de processo nela:

            get-process powershell -OutVariable out   

        O comando a seguir adiciona o objeto de processo à variável $out:

            get-process iexplore -OutVariable +out 

        O comando a seguir exibe o conteúdo da variável $out.

            $out                                         


    -OutBuffer <Int32>

        Determina o número de objetos a serem acumulados em um buffer 
        antes de enviar qualquer objeto pelo pipeline. Se você omitir esse 
        parâmetro, os objetos serão enviados depois de gerados. 
        Esse parâmetro de gerenciamento de recursos foi criado para 
        usuários avançados.

        Quando você usa esse parâmetro, o Windows PowerShell só chama 
        o próximo cmdlet no pipeline quando o número de objetos 
        gerados é igual a OutBuffer + 1. Depois disso, ele envia todos os 
        objetos assim que são gerados.

        
  Descrições de parâmetros de gerenciamento de riscos  
       
    -WhatIf[:{$true | $false}]
        Exibe uma mensagem que descreve o efeito do comando, em vez 
        de executá-lo.

        O parâmetro WhatIf substitui o valor da variável 
        $WhatIfPreference para o comando atual. Como o valor padrão 
        da variável $WhatIfPreference é 0 (desabilitado), o 
        comportamento de WhatIf não é executado sem o parâmetro 
        WhatIf. Para obter mais informações, digite o seguinte comando:

            get-help about_preference_variables



        Valores válidos:

            $true (-WhatIf:$true). Tem o mesmo efeito que -WhatIf.           
            $false (-WhatIf:$false). Suprime o comportamento automático de 
            WhatIf que ocorre quando o valor da variável $WhatIfPreference é 1. 

        Por exemplo, o comando a seguir usa o parâmetro WhatIf em um 
        comando Remove-Item:

            PS> remove-item date.csv -whatif

        Em vez de remover o item, o Windows PowerShell lista as 
        operações que executaria e os itens que seriam afetados. Esse 
        comando gera a seguinte saída:

            Whatif: Realizando a operação "Remover Arquivo" no 
            Destino "C:\ps-test\date.csv".

        
    -Confirm[:{$true | $false}]
        Solicita confirmação antes da execução do comando.

        O parâmetro Confirm substitui o valor da variável 
        $ConfirmPreference para o comando atual. O valor padrão é 
        High. Para obter mais informações, digite o seguinte comando:

            get-help about_preference_variables 
        Valores válidos:

            $true (-WhatIf:$true). Tem o mesmo efeito que -Confirm.

            $false(-Confirm:$false). Suprime a confirmação automática 
            que ocorre quando o valor da variável $ConfirmPreference 
            é menor ou igual ao risco estimado do cmdlet. 

        Por exemplo, o comando a seguir usa o parâmetro Confirm com 
        um comando Remove-Item. Antes de remover o item, o Windows 
        PowerShell lista as operações que executaria e os itens que seriam 
        afetados e solicita aprovação.

            PS C:\ps-test> remove-item tmp*.txt -confirm

        Esse comando gera a seguinte saída:

            Confirm
            Tem certeza de que deseja executar esta ação?
            Realizando a operação "Remover Arquivo" no Destino " C:\ps-
            test\tmp1.txt [S] Sim [A] Sim para Todos [N] Não [T] Não para Todos 
            [U] Suspender [?] Ajuda (o padrão é "S"):


CONSULTE TAMBÉM
    about_Preference_Variables
    Write-Debug
    Write-Warning
    Write-Error
    Write-Verbose