powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Set-Variable



NAME
Set-Variable

SYNOPSIS
Sets the value of a variable. Creates the variable if one with the requested name does not exist.

SYNTAX
Set-Variable [-Name] [[-Value] ] [-Description ] [-Exclude ] [-Force] [-Includ
e ] [-Option {None | ReadOnly | Constant | Private | AllScope}] [-PassThru] [-Scope ] [-Visibilit
y {Public | Private}] [-Confirm] [-WhatIf] []


DESCRIPTION
The Set-Variable cmdlet assigns a value to a specified variable or changes the current value. If the variable does
not exist, the cmdlet creates it.


PARAMETERS
-Description
Specifies the description of the variable.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Exclude
Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pa
ttern, such as "*.txt". Wildcards are permitted.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Force []
Allows you to create a variable with the same name as an existing read-only variable, or to change the value of
a read-only variable.

By default, you can overwrite a variable, unless the variable has an option value of "ReadOnly" or "Constant".
For more information, see the Option parameter.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Include
Changes only the specified items. The value of this parameter qualifies the Name parameter. Enter a name or nam
e pattern, such as "c*". Wildcards are permitted.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Name
Specifies the variable name.

Required? true
Position? 1
Default value
Accept pipeline input? true (ByPropertyName)
Accept wildcard characters? false

-Option
Changes the value of the Options property of the variable. Valid values are:

-- None: Sets no options. ("None" is the default.)

-- ReadOnly: The properties of the variable cannot be changed, except by using the Force parameter. You can use
Remove-Variable to delete the variable.

-- Constant: The variable cannot be deleted and its properties cannot be changed. "Constant" is available only
when you are creating an alias. You cannot change the option of an existing variable to "Constant".

-- Private: The variable is available only within the scope specified by the Scope parameter. It is inherited b
y child scopes.

-- AllScope: The variable is copied to any new scopes that are created.

To see the Options property of the variables, type "get-variable| format-table -property name, options -autosiz
e".

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-PassThru []
Returns an object representing the new variable. By default, this cmdlet does not generate any output.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Scope
Determines the scope of the variable. 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" i
s the default. For more information, see about_Scopes.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Value
Specifies the value of the variable.

Required? false
Position? 2
Default value
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? false

-Visibility
Determines whether the variable is visible outside of the session in which it was created. This parameter is de
signed for use in scripts and commands that will be delivered to other users.

Valid values are:

-- Public: The variable is visible. ("Public" is the default.)
-- Private: The variable is not visible.

When a variable is private, it does not appear in lists of variables, such as those returned by Get-Variable, o
r in displays of the Variable: drive. Commands to read or change the value of a private variable return an erro
r. However, the user can run commands that use a private variable if the commands were written in the session i
n which the variable was defined.

Required? false
Position? named
Default value Public
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

-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


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

INPUTS
System.Object
You can pipe an object that represents the value of the variable to Set-Variable.


OUTPUTS
None or System.Management.Automation.PSVariable
When you use the PassThru parameter, Set-Variable generates a System.Management.Automation.PSVariable object re
presenting the new or changed variable. Otherwise, this cmdlet does not generate any output.


NOTES





-------------------------- EXAMPLE 1 --------------------------

C:\PS>set-variable -name desc -value "A description"

C:\PS>get-variable -name desc


Description
-----------
These commands set the value of the "desc" variable to "A description", and then get the value of the variable.





-------------------------- EXAMPLE 2 --------------------------

C:\PS>set-variable -name processes -value (Get-Process) -option constant -scope global -description "All processes"
-passthru | format-list -property *


Description
-----------
This command creates a global, read-only variable that contains all processes on the system, and then it displays a
ll properties of the variable.

The command uses the Set-Variable cmdlet to create the variable. It uses the PassThru parameter to create an object
representing the new variable, and it uses the pipeline operator (|) to pass the object to the Format-List cmdlet.
It uses the Property parameter of Format-List with a value of all (*) to display all properties of the newly creat
ed variable.

The value, "(Get-Process)", is enclosed in parentheses to ensure that it is executed before being stored in the var
iable. Otherwise, the variable contains the words "Get-Process".





-------------------------- EXAMPLE 3 --------------------------

C:\PS># set-variable -name counter -visibility private

C:\PS> new-variable -name counter -visibility public -value 26

C:\PS> $counter
26

C:\PS> get-variable c*

Name Value
---- -----
Culture en-US
ConsoleFileName
ConfirmPreference High
CommandLineParameters {}
Counter 26

C:\PS> set-variable -name counter -visibility private

C:\PS> get-variable c*

Name Value
---- -----
Culture en-US
ConsoleFileName
ConfirmPreference High
CommandLineParameters {}

C:\PS> $counter
"Cannot access the variable '$counter' because it is a private variable"

C:\PS> .\use-counter.ps1
Commands completed successfully.


Description
-----------
This command shows how to change the visibility of a variable to "Private". This variable can be read and changed b
y scripts with the required permissions, but it is not visible to the user.

The sample output shows the difference in the behavior of public and private variables.






RELATED LINKS
Online version: http://go.microsoft.com/fwlink/?LinkID=113401
Get-Variable
New-Variable
Remove-Variable
Clear-Variable