關於_需求

簡短描述

防止腳本在沒有必要元素的情況下執行。

完整描述

除非滿足 PowerShell 版本、模組（和版本）或管理單元（和版本）和版本先決條件，否則該 #Requires 語句會阻止腳本運行。 如果不滿足先決條件，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 語句一律會全域套用，而且必須先符合，才能執行腳本。

範例：

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

您可能會認為上述程式代碼不應該執行，因為必要的模組已在 #Requires 語句之前移除。 不過，必須先符合 #Requires 狀態，腳本才能執行。 然後，腳本的第一行會使必要狀態失效。

參數

-Assembly <元件路徑> |<.NET 元件規格>

指定元件 DLL 檔案或 .NET 元件名稱的路徑。 元件 參數是在PowerShell 5.0中引進的。 如需 .NET 元件的詳細資訊，請參閱 元件名稱。

例如：

#Requires -Assembly path\to\foo.dll

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

-版本 <N>[.<n>]

指定腳本所需的最低 PowerShell 版本。 輸入主要版本號碼和選擇性次要版本號碼。

例如：

#Requires -Version 6.0

-PSSnapin <PSSnapin-Name> [-版本 <N>[.<n>]]

指定文稿所需的 PowerShell 嵌入式管理單元。 輸入嵌入式管理單元名稱和選擇性版本號碼。

例如：

#Requires -PSSnapin DiskSnapin -Version 1.2

-Modules <Module-Name> |<哈希表>

指定文稿所需的 PowerShell 模組。 輸入模組名稱和選擇性版本號碼。

如果所需的模組不在目前的會話中，PowerShell 會匯入它們。 如果無法匯入模組，PowerShell 會擲回終止錯誤。

對於每個模組，鍵入模組名稱 （<String>） 或哈希表。 該值可以是字串和哈希表的組合。 哈希錶具有以下鍵。

• ModuleName - 必要 指定模組名稱。
• GUID - 可選 指定模組的 GUID。
• 還需要指定以下三個鍵之一。 這些鍵不能一起使用。
  • ModuleVersion - 指定模組的最低可接受的版本。
  • RequiredVersion - 指定模組的確切必要版本。
  • MaximumVersion - 指定模組的最大可接受的版本。

例如：

需要安裝 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-名稱>

指定文稿所需的 PowerShell 版本。 有效值為適用於 PowerShell Core，以及適用於 Windows PowerShell Desktop。

例如：

#Requires -PSEdition Core

-ShellId

指定腳本所需的殼層。 輸入殼層標識碼。 如果您使用 ShellId 參數，也必須包含 PSSnapin 參數。 您可以藉由查詢自動變數來尋找目前的 $ShellId。

例如：

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

-RunAs管理員

將此參數新增至您的 #Requires 語句時，它會指定您執行腳本的 PowerShell 會話必須以提升的使用者權力啟動。 非 Windows作系統上會忽略 RunAsAdministrator 參數。 RunAsAdministrator 參數是在 PowerShell 4.0 中引進的。

例如：

#Requires -RunAsAdministrator

範例

下列腳本有兩個 #Requires 語句。 如果不符合這兩個語句中指定的需求，腳本就不會執行。 每個 #Requires 語句都必須是一行的第一個專案：

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

另請參閱

• 自動變數概覽
• 關於_語言_關鍵字