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 コマンドレットは、Windows PowerShell で新しい変数を作成します。変数の作成中に値を割り当てたり、変数の作成後に値の割り当てや変更を行うことができます。
New-Variable のパラメーターを使用すると、変数のプロパティ (読み取り専用変数または定数変数を作成するプロパティ) やスコープを設定したり、変数がパブリックかプライベートかを特定したりできます。
通常、新しい変数を作成するには "$var = 3" のように変数名とその値を入力しますが、New-Variable コマンドレットではパラメーターを使用できます。
パラメーター
-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
新しい変数を表すオブジェクトを返します。既定では、このコマンドレットによる出力はありません。
必須 |
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: 変数は表示されません。
Private の変数は、Get-Variable が返す変数などの変数の一覧や Variable: ドライブの表示には表示されません。Private の変数の値を読み取ったり変更したりするコマンドでは、エラーが返されます。ただし、Private の変数を定義したセッションでコマンドが記述された場合は、その変数を使用するコマンドをユーザーが実行できます。
必須 |
false |
位置 |
named |
既定値 |
Public |
パイプライン入力を許可する |
false |
ワイルドカード文字を許可する |
false |
-Confirm
コマンドを実行する前に確認メッセージを表示します。
必須 |
false |
位置 |
named |
既定値 |
|
パイプライン入力を許可する |
false |
ワイルドカード文字を許可する |
false |
-WhatIf
実際にコマンドを実行せずに、コマンドを実行すると何が起きるかを出力します。
必須 |
false |
位置 |
named |
既定値 |
|
パイプライン入力を許可する |
false |
ワイルドカード文字を許可する |
false |
<CommonParameters>
このコマンドレットは、次の共通パラメーターをサポートします: -Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer、および -OutVariable。詳細については、次を参照してください: about_Commonparameters.
入力と出力
入力値の型は、コマンドレットへのパイプが可能なオブジェクトの型です。戻り値の型は、コマンドレットによって返されるオブジェクトの型です。
入力 |
System.Object 値を New-Variable にパイプ処理で渡すことができます。 |
出力 |
なし、または System.Management.Automation.PSVariable PassThru パラメーターを使用すると、New-Variable は新しい変数を表す System.Management.Automation.PSVariable オブジェクトを生成します。それ以外の場合、このコマンドレットによる出力はありません。 |
例 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 パラメーターを使用します。
2 番目のコマンドは、同じ名前の変数をもう 1 つ作成しようとします。変数に読み取り専用オプションが設定されているため、エラーが返されます。
3 番目のコマンドは、変数の読み取り専用保護を上書きするために 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 コマンドレットが含まれており、"Counter" という名前のプライベート変数があります。このコマンドでは、値を "Private" に設定した Visibility パラメーターを使用して変数を作成します。
サンプル出力は、プライベート変数の動作を示しています。モジュールを読み込んだユーザーは Counter 変数の値の表示や変更はできませんが、モジュール内でコマンドを使用して Counter 変数の読み取りと変更を行うことができます。