建立新變數。

語法

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。

輸出

None 或 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 變數。

請參閱



目錄