Агенты расширения командлетаCmdlet extension agents

Применимо к: Exchange Server 2013Applies to: Exchange Server 2013

Агенты расширения командлетов — это компоненты Microsoft Exchange Server 2013, вызываемые с помощью командлетов Exchange 2013 при запуске командлета. Агенты расширения командлета расширяют возможности командлетов, которые их вызывают, при обработке данных или выполнении дополнительных действий в зависимости от требований командлета. Агенты расширения командлетов доступны на любой роли сервера.Cmdlet extension agents are components in Microsoft Exchange Server 2013 invoked by Exchange 2013 cmdlets when the cmdlets run. As the name implies, cmdlet extension agents extend the capabilities of the cmdlets that invoke them by assisting in processing data or performing additional actions based on the requirements of the cmdlet. Cmdlet extension agents are available on any server role.

Агенты позволяют изменять, заменять или расширять функции командлетов консоли управления Exchange. Агент позволяет указать значение необходимого параметра, которое не указано в команде, заменить определенное пользователем значение, выполнять другие действия за пределами рабочего потока командлета во время работы командлета и т. д.Agents can modify, replace, or extend functionality of Exchange Management Shell cmdlets. An agent can provide a value for a required parameter that isn't provided on a command, override a value provided by a user, perform other actions outside of the cmdlet workflow while a cmdlet runs, and more.

Например командлет New-Mailbox принимает параметр базы данных , который указывает базу данных почтовых ящиков, в котором необходимо создать новый почтовый ящик. В Microsoft Exchange Server 2007 Если не указать параметр базы данных при запуске командлета New-Mailbox , команда не выполняется. Тем не менее, вызывает командлет New-Mailbox в Exchange 2013 Mailbox Resources Management агента при выполнении командлета. Если параметр базы данных не указан, Mailbox Resources Management агента автоматически определяет базу данных подходящего почтовых ящиков создать новый почтовый ящик и вставляет это значение в параметр базы данных .For example, the New-Mailbox cmdlet accepts the Database parameter that specifies the mailbox database in which to create a new mailbox. In Microsoft Exchange Server 2007, if you don't specify the Database parameter when you run the New-Mailbox cmdlet, the command fails. However, in Exchange 2013, the New-Mailbox cmdlet invokes the Mailbox Resources Management agent when the cmdlet runs. If the Database parameter isn't specified, the Mailbox Resources Management agent automatically determines a suitable mailbox database on which to create the new mailbox and inserts that value into the Database parameter.

Агенты расширения командлетов можно вызывать только в командлетах Exchange 2013 и Microsoft Exchange Server 2010. Командлеты Exchange 2007 и командлеты, предоставленные другими продуктами Майкрософт и сторонних производителей, не могут вызывать агенты расширения командлетов. Сценарии также не позволяют вызывать агенты расширения командлетов напрямую. Тем не менее, если сценарии содержат командлеты Exchange 2013, эти командлеты позволяют вызывать агенты расширения командлетов.Cmdlet extension agents can only be invoked by Exchange 2013 and Microsoft Exchange Server 2010 cmdlets. Exchange 2007 cmdlets and cmdlets provided by other Microsoft and third-party products can't invoke cmdlet extension agents. Scripts also can't invoke cmdlet extension agents directly. However, if scripts contain Exchange 2013 cmdlets, those cmdlets continue to call the cmdlet extension agents.

Необходимы сведения о других задачах управления, связанных с агентами расширения командлетов? См. раздел Управление агентами расширения командлетов.Looking for management tasks related to cmdlet extension agents? See Manage cmdlet extension agents.

Приоритет агентовAgent priority

Приоритет агента определяет порядок вызова агентов во время работы командлета. Агент с более высоким приоритетом (ближе к 0) вызывается в первую очередь. Приоритет агента очень важен, когда два или более агентов пытаются установить значение одного свойства. Свойство устанавливает агент с наиболее высоким приоритетом, а все последующие попытки установки этого же свойства агентами с более низким приоритетом пропускаются. Например, если свойство Name объекта изменено агентом с приоритетом 3, и другой агент с приоритетом 6 попытается изменить этот же объект, изменения агента с приоритетом 6 будут пропущены.The priority of an agent determines the order in which the agent is invoked while a cmdlet runs. An agent that has a higher priority, closer to zero, is invoked first. The priority of an agent becomes important when two or more agents attempt to set the value of the same property. The highest priority agent that attempts to set a property value succeeds, and all subsequent attempts to set the same property by lower priority agents are ignored. For example, if the Name property on an object is modified by an agent with a priority of 3 and another agent with a priority of 6 modifies the same object, the modification made by the agent with a priority of 6 is ignored.

Если вы хотите использовать Scripting agent для задания значения свойства, которые могут быть заданы посредством другие, более высокого приоритета агенты, у вас есть следующие параметры:If you want to use the Scripting agent to set the value of properties that might be set by other, higher priority agents, you have the following options:

  • Отключите агент, который в настоящее время устанавливает свойство.Disable the agent that currently sets the property.

  • Установка Scripting agent приоритет выше, чем существующего агента, необходимо заменить.Set the Scripting agent to a priority higher than the existing agent you want to replace.

  • Оставьте приоритеты агентам же и убедитесь в том, что скрипт, выполняемый в Scripting agent учитывает ли это значение, заданное для других агентов.Keep the priorities of the agents the same and make sure that the script that runs under the Scripting agent respects the value provided by the other agents.

Предупреждение

Изменение приоритета или замена функций встроенного агента являются дополнительными операциями. Убедитесь, что имеете полное представление о производимых изменениях.Changing the priority or replacing the functionality of a built-in agent is an advanced operation. Be sure that you completely understand the changes you're making.

Дополнительные сведения об изменении приоритета агента см. в разделе Управление агентами расширения командлетов.For more information about changing the priority of an agent, see Manage cmdlet extension agents.

Встроенные агентыBuilt-in agents

Exchange 2013 включает несколько агентов, которые могут вызываться при запуске командлета. В следующей таблице перечислены агенты, их порядок и по умолчанию включены агентов. Не удается добавить или удалить агенты или из сервере под управлением Exchange 2013. Тем не менее, можно использовать Scripting agent для запуска сценариев Windows PowerShell для расширения возможностей командлетов, которые его использования. Дополнительные сведения о Scripting agent, обратитесь к разделу «Агент сценариев» в этом разделе.Exchange 2013 includes several agents that can be invoked when a cmdlet runs. The following table lists the agents, their order, and whether the agents are enabled by default. You can't add or remove agents to or from a server running Exchange 2013. However, you can use the Scripting agent to run Windows PowerShell scripts to extend the functionality of the cmdlets that use it. For more information about the Scripting agent, see the “Scripting agent” section later in this topic.

Можно включить или отключить большинство агенты или изменение приоритета агентам, если вы хотите заменить функциональные возможности определенного агента функциональные возможности предоставления в пользовательский сценарий, который вызывается с помощью Scripting agent. Тем не менее некоторые агенты не может быть отключен. Агенты, которые не могут быть отключены называемых агентами системы и задайте свойства IsSystem $True. Следующей таблице приведены сведения о Exchange 2013 командлет агенты расширения, включая агенты системы.You can enable or disable most agents or change the priority of the agents if you want to replace the functionality of a specific agent with functionality you provide in a custom script that you call using the Scripting agent. However, some agents can’t be disabled. Agents that can’t be disabled are called system agents and have their IsSystem property set to $True. The following table provides information about Exchange 2013 cmdlet extension agents, including system agents.

Конфигурация для агентов хранится на уровне организации. При включить или отключить агент или задать его приоритета конфигурации агента установите на каждом сервере в организации. Исключение Добавление скрипты для Scripting agent. Скрипты на каждом сервере, необходимо обновить по отдельности. Дополнительные сведения о настройке сценарии для использования с Scripting agent, обратитесь к разделу «Агент сценариев» в этом разделе.The configuration for agents is stored at the organization level. When you enable or disable an agent, or set its priority, you set that agent configuration across every server in the organization. The exception is adding scripts to the Scripting agent. You must update the scripts on each server individually. For more information about configuring scripts for use with the Scripting agent, see the “Scripting agent” section later in this topic.

Предупреждение

В случае непонимания принципов работы агентов и способов их взаимодействия с командлетами Exchange изменение приоритета агентов, их включение или отключение может привести к непредвиденным последствиям. Перед изменением конфигурации агента убедитесь, что имеете полное представление о выполняемых изменениях и желаемых результатах, и проверьте правильность работы настраиваемого сценария.Changing the priority of agents, or enabling or disabling agents, can cause unintended effects if you don't completely understand what each agent does and how they interact with Exchange cmdlets. Before you change the configuration of any agent, be sure you fully understand the changes and results you want and that you verify that your custom script will work as intended.

Агенты расширения командлета Exchange 2013Exchange 2013 cmdlet extension agents

Имя агентаAgent name ПриоритетPriority Включено по умолчаниюEnabled by default Системный агентSystem agent

Admin Audit Log agent

255255

ИстинаTrue

ДаYes

Scripting agent

6 6

ЛожьFalse

НетNo

Mailbox Resources Management agent

55

ИстинаTrue

НетNo

OAB Resources Management agent

4 4

ИстинаTrue

НетNo

Query Base DN agent

3 3

ИстинаTrue

НетNo

Provisioning Policy agent

2 2

ИстинаTrue

НетNo

Rus agent

1 1

ИстинаTrue

НетNo

Mailbox Creation Time agent

00

ИстинаTrue

НетNo

Агент сценарияScripting agent

Можно использовать Scripting agent агента расширения командлета в Exchange 2013 для вставки сценариев логику в выполнения командлетов Exchange. С помощью Scripting agent, можно добавить условия, переопределить значения и настройка отчетов.You can use the Scripting agent cmdlet extension agent in Exchange 2013 to insert your own scripting logic into the execution of Exchange cmdlets. Using the Scripting agent, you can add conditions, override values, and set up reporting.

Предупреждение

При включении Scripting agent агента расширения командлета, агент вызывается каждый раз командлет на сервере под управлением Exchange 2013. Это включает в себя не только командлетов, которые напрямую, то в командной консоли Exchange, но командлетов, которые службами Exchange и Центр администрирования Exchange (EAC). Настоятельно рекомендуется тестировать сценарии и все изменения, вносимые в файл конфигурации, перед копированием обновленные настройки файлов на серверах Exchange 2013 и включить Scripting agent агента расширения командлета.When you enable the Scripting agent cmdlet extension agent, the agent is invoked every time a cmdlet is run on a server running Exchange 2013. This includes not only cmdlets run directly by you in the Exchange Management Shell, but also cmdlets run by Exchange services, and the Exchange Administration Center (EAC). We strongly recommend that you test your scripts and any changes you make to the configuration file before you copy your updated configuration file to your Exchange 2013 servers and enable the Scripting agent cmdlet extension agent.

Каждый раз командлет Exchange, вызывает командлет Scripting agent агента расширения командлета. При вызове данный агент командлета проверяет, настроены ли какие-либо сценарии для вызова командлета. Если необходимо запустить сценарий использования командлета, командлет пытается вызвать любой API, определенного в сценарии. Следующие интерфейсы API, доступны и вызываются в следующем порядке:Every time an Exchange cmdlet is run, the cmdlet invokes the Scripting agent cmdlet extension agent. When this agent is invoked, the cmdlet checks whether any scripts are configured to be invoked by the cmdlet. If a script should be run for a cmdlet, the cmdlet tries to invoke any APIs defined in the script. The following APIs are available and are invoked in the following order:

  1. ProvisionDefaultProperties Этот интерфейс API можно использовать для установки значений свойств объектов во время создания. Если задано значение, возвращаемое значение командлета и командлет устанавливает значение свойства. Если пользователь не указать значение или может переопределять значение, заданное пользователем значения свойств можно заполнить. Этот интерфейс API учитывает ли это значения, установленные для более высокого приоритета агентов. Scripting agent Агента расширения командлета не перезаписать значения, установленные для более высокого приоритета агентов.ProvisionDefaultProperties This API can be used to set values of properties on objects when they're created. When you set a value, that value is returned to the cmdlet and the cmdlet sets the value on the property. You can fill in values on properties if the user didn't specify a value, or you can override the value specified by the user. This API respects the values set by higher priority agents. The Scripting agent cmdlet extension agent won't overwrite the values set by higher priority agents.

  2. UpdateAffectedIConfigurable Этот интерфейс API можно использовать для установки значений свойств объектов, после выполнения всех обработки, но Validate еще не выполнялся вызов API. Этот интерфейс API учитывает ли это значения, установленные для более высокого приоритета агентов. Scripting agent Агента расширения командлета не перезаписать значения, установленные для более высокого приоритета агентов.UpdateAffectedIConfigurable This API can be used to set values of properties on objects after all other processing has been completed, but the Validate API hasn't yet been invoked. This API respects the values set by higher priority agents. The Scripting agent cmdlet extension agent won't overwrite the values set by higher priority agents.

  3. Проверка Этот интерфейс API можно использовать для проверки значения для свойств объекта, которые должны устанавливаться с помощью командлета. Этот интерфейс API вызывается непосредственно перед командлет записывает данные. Вы можете настроить проверку, позволяющих командлет, чтобы выполнен удачно или нет. Если командлет прохода, которые проверок в этот интерфейс API, командлет может записать данные. В случае сбоя проверки командлет возвращает все ошибки, определенных в этот интерфейс API.Validate This API can be used to validate the values on an object's properties that are about to be set by the cmdlet. This API is called just before a cmdlet writes any data. You can configure validation checks that allow a cmdlet to either succeed or fail. If a cmdlet passes the validation checks in this API, the cmdlet is allowed to write the data. If the cmdlet fails the validation checks, it returns any errors defined in this API.

  4. OnComplete Этот интерфейс API используется после завершения обработки всех командлетов. Его можно использовать для выполнения последующей обработки задач, таких как записи данных к внешней базе данных.OnComplete This API is used after all cmdlet processing is complete. It can be used to perform post-processing tasks, such as writing data to an external database.

Примечание

Scripting agent Агента расширения командлета не будет вызван при командлеты с Get при запуске команды.The Scripting agent cmdlet extension agent isn't invoked when cmdlets with the Get verb are run.

Файл конфигурации агента сценарияScripting agent configuration file

Scripting agent Файл конфигурации содержит все сценарии, которые будут Scripting agent для запуска. Скрипты в файле конфигурации содержатся в XML-тегов, которые определяют начала и окончания сценария и различные входные параметры, необходимые для передачи данных в сценарий. При создании сценариев с использованием синтаксиса Windows PowerShell. Файл конфигурации — это XML-файл, который использует элементы или атрибуты в следующей таблице.The Scripting agent configuration file contains all the scripts that you want the Scripting agent to run. Scripts in the configuration file are contained within XML tags that define the beginning and end of the script and various input parameters required to pass data to the script. Scripts are written using Windows PowerShell syntax. The configuration file is an XML file that uses the elements or attributes in the following table.

Атрибуты файла конфигурации агента сценарияAttributes of Scripting agent configuration file

ЭлементElement АтрибутAttribute ОписаниеDescription

Configuration

НеприменимоNot applicable

Этот элемент содержит все сценарии, Scripting agent можно запустить агента расширения командлета. Feature Тег является дочерним элементом этот тег.This element contains all the scripts that the Scripting agent cmdlet extension agent can run. The Feature tag is a child of this tag.

Существует только один Configuration тега в файле конфигурации.There is only one Configuration tag in the configuration file.

Feature

НеприменимоNot applicable

Этот элемент содержит набор скриптов, которые относятся к компонента. Каждого сценария, определенный в ApiCall дочерний тег расширяет определенной части конвейера выполнения командлета. Этот тег содержит Name и Cmdlets атрибуты.This element contains a set of scripts that relate to a feature. Each script, defined in the ApiCall child tag, extends a specific part of the cmdlet execution pipeline. This tag contains the Name and Cmdlets attributes.

Может существовать несколько Feature теги в разделе Configuration тег.There can be multiple Feature tags under the Configuration tag.

Name

Этот атрибут содержит имя функции. Этот атрибут позволяет определить функцию, которая расширяется сценарием, содержащимся в теге.This attribute contains the name of the feature. Use this attribute to help identify which feature is extended by the scripts contained within the tag.

Cmdlets

В этом атрибуте содержится список командлетов Exchange, которые будут использоваться набором сценариев в этом расширении функции. Можно указать несколько командлетов, разделяя их запятыми.This attribute contains a list of the Exchange cmdlets used by the set of scripts in this feature extension. You can specify multiple cmdlets by separating each cmdlet with a comma.

ApiCall

НеприменимоNot applicable

Этот элемент содержит сценарии, которые могут расширять участок конвейера выполнения командлета. Каждый сценарий определяется именем вызова API в расширяемом конвейере выполнения командлета. Ниже приведены имена API, которые могут быть расширены. This element contains scripts that can extend a part of the cmdlet execution pipeline. Each script is defined by the API call name in the cmdlet execution pipeline it's extending. The following are the API names that can be extended:

  • ProvisionDefaultProperties

  • UpdateAffectedIConfigurable

  • Validate

  • OnComplete

Name

Этот атрибут включает в себя имя вызова API, который расширяет конвейер выполнения командлета.This attribute includes the name of the API call that's extending the cmdlet execution pipeline.

Common

НеприменимоNot applicable

Этот элемент содержит функции, которые могут использоваться любым сценарием в файле конфигурации.This element contains functions that can be used by any script in the configuration file.

Каждый сервер Exchange 2013 включает в себя файл ScriptingAgentConfig.xml.sample в < путь установки>\V15\Bin\CmdletExtensionAgents папки. Этот файл должен называться ScriptingAgentConfig.xml на каждом сервере Exchange 2013 при включении агента расширения командлета агент сценариев. Пример файла конфигурации содержит примеры сценариев, которые можно использовать, которые помогут вам понять, как добавить скрипты в файле конфигурации.Every Exchange 2013 server includes the file ScriptingAgentConfig.xml.sample in the <installation path>\V15\Bin\CmdletExtensionAgents folder. This file must be renamed to ScriptingAgentConfig.xml on every Exchange 2013 server if you enable the Scripting Agent cmdlet extension agent. The sample configuration file contains sample scripts that you can use to help you understand how to add scripts to the configuration file.

После добавления скрипта в файле конфигурации или внести изменения в файл конфигурации, необходимо обновить файл на каждом сервере Exchange 2013 в вашей организации. Это необходимо сделать, чтобы убедиться в том, что каждый сервер содержит актуальную версию сценариев, Scripting Agent запускает агента расширения командлета.After you add a script to the configuration file, or if you make a change to the configuration file, you must update the file on every Exchange 2013 server in your organization. This must be done to make sure that each server contains an up-to-date version of the scripts that the Scripting Agent cmdlet extension agent runs.

Некоторые символы, обычно используемые в сценариях, также имеют определенное значение в языке XML. Для использования этих символов в сценарии необходимо использовать escape-последовательности. Например, для следующих символов используются escape-последовательности.Some characters typically used in scripts also have a special meaning in XML. To use these characters in your script, use escape sequences. For example, the following characters use an escape sequence:

  • Вместо a, больше, чем входа ( > ), используйте&gt;Instead of a greater than sign ( > ), use &gt;

  • А не менее чем входа ( < ), используйте$lt;Instead of a less than sign ( < ), use $lt;

  • Вместо амперсанд ( & ), используйте&amp;Instead of an ampersand ( & ), use &amp;

Включение агента сценарияEnable the Scripting agent

Scripting agent По умолчанию отключен агента расширения командлета. При включении Scripting agent, агент включен для всей организации Exchange 2013. Прежде чем включить Scripting agent, убедитесь, что Scripting agent файл конфигурации был правильно переименованы и добавлены сценариев на каждом сервере Exchange 2013. Вы получите сообщение об ошибке при каждом командлета выполняется, если не правильно переименуйте файл конфигурации и скопируйте файл конфигурации для данного компьютера от другого сервера Exchange 2013.The Scripting agent cmdlet extension agent is disabled by default. When you enable the Scripting agent, the agent is enabled for the entire Exchange 2013 organization. Before you enable the Scripting agent, verify that the Scripting agent configuration file has been correctly renamed and updated with your scripts on every Exchange 2013 server. You will receive an error message each time a cmdlet runs if you don't rename the configuration file correctly or copy a configuration file to this computer from another Exchange 2013 server.

Чтобы включить Scripting agent, необходимо выполнить следующие действия:To enable the Scripting agent, you must do the following:

  1. Переименуйте файл ScriptingAgentConfig.xml.sample в ** <путь установки>\V15\Bin\CmdletExtensionAgents** для ScriptingAgentConfig.xml на каждом сервере Exchange 2013 в вашей организации.Rename the ScriptingAgentConfig.xml.sample file in <installation path>\V15\Bin\CmdletExtensionAgents to ScriptingAgentConfig.xml on every Exchange 2013 server in your organization.

    Примечание

    Файл конфигурации можно скопировать с одного сервера Exchange 2013 на другие серверы Exchange 2013. Перед копированием файла конфигурации убедитесь, что он обновлен.You can copy the configuration file from one Exchange 2013 server to other Exchange 2013 servers. Be sure you update the configuration file you want to copy before you copy it.

  2. Добавьте свой сценарий в переименованный файл конфигурации на каждом сервере Exchange 2013 в организации.Add your script to the renamed configuration file on every Exchange 2013 server in your organization.

  3. Включение Scripting agent агента расширения командлета. Дополнительные сведения о включении агенты расширения командлета можно Управление агенты расширения командлета.Enable the Scripting agent cmdlet extension agent. For more information about enabling cmdlet extension agents, see Manage cmdlet extension agents.

Приоритет агента сценарияScripting Agent priority

По умолчанию Scripting agent агента расширения командлета выполняется после всех других агентов, за исключением элемента Scripting agent агента. Если необходимо, чтобы скрипт, созданный для замены существующей агента, необходимо отключить другие агента или изменения приоритета либо агента, чтобы Scripting agent агента расширения командлета выполняться в первую очередь. Дополнительные сведения о том, как отключить или изменить приоритет агенты можно Управление агенты расширения командлета.By default, the Scripting agent cmdlet extension agent runs after every other agent, with the exception of the Scripting agent agent. If you want a script you created to replace an existing agent, you must either disable the other agent or change the priority of either agent so that the Scripting agent cmdlet extension agent runs first. For more information about how to disable or change the priority of agents, see Manage cmdlet extension agents.