New-Variable

参考

模块:: Microsoft.PowerShell.Utility

创建新变量。

语法

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

说明

New-Variable cmdlet 在 PowerShell 中创建新的变量。可以在创建变量时为变量赋值，也可以在创建变量后分配或更改该值。

可以使用 New-Variable 的参数来设置变量的属性、设置变量的范围，并确定变量是公共变量还是私有变量。

通常，可以通过键入变量名及其值（如 $Var = 3）创建新变量，但可以使用 New-Variable cmdlet 来使用其参数。

示例

示例 1：创建变量

New-Variable days

此命令将创建一个名为 days 的新变量。无需键入 Name 参数。

示例 2：创建变量并为其赋值

New-Variable -Name "zipcode" -Value 98033

此命令创建名为 zipcode 的变量，并为其分配值 98033。

示例 3：使用 ReadOnly 选项创建变量

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

此示例演示如何使用 New-Variable 的 ReadOnly 选项来保护变量不被覆盖。

第一个命令创建名为 Max 的新变量，并将其值设置为 256。它使用值为 ReadOnly的 Option 参数。

第二个命令尝试创建具有相同名称的第二个变量。此命令返回错误，因为对变量设置了只读选项。

第三个命令使用 Force 参数替代变量上的只读保护。在这种情况下，用于创建具有相同名称的新变量的命令成功。

示例 4：为变量分配多个选项

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

此示例创建一个变量并分配 AllScope 和 Constant 选项，以便该变量在当前作用域中可用，并且无法更改或删除任何新作用域。

示例 5：创建专用变量

此命令演示模块中私有变量的行为。该模块包含 Get-Counter cmdlet，该 cmdlet 具有名为 Counter 的私有变量。该命令使用 Visibility 参数和私有值来创建变量。

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
...

示例输出显示私有变量的行为。加载模块的用户无法查看或更改 Counter 变量的值，但计数器变量可由模块中的命令读取和更改。

示例 6：使用空格创建变量

此示例演示了可以创建带空格的变量。可以使用 Get-Variable cmdlet 或直接使用大括号分隔变量来访问变量。

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

参数

-Confirm

在运行 cmdlet 之前，提示你进行确认。

类型:	SwitchParameter
别名:	cf
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-Description

指定变量的说明。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Force

指示 cmdlet 创建与现有只读变量同名的变量。

默认情况下，可以覆盖变量，除非变量具有选项值 ReadOnly 或 Constant。有关详细信息，请参阅 Option 参数。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Name

指定新变量的名称。

类型:	String
Position:	0
默认值:	None
必需:	True
接受管道输入:	True
接受通配符:	False

-Option

指定变量的 Options 属性的值。此参数的可接受值为：

None - 不设置任何选项。 None 为默认值。
ReadOnly - 可以删除。不能更改，除非使用 Force 参数。
Private - 变量仅在当前范围内可用。
AllScope - 变量将复制到创建的任何新作用域。
Constant - 无法删除或更改。只有在创建变量时，Constant 才有效。不能将现有变量的选项更改为 Constant。

这些值定义为基于标志的枚举。可以使用此参数将多个值组合在一起以设置多个标志。可以将值作为值数组或这些值的逗号分隔字符串传递给 Option 参数。该 cmdlet 将使用二进制 OR作合并这些值。将值作为数组传递是最简单的选项，还允许对值使用 Tab 补全。

若要查看会话中所有变量的 Options 属性，请键入 Get-Variable | Format-Table -Property name, options -AutoSize。

类型:	ScopedItemOptions
接受的值:	None, ReadOnly, Constant, Private, AllScope, Unspecified
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-PassThru

返回一个对象，该对象表示正在使用的项。默认情况下，此 cmdlet 不生成任何输出。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Scope

指定新变量的范围。此参数的可接受值为：

Global - 在全局范围内创建的变量可在 PowerShell 进程中随处访问。
Local - 本地范围是指当前范围，这可以是任何范围，具体取决于上下文。未指定 scope 参数时，Local 是默认范围。
Script - 只能在创建脚本文件或模块内访问在脚本范围内创建的变量。
一个相对于当前作用域的数字（0 到范围的数目，其中 0 是当前范围，1 是其父范围，2 是父范围的父范围，等等）。不能使用负数。

注意

该参数还接受 Private的值。 Private 实际上不是范围，而是变量的可选设置。但是，使用此 cmdlet 的 Private 值不会更改变量的可见性。有关详细信息，请参阅 about_Scopes。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Value

指定变量的初始值。

类型:	Object
Position:	1
默认值:	None
必需:	False
接受管道输入:	True
接受通配符:	False

-Visibility

确定变量是否在创建变量的会话之外可见。此参数旨在用于将传递给其他用户的脚本和命令。此参数的可接受值为：

Public - 该变量可见。 Public 为默认值。
Private - 变量不可见。

当变量是私有的，它不会出现在变量列表中，例如由 Get-Variable返回的变量，也不会显示在 Variable: 驱动器的显示中。用于读取或更改私有变量值的命令返回错误。但是，如果用户在定义变量的会话中写入了命令，则可以运行使用私有变量的命令。

类型:	SessionStateEntryVisibility
接受的值:	Public, Private
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-WhatIf

显示 cmdlet 运行时会发生什么情况。 cmdlet 未运行。

类型:	SwitchParameter
别名:	wi
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

输入

Object

可以通过管道将任何对象传递给 New-Variable。

输出

None

默认情况下，此 cmdlet 不返回任何输出。

PSVariable

使用 PassThru 参数时，此 cmdlet 将返回表示新变量的 PSVariable 对象。

备注

PowerShell 包含以下 New-Variable别名：

所有平台：
- nv

通过