New-Variable

模組:

Microsoft.PowerShell.Utility Module

建立新的變數。

語法

Default (預設值)

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

Description

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

此範例示範如何使用 ReadOnly 的 New-Variable 選項來保護變數不受覆寫。

第一個命令會建立名為 Max 的新變數，並將其值設定為 256。 它會使用具有 值的 ReadOnly 參數。

第二個命令會嘗試建立具有相同名稱的第二個變數。 此命令會傳回錯誤，因為變數上已設定唯讀選項。

第三個命令會使用 Force 參數來覆寫變數上的只讀保護。 在此情況下，建立具有相同名稱的新變數的命令會成功。

範例 4：將多個選項指派給變數

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

此範例會建立變數，並指派 AllScope 和 Constant 選項，讓變數可在目前範圍中使用，以及任何建立且無法變更或刪除的新範圍。

範例 5：建立私用變數

此命令示範模組中私用變數的行為。 模組包含 Get-Counter Cmdlet，其具有名為 Counter 的私人變數。 此命令會使用 Visibility 參數搭配 Private 值來建立變數。

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 之前，提示您進行確認。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False
別名:	cf

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Description

指定變數的描述。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Force

表示 Cmdlet 會建立名稱與現有唯讀變數相同的變數。

根據預設，除非變數具有選項值 ReadOnly 或 Constant，否則您可以覆寫變數。 如需詳細資訊，請參閱 Option 參數。

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Name

指定新變數的名稱。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	0
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	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
接受的值:	None, ReadOnly, Constant, Private, AllScope, Unspecified
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-PassThru

返回一個物件，代表您正在處理的項目。 根據預設，此 Cmdlet 不會產生任何輸出。

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Scope

指定新變數的範圍。 此參數可接受的值為：

• Global - 在全域範圍中建立的變數可在PowerShell程式中隨處存取。
• Local - 本機範圍是指目前的範圍，視內容而定，這可以是任何範圍。 未指定 scope 參數時，Local 是預設範圍。
• Script - 文本範圍中建立的變數只能在建立的腳本檔案或模組記憶體取。
• 相對於目前範圍的數位（0 到範圍的數目，其中0是目前的範圍，1是其父範圍，2是父範圍的父系等等）。 無法使用負數。

備註

參數也接受 Private的值。 Private 實際上不是範圍，而是變數的選擇性設定。 不過，搭配此 Cmdlet 使用 Private 值並不會變更變數的可見性。 如需詳細資訊，請參閱 about_Scopes。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Value

指定變數的初始值。

參數屬性

類型:	Object
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	1
必要:	False
來自管線的值:	True
來自管線按屬性名稱的值:	True
來自剩餘引數的值:	False

-Visibility

判斷變數是否顯示在建立該變數的會話之外。 此參數的設計目的是要用於將傳遞給其他使用者的腳本和命令中。 此參數可接受的值為：

• Public - 變數是可見的。 Public 是預設值。
• Private - 看不到變數。

當變數為私用時，它不會出現在變數清單中，例如 Get-Variable所傳回的變數，或顯示在 Variable: 磁碟驅動器中。 讀取或變更私用變數值的命令會傳回錯誤。 不過，如果使用者在定義變數的會話中寫入命令，則可以執行使用私用變數的命令。

參數屬性

類型:	SessionStateEntryVisibility
預設值:	None
接受的值:	Public, Private
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-WhatIf

顯示 Cmdlet 執行時會發生什麼事。 指令未執行。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False
別名:	無線

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CommonParameters

此 Cmdlet 支援一般參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 如需詳細資訊，請參閱 about_CommonParameters。

輸入

Object

您可以使用管線將任何物件傳送至 New-Variable。

輸出

None

根據預設，此 Cmdlet 不會傳回任何輸出。

PSVariable

當您使用 PassThru 參數時，這個 Cmdlet 會傳回代表新變數的 PSVariable 物件。

備註

PowerShell 包含下列 New-Variable的別名：

• 所有平臺：
  • nv

相關連結

• 清除變數
• Get-Variable
• 移除變數（Remove-Variable）
• Set-Variable