Clear-Variable

 

SYNOPSIS

Deletes the value of a variable.

 

SYNTAX

Clear-Variable [-name] <string[]> [-include <string[]>] [-exclude <string[]>] [-scope <string>] [-force] [-passThru] [-whatIf] [-confirm] [<CommonParameters>]

 

DETAILED DESCRIPTION

The Clear-Variable cmdlet deletes the data stored in an variable, but it does not delete the variable. As a result, the value of the variable is NULL (empty). If the variable has a specified data or object type, Clear-Variable preserves the type of the object stored in the variable.

 

PARAMETERS

 

-include <string[]>

Clears only the specified items. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.

 

Required?

false

Position?

named

Default value

 

Accept pipeline input?  

false

Accept wildcard characters? 

true

 

-exclude <string[]>

Omits the specified items. The value of this parameter qualifies the Name parameter. Enter a name element or pattern, such as "s*". Wildcards are permitted.

 

Required?

false

Position?

named

Default value

 

Accept pipeline input?  

false

Accept wildcard characters? 

true

 

-scope <string>

Specifies the scope in which this alias is valid. Valid values are "Global", "Local", or "Script", or a number relative to the current scope (0 through the number of scopes, where 0 is the current scope and 1 is its parent). "Local" is the default. For more information, type "get-help about_scope".

 

Required?

false

Position?

named

Default value

local

Accept pipeline input?  

false

Accept wildcard characters? 

false

 

-force <SwitchParameter>

Overrides restrictions that prevent the command from succeeding, just so the changes do not compromise security. For example, Force will override the read-only attribute or create directories to complete a file path, but it will not attempt to change file permissions.

 

Required?

false

Position?

named

Default value

False

Accept pipeline input?  

false

Accept wildcard characters? 

false

 

-passThru <SwitchParameter>

Passes the object created by this cmdlet through the pipeline. By default, this cmdlet does not pass any objects through the pipeline.

 

Required?

false

Position?

named

Default value

False

Accept pipeline input?  

false

Accept wildcard characters? 

false

 

-name <string[]>

Specifies the name of the variable to be cleared. Wildcards are permitted. This parameter is required, but the parameter name ("-Name") is optional.

 

Required?

true

Position?

1

Default value

N/A - The Name must be specified

Accept pipeline input?  

true (ByPropertyName)

Accept wildcard characters? 

true

 

-whatIf

Describes what would happen if you executed the command without actually executing the command.

 

Required?

false

Position?

named

Default value

 

Accept pipeline input?  

false

Accept wildcard characters? 

false

 

-confirm

Prompts you for confirmation before executing the command.

 

Required?

false

Position?

named

Default value

 

Accept pipeline input?  

false

Accept wildcard characters? 

false

 

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, and -OutVariable. For more information, type, "get-help about_commonparameters".

 

INPUT TYPE

String

 

NOTES

 

For more information, type "Get-Help Clear-Variable -detailed". For technical information, type "Get-Help Clear-Variable -full".

 

To delete a variable, along with its value, use Remove-Variableor Remove-Item.

 

Clear-Variable will not delete the values of variables that are set as constants or owned by the system, even if you use the -Force parameter.

 

If the variable that you are clearing does not exist, the cmdlet has no effect. It does not create a variable with a null value.

 

You can also refer to Clear-Variable by its built-in alias, "clv". For more information, see About_Alias.

 

When specifying multiple values for a parameter, use commas to separate the values. For example, "<parameter-name> <value1>, <value2>".

 

EXAMPLE 1

 

clear-variable my* -global

 

This command deletes the value of the global variables that begin with "my".

 

EXAMPLE 2

 

$a=3

&{ clear-variable a }

$a

3

 

These commands demonstrate that clearing a variable in a child scope does not clear the value in the parent scope. The first command sets the value of the variable $a to 3. The second command uses the invoke operator (&) to run a Clear-Variable command in a new scope. The variable is cleared in the child scope (although it didn't exist), but it is not cleared in the local scope. The third command, which gets the value of $a, shows that the value 3 is unaffected.

 

EXAMPLE 3

 

clear-variable -name processes

 

This command deletes the value of the $processes variable. The $processes variable still exists, but the value is null.

 

RELATED LINKS

Get-Variable

Set-Variable

New-Variable

Remove-Variable