Агенты расширения командлета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 принимает параметр Database , который указывает базу данных почтовых ящиков для создания нового почтового ящика.For example, the New-Mailbox cmdlet accepts the Database parameter that specifies the mailbox database in which to create a new mailbox. Если в Microsoft Exchange Server 2007 не указать параметр Database при выполнении командлета 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. Однако в Exchange 2013 командлет New – Mailbox вызывает Mailbox Resources Management агент при запуске командлета.However, in Exchange 2013, the New-Mailbox cmdlet invokes the Mailbox Resources Management agent when the cmdlet runs. Если параметр Database не указан, Mailbox Resources Management агент автоматически определяет подходящую базу данных почтовых ящиков для создания нового почтового ящика и вставляет это значение в параметр Database .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 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. Вы не можете добавлять или удалять агенты на сервере с Exchange 2013.You can't add or remove agents to or from a server running Exchange 2013. Тем не менее, вы можете Scripting agent использовать сценарии для запуска сценариев Windows PowerShell, чтобы расширить функциональные возможности командлетов, использующих его.However, you can use the Scripting agent to run Windows PowerShell scripts to extend the functionality of the cmdlets that use it. Дополнительные сведения об этом Scripting agentможно найти в разделе Scripting Agent (Scripting Agent) далее в этом разделе.For more information about the Scripting agent, see the "Scripting agent" section later in this topic.

Вы можете включить или отключить большинство агентов или изменить приоритет агентов, если вы хотите заменить функциональные возможности определенного агента возможностями, которые вы выдаете в пользовательском скрипте, который вызывается с помощью Scripting agent.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. Агенты, которые не могут быть отключены, называются системными агентами и имеют $Trueзначение свойства. **Agents that can't be disabled are called system agents and have their IsSystem property set to $True. В следующей таблице приведены сведения об агентах расширения командлета Exchange 2013, в том числе системных агентах.The following table provides information about Exchange 2013 cmdlet extension agents, including system agents.

Конфигурация агентов хранится на уровне организации.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. Исключение добавляет скрипты в Scripting agent.The exception is adding scripts to the Scripting agent. Обновление сценариев необходимо выполнять отдельно на каждом сервере.You must update the scripts on each server individually. Дополнительные сведения о настройке скриптов для использования с помощью Scripting agentможно найти в разделе "Агент сценариев" Далее в этой статье.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 PriorityPriority Включено по умолчаниюEnabled by default Системный агентSystem agent

Admin Audit Log agent

255255

TrueTrue

ДаYes

Scripting agent

6 6

ЛожьFalse

НетNo

Mailbox Resources Management agent

17:005

ИстинаTrue

НетNo

OAB Resources Management agent

SP44

ИстинаTrue

НетNo

Query Base DN agent

43

ИстинаTrue

НетNo

Provisioning Policy agent

22

ИстинаTrue

НетNo

Rus agent

1,11

ИстинаTrue

НетNo

Mailbox Creation Time agent

нуль0

ИстинаTrue

НетNo

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

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

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

При включении агента Scripting agent расширения командлета Агент вызывается каждый раз при выполнении командлета на сервере Exchange 2013.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. Сюда входят не только командлеты, которые выполняются непосредственно в командной консоли Exchange, но командлеты запускаются службами Exchange и центром администрирования Exchange.This includes not only cmdlets run directly by you in the Exchange Management Shell, but also cmdlets run by Exchange services, and the Exchange admin center (EAC). Настоятельно рекомендуется протестировать скрипты и все изменения, внесенные в файл конфигурации, прежде чем копировать обновленный файл конфигурации на серверы Exchange 2013 и включить агент расширения Scripting agent командлета.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 командлета.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. Если для командлета настроено выполнение сценария, командлет пытается вызвать любой из интерфейсов API, определенных в сценарии.If a script should be run for a cmdlet, the cmdlet tries to invoke any APIs defined in the script. В сценарии доступны следующие API, вызываемые в указанном ниже порядке.The following APIs are available and are invoked in the following order:

  1. Провисиондефаултпропертиес: Этот API можно использовать для установки значений свойств объектов при их создании.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. Этот API учитывает значения, установленные агентами с более высоким приоритетом.This API respects the values set by higher priority agents. Агент Scripting agent расширения командлета не перезаписывает значения, установленные агентами с более высоким приоритетом.The Scripting agent cmdlet extension agent won't overwrite the values set by higher priority agents.

  2. Упдатеаффектедиконфигурабле: Этот API можно использовать для установки значений свойств объектов после выполнения всех других действий, но Validate API еще не вызывался.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. Этот API учитывает значения, установленные агентами с более высоким приоритетом.This API respects the values set by higher priority agents. Агент Scripting agent расширения командлета не перезаписывает значения, установленные агентами с более высоким приоритетом.The Scripting agent cmdlet extension agent won't overwrite the values set by higher priority agents.

  3. Проверка: Этот 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. Если командлет проходит проверку в этом API, то ему разрешается запись данных.If a cmdlet passes the validation checks in this API, the cmdlet is allowed to write the data. Если командлет не проходит проверку, он возвращает ошибку, определенную в этом API.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 требуется выполнить.The Scripting agent configuration file contains all the scripts that you want the Scripting agent to run. Сценарии в файле конфигурации заключены в тегах XML, которые определяют начало и конец сценария, а также различные входные параметры, необходимые для передачи данных в сценарий.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. Сценарии пишутся по синтаксическим правилам Windows PowerShell.Scripts are written using Windows PowerShell syntax. В файле конфигурации, имеющем формат XML, используются элементы и атрибуты, приведенные в следующей таблице.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 может запускать агент расширения командлета.This element contains all the scripts that the Scripting agent cmdlet extension agent can run. Feature Тег является дочерним по отношению к этому тегу.The Feature tag is a child of this tag.

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

Feature

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

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

Тег может содержать несколько Feature ConfigurationThere 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\кмдлетекстенсионажентс Folder.Every Exchange 2013 server includes the file ScriptingAgentConfig.xml.sample in the <installation path>\V15\Bin\CmdletExtensionAgents folder. При включении агента расширения командлета «Агент сценария» имя этого файла необходимо изменить на ScriptingAgentConfig.xml на каждом сервере Exchange 2013.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 в организации.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. Это необходимо для того, чтобы убедиться, что на каждом сервере содержатся обновленные версии сценариев, выполняемые агентом расширения Scripting Agent командлета.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:

  • Вместо знака "больше" ( > ) используйте&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 умолчанию агент расширения командлета отключен.The Scripting agent cmdlet extension agent is disabled by default. Когда вы включаете Scripting agentэтот параметр, агент включается для всей организации Exchange 2013.When you enable the Scripting agent, the agent is enabled for the entire Exchange 2013 organization. Перед включением Scripting agentубедитесь, что файл Scripting agent конфигурации был правильно переименован и обновлен с помощью сценариев на каждом сервере Exchange 2013.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. Вы получите сообщение об ошибке при каждом запуске командлета, если неправильно переименовали файл конфигурации или не скопировали файл конфигурации на этот компьютер с другого сервера Exchange 2013.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 кмдлетекстенсионажентс** to 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 агента.By default, the Scripting agent cmdlet extension agent runs after every other agent, with the exception of the Scripting agent agent. Если вы хотите создать сценарий для замены существующего агента, необходимо отключить другой агент или изменить приоритет любого агента, чтобы агент расширения Scripting 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.