about_Requires
簡短描述
防止腳本在沒有必要元素的情況下執行。
詳細描述
#Requires 語句會防止腳本執行，除非符合 PowerShell 版本、模組（和版本）和版本必要條件。 如果不符合必要條件，PowerShell 不會執行腳本或提供其他運行時間功能，例如 Tab 鍵自動完成。
語法
#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 元件名稱的路徑。 元件參數是在 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 <> | <哈希表>
指定文稿所需的 PowerShell 模組。 輸入模組名稱和選擇性版本號碼。
如果所需的模組不在目前的會話中，PowerShell 會匯入它們。 如果無法匯入模組，PowerShell 會擲回終止錯誤。
#Requires語句不會載入模組中的類別和列舉定義。
using module使用腳本開頭的 語句來匯入模組，包括 類別和列舉定義。 如需詳細資訊，請參閱 about_Using。
針對每個模組，輸入模組名稱 （<String>） 或哈希表。 此值可以是字串和哈希表的組合。 哈希錶具有下列索引鍵。
-
ModuleName- 必要 指定模組名稱。 -
GUID- 選擇性 指定模組的 GUID。 - 也必須指定下列三個索引鍵中的至少一個。
-
ModuleVersion- 指定模組的最低可接受的版本。 -
MaximumVersion- 指定模組的最大可接受的版本。 -
RequiredVersion- 指定模組的確切必要版本。 這無法與其他版本金鑰搭配使用。
-
注意
RequiredVersion 已在 Windows PowerShell 5.0 中新增。
MaximumVersion 已在 Windows PowerShell 5.1 中新增。
例如：
Hyper-V 需要安裝 （版本或更新版本1.1）。
#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 與 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" }
-PSEdition <PSEdition-Name>
指定文稿所需的 PowerShell 版本。 有效值為 適用於 PowerShell 的 Core 和 適用於 Windows PowerShell 的 Desktop 。
例如：
#Requires -PSEdition Core
-ShellId
指定腳本所需的殼層。 輸入殼層標識碼。 如果您使用 ShellId 參數，也必須包含 PSSnapin 參數。
您可以藉由查詢自動變數來尋找目前的 $ShellId。
例如：
#Requires -ShellId MyLocalShell -PSSnapin Microsoft.PowerShell.Core
注意
此參數適用於已被取代的迷你殼層。
-RunAsAdministrator
將此參數新增至語句 #Requires 時，它會指定您執行腳本的PowerShell工作階段必須以提升的使用者權力啟動。 非 Windows 作業系統上會忽略 RunAsAdministrator 參數。
RunAsAdministrator 參數是在 PowerShell 4.0 中引進的。
例如：
#Requires -RunAsAdministrator
範例
下列腳本有兩個 #Requires 語句。 如果不符合這兩個語句中指定的需求，腳本就不會執行。 每個 #Requires 語句都必須是行上的第一個專案：
#Requires -Modules PSWorkflow
#Requires -Version 3
Param
(
[parameter(Mandatory=$true)]
[String[]]
$Path
)
...
