about_Requires
簡短描述
防止腳本在沒有必要元素的情況下執行。
完整描述
除非 #Requires
符合 PowerShell 版本、模組 (和版本) ,或符合版本 (和版本) ,以及版本必要條件,否則語句會防止腳本執行。 如果不符合必要條件,PowerShell 不會執行腳本或提供其他運行時間功能,例如 Tab 鍵完成。
Syntax
#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 元件 <路徑> | <。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> | <哈希表>
指定文稿所需的 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 中新增。
例如:
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 和 Desktop,適用於 Windows PowerShell。
例如:
#Requires -PSEdition Core
-RunAsAdministrator
當這個 switch 參數新增至語句 #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
)
...