New-Variable
建立新變數。
語法
New-Variable [-Name] <string> [[-Value] <Object>] [-Description <string>] [-Force] [-Option {<None> | <ReadOnly> | <Constant> | <Private> | <AllScope>}] [-PassThru] [-Scope <string>] [-Visibility {<Public> | <Private>}] [-Confirm] [-WhatIf] [<CommonParameters>]
描述
New-Variable Cmdlet 會在 Windows PowerShell 中建立新的變數。您可以在建立時指派值給變數，也可以在建立之後才指派或變更值。
您可以使用 New-Variable 的參數設定變數的屬性 (例如建立唯讀或常數變數的屬性)、設定變數範圍，以及決定變數是公用還是私用。
一般來說，您會透過輸入變數名稱及其值，例如 "$var = 3"，建立新的變數，不過可以利用 New-Variable Cmdlet 使用其參數。
參數
-Description <string>
指定變數的描述。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-Force
允許建立與現有唯讀變數同名的新變數。
根據預設，除非變數的選項值為 ReadOnly 或 Constant，否則可以覆寫變數。如需詳細資訊，請參閱 Option 參數。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-Name <string>
指定新變數的名稱。
必要? |
true |
位置? |
1 |
預設值 |
|
接受管線輸入? |
true (ByPropertyName) |
接受萬用字元? |
false |
-Option <ScopedItemOptions>
設定新變數的 Options 屬性值。
有效的值包括：
-- None：不設定選項。(預設值為 "None")。
-- ReadOnly：無法變更變數的值，除非使用 Force 參數。您可以使用 Remove-Variable 刪除變數。
-- Constant：無法刪除變數，且無法變更其屬性。只有建立別名時才能使用 "Constant"。您無法將現有變數的選項變更為 "Constant"。
-- Private：變數只在 Scope 參數所指定的範圍內有效。此範圍由子範圍繼承 (此值與 Visibility 參數的 "Private" 值無關)。
-- AllScope：將變數複製到所有新建立的範圍。
若要查看變數的 Options 屬性，請輸入 "get-variable| Format-Table -property name, options -autosize"。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-PassThru
傳回代表新變數的物件。根據預設，此 Cmdlet 不會產生任何輸出。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-Scope <string>
決定新變數的範圍。有效的值包括 "Global"、"Local"、"Script" 或相對於目前範圍的數字 (從 0 到範圍總數，其中 0 代表目前範圍，1 代表其上層)。預設值為 "Local"。如需詳細資訊，請參閱 about_Scopes。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-Value <Object>
指定變數的初始值。
必要? |
false |
位置? |
2 |
預設值 |
|
接受管線輸入? |
true (ByValue, ByPropertyName) |
接受萬用字元? |
false |
-Visibility <SessionStateEntryVisibility>
決定變數是否可在其建立所在的工作階段以外顯示。此參數是專為用在提供給其他使用者的指令碼和命令所設計。
有效的值包括：
-- Public：看得到變數 (預設值為 "Public")。
-- Private：看不到變數。
變數為私用時，不會出現在變數的清單 (例如由 Get-Variable 傳回的清單)，也不會在 Variable：磁碟機中顯示。對私用變數的值進行讀取或變更的命令會傳回錯誤。但是，如果使用私用變數的命令是在該變數定義所在的工作階段中撰寫的，使用者就可以執行這種命令。
必要? |
false |
位置? |
named |
預設值 |
Public |
接受管線輸入? |
false |
接受萬用字元? |
false |
-Confirm
在執行命令前先提示確認。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-WhatIf
說明執行命令時將會發生何種情況，但不會實際執行命令。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
<CommonParameters>
這個 Cmdlet 支援一般參數：-Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer 和 -OutVariable。如需詳細資訊，請參閱 about_Commonparameters.
輸入和輸出
輸入型別是可經由管道輸出至 Cmdlet 的物件型別。傳回型別則是 Cmdlet 所傳回的物件型別。
輸入 |
System.Object 您可以經由管道將值輸出至 New-Variable。 |
輸出 |
無或 System.Management.Automation.PSVariable 當您使用 PassThru 參數時，New-Variable 會產生代表新變數的 System.Management.Automation.PSVariable 物件。否則，這個 Cmdlet 不會產生任何輸出。 |
範例 1
C:\PS>new-variable days
描述
-----------
這個命令會建立名為 "days" 的新變數。緊接命令之後沒有任何值。
範例 2
C:\PS>new-variable zipcode -value 98033
描述
-----------
這個命令會建立名為 "zipcode" 的變數，並指定其值為 "98033"。
範例 3
C:\PS>new-variable -name max -value 256 -option readonly
new-variable -name max -value 1024
new-variable -name max -value 1024 -force
C:\PS> new-variable -name max -value 256 -option readonly
C:\PS> new-variable -name max -value 1024
New-Variable : A variable with name 'max' already exists.
At line:1 char:13
+ new-variable <<<< -name max -value 1024
C:\PS> new-variable -name max -value 1024 -force
描述
-----------
這個範例示範如何使用 New-Variable 的 ReadOnly 選項防止覆寫變數。
第一個命令會建立名為 Max 的新變數，並將它的值設定為 "256"。它會使用具有 ReadOnly 值的 Option 參數。
第二個命令會嘗試建立第二個同名變數。此命令會傳回錯誤，因為該變數上已設定唯讀選項。
第三個命令會使用 Force 參數覆寫該變數上的唯讀保護。在此例中，建立新的同名變數的命令會成功。
範例 4
C:\PS>new-variable -name counter -visibility private
#Effect of private variable in a module.
C:\PS> get-variable c*
Name Value
---- -----
Culture en-US
ConsoleFileName
ConfirmPreference High
CommandLineParameters {}
C:\PS> $counter
"Cannot access the variable '$counter' because it is a private variable"
C:\PS> Get-Counter
Name Value
---- -----
Counter1 3.1415
...
描述
-----------
這個命令示範私用變數在模組中的行為。這個模組包含 Get-Counter Cmdlet，其中有一個名為 "Counter" 的私用變數。這個命令會使用值為 "Private" 的 Visibility 參數來建立變數。
範例輸出會顯示私用變數的行為。已載入該模組的使用者無法檢視或變更 Counter 變數的值，但該模組中的命令卻可以讀取或變更 Counter 變數。