コマンドレット パラメーターの種類

このトピックでは、コマンドレットで宣言できるさまざまな種類のパラメーターについて説明します。 コマンドレット パラメーターには、位置指定、名前付き、必須、省略可能、または [switch] パラメーターを指定できます。

位置指定パラメーターと名前付きパラメーター

すべてのコマンドレット パラメーターは、名前付きパラメーターまたは位置指定パラメーターです。 名前付きパラメーターでは、コマンドレットを呼び出すときにパラメーター名と引数を入力する必要があります。 位置指定パラメーターでは、引数を相対的な順序で入力するだけで済みます。 その後、システムは最初の無名引数を最初の位置指定パラメーターにマップします。 システムは、2 番目の名前のない引数を 2 番目の名前のないパラメーターにマップします。 既定では、すべてのコマンドレット パラメーターは名前付きパラメーターです。

名前付きパラメーターを定義するには、次のパラメーター宣言に示すように、Position 属性宣言で キーワードを省略します。

[Parameter(ValueFromPipeline=true)]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

位置指定パラメーターを定義するには、Parameter 属性宣言に Position キーワードを追加し、位置を指定します。 次の例では、UserName パラメーターは位置 0 の位置パラメーターとして宣言されています。 これは、呼び出しの最初の引数がこのパラメーターに自動的にバインドされることを意味します。

[Parameter(Position = 0)]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

注

適切なコマンドレット設計では、コマンドレットの実行時にユーザーがパラメーター名を入力する必要がないように、最も使用されるパラメーターを位置指定パラメーターとして宣言することをお勧めします。

位置指定パラメーターと名前付きパラメーターは、1 つの引数またはコンマで区切られた複数の引数を受け取ります。 複数の引数は、パラメーターが文字列の配列などのコレクションを受け入れる場合にのみ使用できます。 同じコマンドレットで位置指定パラメーターと名前付きパラメーターを混在させられます。 この場合、システムは最初に名前付き引数を取得してから、残りの名前のない引数を位置指定パラメーターにマップしようとします。

次のコマンドは、Get-Command コマンドレットのパラメーターに対して 1 つの引数と複数の引数を指定するさまざまな方法を示しています。 最後の 2 つのサンプルでは、-Name パラメーターが位置指定パラメーターとして定義されているため、 を指定する必要はありません。

Get-Command -Name Get-Service
Get-Command -Name Get-Service,Set-Service
Get-Command Get-Service
Get-Command Get-Service,Set-Service

必須パラメーターと省略可能なパラメーター

また、必須または省略可能なパラメーターとしてコマンドレット パラメーターを定義することもできます。 (PowerShell ランタイムがコマンドレットを呼び出す前に、必須パラメーターを指定する必要があります)。既定では、パラメーターは省略可能として定義されます。

必須パラメーターを定義するには、次のパラメーター宣言に示すように、パラメーター属性宣言に Mandatory キーワードを追加し、trueに設定します。

[Parameter(Position = 0, Mandatory = true)]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

省略可能なパラメーターを定義するには、次のパラメーター宣言に示すように、Mandatory 属性宣言で キーワードを省略します。

[Parameter(Position = 0)]
public string UserName
{
  get { return userName; }
  set { userName = value; }
}
private string userName;

[switch] パラメーター

PowerShell には、System.Management.Automation.SwitchParameter 型が用意されており、コマンドレットの呼び出し時にパラメーターを指定しない限り、既定値 false パラメーターを定義できます。 可能な限り、ブール型パラメーターの代わりに [switch] パラメーターを使用します。

次のような例で考えてみましょう。 多くの PowerShell コマンドレットは出力を返します。 ただし、これらのコマンドレットには、既定の動作をオーバーライドする PassThru[switch] パラメーターがあります。 PassThru パラメーターを使用すると、コマンドレットは出力オブジェクトをパイプラインに返します。

次の例は、 [switch] パラメーターを定義する方法を示しています。

[Parameter()]
public SwitchParameter GoodBye
{
  get { return goodbye; }
  set { goodbye = value; }
}
private bool goodbye;

コマンドレットが指定されたときにパラメーターに対して動作するようにするには、入力処理メソッドの 1 つ内で次の構造を使用します。

protected override void ProcessRecord()
{
  WriteObject("Switch parameter test: " + userName + ".");
  if (goodbye)
  {
    WriteObject(" Goodbye!");
  }
} // End ProcessRecord

既定では、 [switch] パラメーターは位置指定パラメーターから除外されます。 Parameter 属性でそれをオーバーライド が、ユーザーを混乱させる可能性があります。

パラメーター [switch] 設計して、パラメーターを使用すると、コマンドの既定の動作が、あまり一般的ではない、またはより複雑なモードに変更されます。 コマンドの最も簡単な動作は、 [switch] パラメーターを使用する必要のない既定の動作です。 [switch] パラメーターによって制御される動作は、パラメーターの存在ではなく、パラメーターの値に基づいて行います。

[switch] パラメーターが存在することをテストするには、いくつかの方法があります。

  • MyInvocation.BoundParameters [switch]パラメーター名がキーとして含まれています
  • PSCmdlet.ParameterSetName [switch] パラメーターが一意のパラメーター セットを定義する場合

たとえば、-MySwitch:$false またはスプラッティングを使用して、スイッチに明示的な値を指定できます。 パラメーターの有無のみをテストする場合、コマンドはスイッチ値が $trueではなく $false かのように動作します。

こちらもご覧ください

Windows PowerShell コマンドレットの作成

  • Last updated on