about_Requires

發行項
03/20/2024

簡短描述

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

詳細描述

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

語法

#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 元件名稱的路徑。元件參數是在 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 和 適用於 Windows PowerShell 的 Desktop 。

例如：

#Requires -PSEdition Core

-RunAs 管理員 istrator

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

例如：

#Requires -RunAsAdministrator

範例

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

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