about_Requires

[アーティクル]
05/09/2024

簡単な説明

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

長い説明

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

構文

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

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

使用するルール

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

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

警告

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

例:

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

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

パラメーター

-Assembly <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 6.0

-Modules <Module-Name> | <Hashtable>

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

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

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

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

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

注意

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

例:

AzureRM.Netcore (バージョン0.12.0以上) がインストールされている必要があります。

#Requires -Modules @{ ModuleName="AzureRM.Netcore"; ModuleVersion="0.12.0" }

AzureRM.Netcore (バージョン0.12.0のみ) がインストールされている必要があります。

#Requires -Modules @{ ModuleName="AzureRM.Netcore"; RequiredVersion="0.12.0" }

AzureRM.Netcore (バージョン0.12.0以下) がインストールされている必要があります。

#Requires -Modules @{ ModuleName="AzureRM.Netcore"; MaximumVersion="0.12.0" }

任意のバージョンの AzureRM.Netcore と PowerShellGet がインストールされている必要があります。

#Requires -Modules AzureRM.Netcore, PowerShellGet

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

Get-Module AzureRM.Netcore -ListAvailable

    Directory: /home/azureuser/.local/share/powershell/Modules

ModuleType Version Name            PSEdition ExportedCommands
---------- ------- ----            --------- ----------------
Script     0.12.0  AzureRM.Netcore Core

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

#Requires -Modules @{ ModuleName="AzureRM.Netcore"; RequiredVersion="0.12" }

-PSEdition <PSEdition-Name>

スクリプトに必要な PowerShell エディションを指定します。有効な値は、PowerShell の場合は Core、Windows PowerShellの場合は Desktop です。

例:

#Requires -PSEdition Core

-RunAsAdministrator

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

次に例を示します。

#Requires -RunAsAdministrator

例

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

#Requires -Modules AzureRM.Netcore
#Requires -Version 6.0
Param
(
    [parameter(Mandatory=$true)]
    [String[]]
    $Path
)
...

次の方法で共有