New-Variable

Syntax

New-Variable
   [-Name] <String>
   [[-Value] <Object>]
   [-Description <String>]
   [-Option <ScopedItemOptions>]
   [-Visibility <SessionStateEntryVisibility>]
   [-Force]
   [-PassThru]
   [-Scope <String>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

The New-Variable cmdlet creates a new variable in Windows PowerShell. You can assign a value to the variable while creating it or assign or change the value after it is created.

You can use the parameters of New-Variable to set the properties of the variable, set the scope of a variable, and determine whether variables are public or private.

Typically, you create a new variable by typing the variable name and its value, such as $Var = 3, but you can use the New-Variable cmdlet to use its parameters.

Examples

Example 1: Create a variable

New-Variable days

This command creates a new variable named days. You are not required to type the Name parameter.

Example 2: Create a variable and assign it a value

New-Variable -Name "zipcode" -Value 98033

This command creates a variable named zipcode and assigns it the value 98033.

Example 3: Create a variable with the ReadOnly option

PS C:\> New-Variable -Name Max -Value 256 -Option ReadOnly
PS C:\> New-Variable -Name max -Value 1024

New-Variable : A variable with name 'max' already exists.
At line:1 char:1
+ New-Variable -Name max -Value 1024
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ResourceExists: (max:String) [New-Variable], SessionStateException
    + FullyQualifiedErrorId : VariableAlreadyExists,Microsoft.PowerShell.Commands.NewVariableCommand

PS C:\> New-Variable -Name max -Value 1024 -Force

This example shows how to use the ReadOnly option of New-Variable to protect a variable from being overwritten.

The first command creates a new variable named Max and sets its value to 256. It uses the Option parameter with a value of ReadOnly.

The second command tries to create a second variable with the same name. This command returns an error, because the read-only option is set on the variable.

The third command uses the Force parameter to override the read-only protection on the variable. In this case, the command to create a new variable with the same name succeeds.

Example 4: Assign multiple options to a variable

New-Variable -Name 'TestVariable' -Value 'Test Value' -Option AllScope,Constant

This example creates a variable and assigns the AllScope and Constant options so the variable will be available in the current scope and any new scopes created and cannot be changed or deleted.

Example 5: Create a private variable

PS C:\> New-Variable -Name counter -Visibility Private

#Effect of private variable in a module.

PS C:\> Get-Variable c*

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

PS C:\> $counter
"Cannot access the variable '$counter' because it is a private variable"
At line:1 char:1
+ $counter
+ ~~~~~~~~
    + CategoryInfo          : PermissionDenied: (counter:String) [], SessionStateException
    + FullyQualifiedErrorId : VariableIsPrivate

PS C:\> Get-Counter
Name         Value
----         -----
Counter1     3.1415
...

This command demonstrates the behavior of a private variable in a module. The module contains the Get-Counter cmdlet, which has a private variable named Counter. The command uses the Visibility parameter with a value of Private to create the variable.

The sample output shows the behavior of a private variable. The user who has loaded the module cannot view or change the value of the Counter variable, but the Counter variable can be read and changed by the commands in the module.

Example 6: Create a variable with a space

PS C:\> New-Variable -Name 'with space' -Value 'abc123xyz'

PS C:\> Get-Variable -Name 'with space'

Name                           Value
----                           -----
with space                     abc123xyz

PS C:\> ${with space}
abc123xyz

This command demonstrates that variables with spaces can be created. The variables can be accessed using the Get-Variable cmdlet or directly by delimiting a variable with braces.

Parameters

-Confirm

-Description

-Force

-Name

-Option

-PassThru

-Scope

-Value

-Visibility

-WhatIf

Inputs

Object

You can pipe a value to New-Variable.

Outputs

None or System.Management.Automation.PSVariable

When you use the PassThru parameter, New-Variable generates a System.Management.Automation.PSVariable object representing the new variable. Otherwise, this cmdlet does not generate any output.

Related Links

• Clear-Variable
• Get-Variable
• Remove-Variable
• Set-Variable