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，它具有一个名为 Counter 的私有变量。 该命令使用值为 Private 的 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 变量的值，但可以通过该模块中的命令来读取和更改 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 之前进行确认。

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 将使用二进制或运算合并这些值。 将值作为数组传递是最简单的选项，此选项还支持对值使用 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 - 局部作用域是指当前作用域，这可以是任何作用域，具体取决于上下文。 未指定 scope 参数时，Local 是默认作用域。
  • Script - 在脚本作用域中创建的变量只能在创建该变量的脚本文件或模块中访问。
  • 一个相对于当前作用域的数字（0 到作用域数，其中 0 是指当前作用域，1 是指其父作用域，2 是父作用域的父级，依此类推）。 不能使用负数。

注意

该参数还接受 Private 的值。 Private 实际上不是作用域，而是变量的可选设置。 但是，对此 cmdlet 使用 Private 值不会更改变量的可见性。 有关详细信息，请参阅 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

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

PSVariable

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

备注

PowerShell 包含 New-Variable 的以下别名：

  • 所有平台：
    • nv