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 會擲回終止錯誤。

針對每個模組， (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

當此參數新增至語句 #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
)
...

另請參閱