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 的新變數。 你不需要輸入 名稱 參數。

範例 2：建立變數並賦值

New-Variable -Name "zipcode" -Value 98033

此指令會建立一個名為郵遞區號的變數，並將其賦值為 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。 它使用 Option 參數，值為 ReadOnly。

第二個指令嘗試建立同名的第二個變數。 此指令會回傳錯誤，因為該變數已設定唯讀選項。

第三個指令使用 力 參數來覆蓋該變數的唯讀保護。 在這種情況下，建立同名新變數的指令成功。

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

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

這個範例建立一個變數並指派 和 AllScopeConstant 選項，使變數在目前的範圍內可用，且新建立的 scope 無法更改或刪除。

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

樣本輸出顯示私有變數的行為。 載入模組的使用者無法查看或更改計數器變數的值，但計數器變數可由模組中的指令讀取並更改。

範例 6：建立一個包含空格的變數

此範例顯示帶有空格的變數是可以被創造的。 這些變數可以透過指令碼（cmdlet） Get-Variable 或直接用大括號分隔變數來存取。

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
別名:	參見

參數集

(All)

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

-Description

指定變數的描述。

參數屬性

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

參數集

(All)

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

-Force

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

預設情況下，除非變數的選項值為或 ReadOnlyConstant，否則你可以覆寫該變數。 欲了解更多資訊，請參閱 選項 參數。

參數屬性

類型:	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 - 可以刪除。 無法更改，除非使用 力 場參數。
• 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 - 局部範圍指的是目前的範圍，依上下文可以是任何範圍。 Local 當作用域參數未指定時，是預設範圍。
• Script - 在腳本作用域中建立的變數只能在它們所建立的腳本檔案或模組中存取。
• 相對於目前範圍的數字（0 除以範圍數，0 是目前的範圍，1 是父範圍，2 是父範圍的父，依此類推）。 負數則不能使用。

Note

參數同時接受 的 Private值。 Private 其實不是作用域，而是變數的可選設定。 然而，使用此 Private cmdlet 並不會改變變數的可見性。 如需詳細資訊，請參閱 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

Value 參數接受從管線輸入的物件，無論是來自具有 Value 屬性的物件。

String

Name 參數接受具有 Name 屬性的管線物件的字串輸入。

輸出

None

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

PSVariable

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

備註

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

• 所有平臺：
  • nv

相關連結

• 清除變數
• Get-Variable
• 移除變數
• Set-Variable