about_Requires

  • [アーティクル]

簡単な説明

スクリプトが必要な要素なしで実行されないようにします。

詳細な説明

このステートメントでは #Requires 、PowerShell のバージョン、モジュール (およびバージョン)、スナップイン (およびバージョン)、エディションの前提条件が満たされていない限り、スクリプトが実行されなくなります。 前提条件が満たされていない場合、PowerShell ではスクリプトが実行されず、タブ補完などの他のランタイム機能も提供されません。

構文

#Requires -Version <N>[.<n>]
#Requires -PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]
#Requires -Modules { <Module-Name> | <Hashtable> }
#Requires -PSEdition <PSEdition-Name>
#Requires -ShellId <ShellId> -PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]
#Requires -RunAsAdministrator

構文の詳細については、「ScriptRequirements」を参照してください。

使用する規則

スクリプトには複数のステートメントを #Requires 含めることができます。 ステートメントは #Requires 、スクリプト内の任意の行に表示できます。

関数内に #Requires ステートメントを配置しても、そのスコープは制限されません。 すべての #Requires ステートメントは常にグローバルに適用され、スクリプトを実行する前に満たす必要があります。

警告

ステートメントはスクリプト内の #Requires 任意の行に表示できますが、スクリプト内での位置はアプリケーションのシーケンスに影響しません。 ステートメントが提示する #Requires グローバル状態は、スクリプトを実行する前に満たす必要があります。

例:

Get-Module AzureRM.Netcore | Remove-Module
#Requires -Modules AzureRM.Netcore

必要なモジュールがステートメントの前 #Requires に削除されたため、上記のコードを実行しないでください。 ただし、スクリプトを #Requires 実行する前に状態を満たす必要がありました。 その後、スクリプトの最初の行で必要な状態が無効になりました。

パラメーター

-Assembly <アセンブリ パス> | <.NET アセンブリの仕様>

重要

構文は -Assembly 非推奨です。 これは関数を提供しません。 構文は PowerShell 5.1 で追加されましたが、サポート コードは実装されませんでした。 構文は下位互換性のために引き続き受け入れられます。

アセンブリ DLL ファイルまたは .NET アセンブリ名へのパスを指定します。 Assembly パラメーターは PowerShell 5.0 で導入されました。 .NET アセンブリの詳細については、「アセンブリ名」を参照してください。

次に例を示します。

#Requires -Assembly path\to\foo.dll

#Requires -Assembly "System.Management.Automation, Version=3.0.0.0,
  Culture=neutral, PublicKeyToken=31bf3856ad364e35"

-Version <N>[.<n>]

スクリプトに必要な PowerShell の最小バージョンを指定します。 メジャー バージョン番号とオプションのマイナー バージョン番号を入力します。

次に例を示します。

#Requires -Version 5.1

-PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]

スクリプトに必要な PowerShell スナップインを指定します。 スナップイン名とオプションのバージョン番号を入力します。

次に例を示します。

#Requires -PSSnapin DiskSnapin -Version 1.2

-Modules <Module-Name> | <Hashtable>

スクリプトに必要な PowerShell モジュールを指定します。 モジュール名とオプションのバージョン番号を入力します。

必要なモジュールが現在のセッションにない場合は、PowerShell によってインポートされます。 モジュールをインポートできない場合、PowerShell は終了エラーをスローします。

このステートメントでは #Requires 、モジュール内のクラス定義と列挙定義は読み込まれません。 スクリプトの using module 先頭にあるステートメントを使用して、クラス定義や列挙定義を含むモジュールをインポートします。 詳細については、「about_Using」を参照してください。

モジュールごとに、モジュール名 (<String>) またはハッシュテーブルを入力します。 値には、文字列とハッシュテーブルの組み合わせを指定できます。 ハッシュテーブルには次のキーがあります。

  • ModuleName - 必須 モジュール名を指定します。
  • GUID - 省略可能 モジュールの GUID を指定します。
  • また 、以下の 3 つのキーのうち少なくとも 1 つを指定する必要 もあります。
    • ModuleVersion - モジュールの最小許容バージョンを指定します。
    • MaximumVersion - モジュールの許容される最大バージョンを指定します。
    • RequiredVersion - モジュールの正確で必要なバージョンを指定します。 これは、他のバージョン キーでは使用できません。

Note

RequiredVersion は Windows PowerShell 5.0 で追加されました。 MaximumVersion は Windows PowerShell 5.1 で追加されました。

次に例を示します。

(バージョン1.1以上) をインストールするHyper-V必要があります。

#Requires -Modules @{ ModuleName="Hyper-V"; ModuleVersion="1.1" }

Hyper-V (バージョン1.1のみ) がインストールされている必要があります。

#Requires -Modules @{ ModuleName="Hyper-V"; RequiredVersion="1.1" }

Hyper-V (バージョン1.1以下) がインストールされている必要があります。

#Requires -Modules @{ ModuleName="Hyper-V"; MaximumVersion="1.1" }

任意のバージョンの PSScheduledJob and 、 PSWorkflowがインストールされている必要があります。

#Requires -Modules PSWorkflow, PSScheduledJob

キーを使用する RequiredVersion 場合は、バージョン文字列が必要なバージョン文字列と正確に一致していることを確認します。

Get-Module Hyper-V

ModuleType Version    Name     ExportedCommands
---------- -------    ----     ------------------
Binary     2.0.0.0    hyper-v  {Add-VMAssignableDevice, ...}

2.0.0 が 2.0.0.0 と完全に一致しないため、次の例は失敗します。

#Requires -Modules @{ ModuleName="Hyper-V"; RequiredVersion="2.0.0" }

-P Standard Edition dition <P Standard Edition dition-Name>

スクリプトに必要な PowerShell エディションを指定します。 有効な値は、 PowerShell のコア と Windows PowerShell のデスクトップ です。

次に例を示します。

#Requires -PSEdition Core

-ShellId

スクリプトに必要なシェルを指定します。 シェル ID を入力します。 ShellId パラメーターを使用する場合は、PSSnapin パラメーターも含める必要があります。 自動変数のクエリを実行すると、現在 の ShellId を $ShellId 見つけることができます。

次に例を示します。

#Requires -ShellId MyLocalShell -PSSnapin Microsoft.PowerShell.Core

Note

このパラメーターは、非推奨となったミニシェルでの使用を目的としています。

-RunAs管理istrator

この switch パラメーターを #Requires ステートメントに追加するときに、スクリプトを実行している PowerShell セッションを管理者特権で開始する必要があることを指定します。 Windows 以外のオペレーティング システムでは、RunAs管理istrator パラメーターは無視されます。 RunAs管理istrator パラメーターは、PowerShell 4.0 で導入されました。

次に例を示します。

#Requires -RunAsAdministrator

例

次のスクリプトには 2 つの #Requires ステートメントがあります。 両方のステートメントで指定された要件が満たされていない場合、スクリプトは実行されません。 各 #Requires ステートメントは、行の最初の項目である必要があります。

#Requires -Modules PSWorkflow
#Requires -Version 3
Param
(
    [parameter(Mandatory=$true)]
    [String[]]
    $Path
)
...

関連項目