about_Requires

簡短描述

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

完整描述

#Requires 語句會防止腳本執行，除非符合 PowerShell 版本、模組（和版本）和版本必要條件。 如果不符合必要條件，PowerShell 不會執行腳本或提供其他運行時間功能，例如 Tab 鍵自動完成。

語法

#Requires -Version <N>[.<n>]
#Requires -Modules { <Module-Name> | <Hashtable> }
#Requires -PSEdition <PSEdition-Name>
#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

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

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

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

#Requires 語句不會載入模組中的類別和列舉定義。 使用腳本開頭的 using module 語句來匯入模組，包括 類別和列舉定義。 如需詳細資訊，請參閱 about_Using。

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

• ModuleName - 必要 指定模組名稱。
• GUID - 選擇性 指定模組的 GUID。
• 它也 必要 至少指定下列三個索引鍵的其中一個。
  • ModuleVersion - 指定模組的最低可接受的版本。
  • MaximumVersion - 指定模組的最大可接受的版本。
  • RequiredVersion - 指定模組的確切必要版本。 這無法與其他版本金鑰搭配使用。

例如：

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

-RunAsAdministrator

將此參數新增至您的 #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
)
...

另請參閱

• about_Automatic_Variables
• about_Language_Keywords