about_Requires

项目
10/07/2023

简短说明

防止脚本在缺少必要元素的情况下运行。

长说明

#Requires 语句可防止脚本运行，确保其只有在满足 PowerShell 版本、模块（及版本）或管理单元（及版本）和版本相关先决条件时才能运行。如果不满足相关先决条件，PowerShell 不会运行脚本或提供其他运行时功能（例如选项卡完成）。

语法

#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 中引入了 Assembly 参数。有关 .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。

为每个模块键入模块名称（<字符串>）或哈希表。其值可以是字符串和哈希表的组合。哈希表有以下键。

ModuleName - 必需指定模块名称。
GUID - 可选指定模块的 GUID。
还必需指定以下三个键中的至少一个。
- ModuleVersion - 指定模块的最低可接受版本。
- MaximumVersion - 指定模块的最低可接受版本。
- RequiredVersion - 指定模块所需的确切版本。这不能与其他版本键一起使用。

注意

Windows PowerShell 5.0 中添加了 RequiredVersion。 Windows PowerShell 5.1 中添加了 MaximumVersion。

例如：

要求安装 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 的桌面。

例如：

#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
)
...