CmdID / PowerShell / Cmdlets / New
New-Variable
Creates a new variable. PowerShell reference
From the PowerShell reference
10 parameters
Alias nv
What it does
Creates a new variable. The New-Variable cmdlet creates a new variable in 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.
New-Variable [-Name] <String> [[-Value] <Object>] [-Description <String>] [-Option <ScopedItemOptions>] [-Visibility <SessionStateEntryVisibility>] [-Force] [-PassThru] [-Scope <String>] [-WhatIf] [-Confirm] [<CommonParameters>]Create a variable
New-Variable daysIdentifyCreate a variable and assign it a value
New-Variable -Name "zipcode" -Value 98033IdentifyCreate 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 -ForceIdentifyAssign multiple options to a variable
New-Variable -Name 'TestVariable' -Value 'Test Value' -Option AllScope,ConstantIdentifyCreate 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
...IdentifyCreate 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}
abc123xyzIdentifyIts page in the reference: New-Variable.
Parameters
-DescriptionSpecifies a description of the variable.-ForceIndicates that the cmdlet creates a variable with the same name as an existing 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.-NameSpecifies a name for the new variable.-OptionSpecifies the value of the Options property of the variable. The acceptable values for this parameter are:
- None - Sets no options. None is the default.
- ReadOnly - Can be deleted. Cannot be changed, except by using the Force parameter.
- Private - The variable is available only in the current scope.
- AllScope - The variable is copied to any new scopes that are created.
- Constant - Cannot be deleted or changed. Constant is valid only when you are creating a
variable. You cannot change the options of an existing variable to Constant.
These values are defined as a flag-based enumeration. You can combine multiple values together to set multiple flags using this parameter. The values can be passed to the Option parameter as an array of values or as a comma-separated string of those values. The cmdlet will combine the values using a binary-OR operation. Passing values as an array is the simplest option and also allows you to use tab-completion on the values.
To see the Options property of all variables in the session, type
Get-Variable | Format-Table -Property Name, Options -AutoSize.-PassThruReturns an object representing the item with which you are working. By default, this cmdlet does not generate any output.-ScopeSpecifies the scope of the new variable. The acceptable values for this parameter are:
- Global - Variables created in the global scope are accessible everywhere in a PowerShell
process.
- Local - The local scope refers to the current scope, this can be any scope depending on the
context. Local is the default scope when the scope parameter is not specified.
- Script - Variables created in the script scope are accessible only within the script file or
module they are created in.
- A number relative to the current scope (0 through the number of scopes, where 0 is the current
scope, 1 is its parent, 2 the parent of the parent scope, and so on). Negative numbers cannot be
used.
NOTE: The parameter also accepts the value of Private. Private is not actually a scope but an optional setting for a variable. However, using the Private value with this cmdlet does not change the visibility of the variable. For more information, see about_Scopes.-ValueSpecifies the initial value of the variable.-VisibilityDetermines whether the variable is visible outside of the session in which it was created. This parameter is designed for use in scripts and commands that will be delivered to other users. The acceptable values for this parameter 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, or in displays of the Variable: drive. Commands to read or change the value of a private variable return an error. However, the user can run commands that use a private variable if the commands were written in the session in which the variable was defined.-ConfirmPrompts you for confirmation before running the cmdlet.-WhatIfShows what would happen if the cmdlet runs. The cmdlet is not run.