cmdlet 扩展代理

  • 项目

适用于：Exchange Server 2013

Cmdlet 扩展代理是在 cmdlet 运行时，由 Exchange 2013 cmdlet 调用的 Microsoft Exchange Server 2013 中的组件。 顾名思义，cmdlet 扩展代理可扩展 cmdlet 的功能，通过帮助处理数据或执行其他基于 cmdlet 要求的操作来调用这些功能。 Cmdlet 扩展代理在任何服务器角色上均可用。

这些代理可以修改、替换或扩展 Exchange 命令行管理程序 cmdlet 的功能。 代理可以执行以下操作：为所需参数提供值（该值未在命令上提供）、覆盖由用户提供的值、在 cmdlet 运行时执行其他 cmdlet 工作流以外的操作等。

例如， New-Mailbox cmdlet 接受 Database 参数，该参数指定要在其中创建新邮箱的邮箱数据库。 在 Microsoft Exchange Server 2007 中，如果在运行 New-Mailbox cmdlet 时未指定 Database 参数，则命令将失败。 但是，在 Exchange 2013 中， New-Mailbox cmdlet 会在 cmdlet 运行时调用 Mailbox Resources Management 代理。 如果未指定 Database 参数，代理 Mailbox Resources Management 会自动确定要在其上创建新邮箱的合适邮箱数据库，并将该值插入 到 Database 参数中。

只能通过 Exchange 2013 和 Microsoft Exchange Server 2010 cmdlet 来调用 cmdlet 扩展代理。 Exchange 2007 cmdlet 以及由其他 Microsoft 和第三方产品提供的 cmdlet 无法调用 cmdlet 扩展代理。 脚本也无法直接调用 cmdlet 扩展代理。 但是，如果脚本包含 Exchange 2013 cmdlet，则这些 cmdlet 可继续调用 cmdlet 扩展代理。

正在查找与 cmdlet 扩展代理相关的管理任务？ 请参阅 管理 cmdlet 扩展代理。

代理优先级

Cmdlet 运行时，代理的优先级会确定在其中调用代理的顺序。 首先调用有较高优先级的代理（更接近零）。 当两个或多个代理尝试设置相同属性的值时，代理的优先级变得非常重要。 优先级最高的代理将成功设置某个属性值，而所有尝试设置相同属性的较低优先级代理将被忽略。 例如，如果优先级为 3 的代理修改了某个对象上的 Name 属性，而优先级为 6 的另一个代理也修改相同对象，则由优先级为 6 的代理进行的修改将被忽略。

如果要使用 Scripting agent 设置可能由其他较高优先级代理设置的属性的值，可以使用以下选项：

  • 禁用当前设置该属性的代理。

  • Scripting agent将 设置为比要替换的现有代理更高的优先级。

  • 使代理的优先级保持不变，并确保在 下 Scripting agent 运行的脚本遵循其他代理提供的值。

警告

更改内置代理的优先级或替换内置代理的功能是一项高级操作。 请确保您完全了解要进行的更改。

有关更改代理优先级的详细信息，请参阅管理 cmdlet 扩展代理。

内置代理

Exchange 2013 包括多个可在 cmdlet 运行时调用的代理。 下表列出了这些代理、其顺序，以及默认情况下是否启用代理。 无法在运行 Exchange 2013 的服务器上添加或删除代理。 但是，可以使用 Scripting agent 运行Windows PowerShell脚本来扩展使用它的 cmdlet 的功能。 有关 的详细信息， Scripting agent请参阅本主题后面的“脚本代理”部分。

如果要将特定代理的功能替换为你在使用 调用的自定义脚本中提供的功能，可以启用或禁用大多数代理或更改代理的 Scripting agent优先级。 但是，无法禁用某些代理。 不能禁用的代理称为 系统代理 ，其 IsSystem 属性设置为 $True。 下表提供了有关 Exchange 2013 cmdlet 扩展代理（包括系统代理）的信息。

代理的配置存储在组织级别上。 启用或禁用代理，或设置其优先级时，您将在组织中的每台服务器上设置该代理配置。 例外是将脚本添加到 Scripting agent。 您必须分别对每个服务器上的脚本进行更新。 有关配置用于 的 Scripting agent脚本的详细信息，请参阅本主题后面的“脚本代理”部分。

警告

如果不完全了解每个代理所做的内容以及其与 Exchange cmdlet 交互的方式，则更改代理的优先级，或者启用（或禁用）代理，将会导致意外的结果。 在更改任何代理的配置之前，请确保完全了解所要的更改和结果，并验证自定义脚本是否将按预期工作。

Exchange 2013 cmdlet 扩展代理

代理名 优先级 默认情况下启用 系统代理
Admin Audit Log agent 255 True 是
Scripting agent 6 False 否
Mailbox Resources Management agent 5 True 否
OAB Resources Management agent 4 True 否
Query Base DN agent 3 True 否
Provisioning Policy agent 2 True 否
Rus agent 1 True 否
Mailbox Creation Time agent 0 True 否

脚本编写代理

可以使用 Scripting agent Exchange 2013 中的 cmdlet 扩展代理将自己的脚本逻辑插入到 Exchange cmdlet 的执行中。 使用 ， Scripting agent可以添加条件、替代值和设置报告。

警告

启用 Scripting agent cmdlet 扩展代理时，每次在运行 Exchange 2013 的服务器上运行 cmdlet 时，都会调用该代理。 这不仅包括你在 Exchange 命令行管理程序中直接运行的 cmdlet，还包括由 Exchange 服务运行的 cmdlet，以及 Exchange 管理中心 (EAC) 。 强烈建议在将更新后的配置文件复制到 Exchange 2013 服务器并启用 Scripting agent cmdlet 扩展代理之前，先测试脚本和对配置文件所做的任何更改。

每次运行 Exchange cmdlet 时，cmdlet 都会 Scripting agent 调用 cmdlet 扩展代理。 当调用此代理时，cmdlet 会检查是否有任何脚本配置为由 cmdlet 进行调用。 如果应为某个 cmdlet 运行某个脚本，则该 cmdlet 会尝试调用该脚本中定义的任何 API。 以下 API 可供使用，并按以下顺序进行调用：

  1. ProvisionDefaultProperties：此 API 可用于在创建对象时设置对象的属性值。 当设置某个值时，该值会返回给 cmdlet，而 cmdlet 会对属性设置值。 您可以在用户未指定值时对属性填充值，也可以覆盖用户指定的值。 此 API 会采用更高优先级代理设置的值。 Scripting agent cmdlet 扩展代理不会覆盖优先级较高的代理设置的值。

  2. UpdateAffectedIConfigurable：此 API 可用于在完成所有其他处理后设置对象的属性值，但尚未调用该 Validate API。 此 API 会采用更高优先级代理设置的值。 Scripting agent cmdlet 扩展代理不会覆盖优先级较高的代理设置的值。

  3. 验证：此 API 可用于验证 cmdlet 即将设置的对象属性上的值。 此 API 就在 cmdlet 写入任何数据之前进行调用。 可以配置允许 cmdlet 成功或失败的验证检查。 如果某个 cmdlet 通过此 API 中的验证检查，则允许该 cmdlet 写入数据。 如果 cmdlet 未能通过验证检查，则会返回此 API 中定义的任何错误。

  4. OnComplete：在所有 cmdlet 处理完成后使用此 API。 它可以用于执行处理后任务，如将数据写入外部数据库。

注意

运行 Scripting agent 带有 Get 谓词的 cmdlet 时，不会调用 cmdlet 扩展代理。

脚本编写代理配置文件

配置文件 Scripting agent 包含要 Scripting agent 运行 的所有脚本。 该配置文件中的脚本包含在 XML 标记中，这些标记定义脚本的开头和结尾，以及将数据传递给脚本所需的各个输入参数。 脚本使用 Windows PowerShell 语法进行编写。 该配置文件是使用下表中的元素或属性的 XML 文件。

脚本编写代理配置文件的属性

元素 属性 说明
Configuration 不适用 此元素包含 cmdlet 扩展代理可以运行的所有脚本 Scripting agent 。 标记 Feature 是此标记的子级。

配置文件中只有一个 Configuration 标记。
Feature 不适用 此元素包含与某个功能相关的一组脚本。 子标记中 ApiCall 定义的每个脚本扩展了 cmdlet 执行管道的特定部分。 此标记包含 Name 和 Cmdlets 属性。

标记下Configuration可以有多个Feature标记。
Name 此属性包含功能的名称。 使用此属性可帮助标识标记中包含的脚本所扩展的功能。
Cmdlets 此属性包含将此功能扩展中的脚本集使用的 Exchange cmdlet 列表。 可以指定多个 cmdlet，使用逗号分隔每个 cmdlet。
ApiCall 不适用 此元素包含可以扩展 cmdlet 执行管道某部分的脚本。 每个脚本在其扩展的 cmdlet 执行管道中，由 API 调用名称进行定义。 下面是可以扩展的 API 名称：
  • ProvisionDefaultProperties
  • UpdateAffectedIConfigurable
  • Validate
  • OnComplete
Name 此属性包括扩展 cmdlet 执行管道的 API 调用的名称。
Common 不适用 此元素包含可以由配置文件中任何脚本使用的功能。

每个 Exchange 2013 服务器都包含 文件夹中的文件 ScriptingAgentConfig.xml.sample %ExchangeInstallPath%CmdletExtensionAgents 。 如果启用脚本代理 cmdlet 扩展代理，则必须在每个 Exchange 2013 服务器上将此文件重命名为 ScriptingAgentConfig.xml。 示例配置文件包含示例脚本，可以使用这些脚本帮助了解如何向配置文件添加脚本。

在向配置文件添加了脚本之后，或如果对配置文件进行了更改，必须在组织中的每个 Exchange 2013 服务器上都更新该文件。 必须执行此操作，以确保每个服务器都包含 cmdlet 扩展代理运行的脚本 Scripting Agent 的最新版本。

脚本中常用的某些字符在 XML 中也具有特殊含义。 若要在脚本中使用这些字符，请使用转义序列。 例如，以下字符使用了转义序列：

  • 使用大于符号 () > ，而不是 >
  • 使用小于符号 () < ，而不是 $lt;
  • 使用，而不是与 ( & ) &amp;

启用脚本编写代理

Scripting agent默认情况下，cmdlet 扩展代理处于禁用状态。 启用 后， Scripting agent将对整个 Exchange 2013 组织启用代理。 在启用 之前， Scripting agent请验证 Scripting agent 是否已使用每个 Exchange 2013 服务器上的脚本正确重命名和更新配置文件。 如果未正确重命名配置文件，或者从其他 Exchange 2013 服务器向此计算机复制了配置文件，则每当 cmdlet 运行时，就会收到错误消息。

若要启用 ， Scripting agent必须执行以下操作：

  1. 将 ScriptingAgentConfig.xml.sample 文件 %ExchangeInstallPath%Bin\CmdletExtensionAgents 重命名为组织中每个 Exchange 2013 服务器上的ScriptingAgentConfig.xml。

    注意

    可以将配置文件从一个 Exchange 2013 服务器复制到其他 Exchange 2013 服务器。 请务必先更新要复制的配置文件，然后再进行复制。

  2. 在组织中每个 Exchange 2013 服务器上，将脚本添加到重命名后的配置文件。

  3. Scripting agent启用 cmdlet 扩展代理。 有关启用 cmdlet 扩展代理的详细信息，请参阅 管理 cmdlet 扩展代理。

脚本编写代理优先级

默认情况下， Scripting agent cmdlet 扩展代理在每隔一个代理之后运行，但代理除外 Scripting agent 。 如果希望创建的脚本替换现有代理，则必须禁用另一个代理或更改其中一个代理的优先级，以便 Scripting agent 先运行 cmdlet 扩展代理。 有关如何禁用代理或更改代理优先级的详细信息，请参阅 管理 cmdlet 扩展代理。