Share via

New-Variable

  • 参考
模块:
Microsoft.PowerShell.Utility

创建新变量。

语法

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

说明

cmdlet New-Variable 在 Windows 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

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

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

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

第三个命令使用 Force 参数来覆盖该变量上的只读保护。 在此示例中，用于创建具有相同名称的新变量的命令将成功。

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

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

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

示例 5：Create私有变量

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

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

示例输出显示了私有变量的行为。 已加载该模块的用户无法查看或更改 Counter 变量的值，但可以通过该模块中的命令来读取和更改 Counter 变量。

示例 6：Create带空格的变量

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

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

参数

-Confirm

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

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Description

指定对变量的描述。

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Force

指示该 cmdlet 创建一个与现有只读变量具有相同名称的变量。

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Name

指定新变量的名称。

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters: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。

Type:ScopedItemOptions
Accepted values:None, ReadOnly, Constant, Private, AllScope, Unspecified
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-PassThru

返回一个代表你所处理的项目的对象。 默认情况下，此 cmdlet 将不产生任何输出。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Scope

指定新变量的作用域。 此参数的可接受值为：

  • Global - 在全局范围内创建的变量可在 PowerShell 进程中的任意位置访问。
  • Local - 本地范围是指当前范围，这可以是任何范围，具体取决于上下文。
  • Script - 在脚本范围内创建的变量只能在在其中创建变量的脚本文件或模块中访问。
  • Private - 在专用作用域中创建的变量不能在它们存在的范围之外访问。 可以使用专用作用域在另一个作用域中创建具有相同名称的项的专用版本。
  • 相对于当前范围的数字 (0 到范围的数目，其中 0 是当前范围，1 是其父范围，2 是父范围，依此) 。 不能使用负数。

Local 是未指定 scope 参数时的默认范围。

有关详细信息，请参阅 about_Scopes。

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Value

指定变量初始值。

Type:Object
Position:1
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-Visibility

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

  • Public - 变量可见。 Public 是默认值。
  • Private - 变量不可见。

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

Type:SessionStateEntryVisibility
Accepted values:Public, Private
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WhatIf

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

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

输入

Object

可以通过管道将值传递给 New-Variable。

输出

None or System.Management.Automation.PSVariable

使用 PassThru 参数时， New-Variable 会生成一个表示新变量的 System.Management.Automation.PSVariable 对象。 否则，此 cmdlet 将不生成任何输出。