Exclui o valor de uma variável.
Sintaxe
Clear-Variable [-Name] <string[]> [-Exclude <string[]>] [-Force] [-Include <string[]>] [-PassThru] [-Scope <string>] [-Confirm] [-WhatIf] [<CommonParameters>]
Descrição
O cmdlet Clear-Variable exclui os dados armazenados em uma variável, mas não exclui a variável. Como resultado, o novo valor da variável será NULL (vazio). Se a variável tiver dados especificados ou o tipo de objeto, Clear-Variable preservará o tipo do objeto armazenado na variável.
Parâmetros
-Exclude <string[]>
Omite os itens especificados. O valor desse parâmetro qualifica o parâmetro Name. Digite um elemento ou padrão do nome, como "s*". Os caracteres curinga são permitidos.
|
Necessário? |
false |
|
Posição? |
named |
|
Valor padrão |
|
|
Aceitar entrada do pipeline? |
false |
|
Aceitar caracteres curinga? |
false |
-Force
Permite que o cmdlet limpe uma variável mesmo se ela for somente leitura. Mesmo usando o parâmetro Force, o cmdlet não pode limpar as constantes.
|
Necessário? |
false |
|
Posição? |
named |
|
Valor padrão |
|
|
Aceitar entrada do pipeline? |
false |
|
Aceitar caracteres curinga? |
false |
-Include <string[]>
Limpa somente os itens especificados. O valor desse parâmetro qualifica o parâmetro Name. Digite um elemento ou padrão do nome, como "s*". Os caracteres curinga são permitidos.
|
Necessário? |
false |
|
Posição? |
named |
|
Valor padrão |
|
|
Aceitar entrada do pipeline? |
false |
|
Aceitar caracteres curinga? |
false |
-Name <string[]>
Especifica o nome da variável a ser limpa. Os caracteres curinga são permitidos. Esse parâmetro é obrigatório, mas seu nome ("Name") é opcional.
|
Necessário? |
true |
|
Posição? |
1 |
|
Valor padrão |
|
|
Aceitar entrada do pipeline? |
true (ByPropertyName) |
|
Aceitar caracteres curinga? |
false |
-PassThru
Retorna um objeto que representa a variável limpa. Por padrão, este cmdlet não gera nenhuma saída.
|
Necessário? |
false |
|
Posição? |
named |
|
Valor padrão |
|
|
Aceitar entrada do pipeline? |
false |
|
Aceitar caracteres curinga? |
false |
-Scope <string>
Especifica o escopo no qual este alias é válido. Os valores válidos são "Global", "Local" ou "Script" ou um número relativo ao atual escopo (0 ao número de escopos, onde 0 é o escopo atual e 1 é seu pai). "Local" é o padrão. Para obter mais informações, consulte about_Scopes.
|
Necessário? |
false |
|
Posição? |
named |
|
Valor padrão |
|
|
Aceitar entrada do pipeline? |
false |
|
Aceitar caracteres curinga? |
false |
-Confirm
Solicita confirmação antes da execução do comando.
|
Necessário? |
false |
|
Posição? |
named |
|
Valor padrão |
|
|
Aceitar entrada do pipeline? |
false |
|
Aceitar caracteres curinga? |
false |
-WhatIf
Descreve o que aconteceria se você executasse o comando, sem executá-lo de fato.
|
Necessário? |
false |
|
Posição? |
named |
|
Valor padrão |
|
|
Aceitar entrada do pipeline? |
false |
|
Aceitar caracteres curinga? |
false |
<CommonParameters>
Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.
Entradas e saídas
O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.
|
Entradas |
None Não é possível enviar objetos para Clear-Variable. |
|
Saídas |
None ou System.Management.Automation.PSVariable Quando você usa o parâmetro PassThru, Clear-Variable gera um objeto System.Management.Automation.PSVariable que representa a variável limpa. Caso contrário, esse cmdlet não gera nenhuma saída. |
Observações
Para excluir uma variável, juntamente com seu valor, use Remove-Variable ou Remove-Item.
Clear-Variable não excluirá os valores das variáveis que estiverem definidas como constantes ou sejam de propriedade do sistema, nem mesmo se você usar o parâmetro -Force.
Se a variável que estiver limpando não existir, o cmdlet não terá efeito. Ele não cria uma variável com um valor nulo.
Você também pode fazer referência a Clear-Variable usando seu alias interno, "clv". Para obter mais informações, consulte about_Aliases.
Exemplo 1
C:\PS>clear-variable my* -global Descrição ----------- Esse comando exclui o valor das variáveis globais iniciando com "my".
Exemplo 2
C:\PS>$a=3
C:\PS>&{ clear-variable a }
C:\PS>$a
3
Descrição
-----------
Estes comandos demonstram que a ação de limpar uma variável em um escopo filho não limpa o valor no escopo pai. O primeiro comando define o valor da variável $a para "3". O segundo comando usa o operador de invocação (&) para executar um comando Clear-Variable em um novo escopo. A variável é limpa no escopo filho (embora ele não exista), mas não é limpa no escopo local. O terceiro comando, que obtém o valor de $a, mostra que o valor "3" não é afetado.
Exemplo 3
C:\PS>clear-variable -name processes Descrição ----------- Esse comando exclui o valor da variável $processes. A variável $processes ainda existe, mas o valor é nulo.
See Also