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

  • Статья

Область применения: Exchange Server 2013 г.

Агенты расширения командлетов — это компоненты Microsoft Exchange Server 2013, вызываемые с помощью командлетов Exchange 2013 при запуске командлета. Агенты расширения командлета расширяют возможности командлетов, которые их вызывают, при обработке данных или выполнении дополнительных действий в зависимости от требований командлета. Агенты расширения командлетов доступны на любой роли сервера.

Агенты могут изменять, заменять или расширять функциональные возможности командлетов командной консоли Exchange. Агент позволяет указать значение необходимого параметра, которое не указано в команде, заменить определенное пользователем значение, выполнять другие действия за пределами рабочего потока командлета во время работы командлета и т. д.

Например, командлет New-Mailbox принимает параметр Database , указывающий базу данных почтового ящика, в которой создается новый почтовый ящик. В Microsoft Exchange Server 2007 г., если не указать параметр Database при выполнении командлета New-Mailbox, команда завершится ошибкой. Однако в Exchange 2013 командлет New-Mailbox вызывает Mailbox Resources Management агент при выполнении командлета. Если параметр Database не указан, Mailbox Resources Management агент автоматически определяет подходящую базу данных почтовых ящиков, в которой будет создан новый почтовый ящик, и вставляет это значение в параметр Database .

Агенты расширения командлетов можно вызывать только в командлетах Exchange 2013 и Microsoft Exchange Server 2010. Командлеты Exchange 2007 и командлеты, предоставленные другими продуктами Майкрософт и сторонних производителей, не могут вызывать агенты расширения командлетов. Сценарии также не позволяют вызывать агенты расширения командлетов напрямую. Тем не менее, если сценарии содержат командлеты Exchange 2013, эти командлеты позволяют вызывать агенты расширения командлетов.

Ищете задачи управления, связанные с агентами расширения командлетов? См. раздел Управление агентами расширения командлетов.

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

Приоритет агента определяет порядок вызова агентов во время работы командлета. Агент с более высоким приоритетом (ближе к 0) вызывается в первую очередь. Приоритет агента очень важен, когда два или более агентов пытаются установить значение одного свойства. Свойство устанавливает агент с наиболее высоким приоритетом, а все последующие попытки установки этого же свойства агентами с более низким приоритетом пропускаются. Например, если свойство Name объекта изменено агентом с приоритетом 3, и другой агент с приоритетом 6 попытается изменить этот же объект, изменения агента с приоритетом 6 будут пропущены.

Если вы хотите использовать Scripting agent , чтобы задать значение свойств, которые могут быть заданы другими агентами с более высоким приоритетом, у вас есть следующие параметры:

  • Отключите агент, который в настоящее время устанавливает свойство.

  • Присвойте Scripting agent параметру приоритет выше, чем у существующего агента, который вы хотите заменить.

  • Оставьте приоритеты агентов одинаковыми и убедитесь, что скрипт, который выполняется в Scripting agent соответствии со значением, предоставленным другими агентами.

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

Изменение приоритета или замена функций встроенного агента являются дополнительными операциями. Убедитесь, что имеете полное представление о производимых изменениях.

Дополнительные сведения об изменении приоритета агента см. в разделе Управление агентами расширения командлетов.

Встроенные агенты

Exchange 2013 включает несколько агентов, которые можно вызывать при выполнении командлета. В следующей таблице перечислены агенты, их порядок и состояние по умолчанию (включен или отключен). Вы не можете добавлять или удалять агенты на сервере Exchange 2013 или с сервера. Однако можно использовать Scripting agent для выполнения Windows PowerShell скриптов, чтобы расширить функциональные возможности командлетов, которые его используют. Дополнительные сведения о Scripting agentсм. в разделе "Агент сценариев" далее в этом разделе.

Вы можете включить или отключить большинство агентов или изменить приоритет агентов, если вы хотите заменить функциональность определенного агента функциями, предоставляемыми в пользовательском скрипте, вызываемом Scripting agentс помощью . Однако некоторые агенты не могут быть отключены. Агенты, которые не могут быть отключены, называются системными агентами и имеют для свойства IsSystem значение $True. В следующей таблице приведены сведения об агентах расширения командлетов Exchange 2013, включая системные агенты.

Конфигурация агентов хранится на уровне организации. При включении, отключении агента или установке его приоритета изменение конфигурации агента выполняется на каждом сервере организации. Исключением является добавление скриптов в Scripting agent. Обновление сценариев необходимо выполнять отдельно на каждом сервере. Дополнительные сведения о настройке скриптов для использования с Scripting agentсм. в разделе "Агент сценариев" далее в этом разделе.

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

В случае непонимания принципов работы агентов и способов их взаимодействия с командлетами Exchange изменение приоритета агентов, их включение или отключение может привести к непредвиденным последствиям. Перед изменением конфигурации агента убедитесь, что имеете полное представление о выполняемых изменениях и желаемых результатах, и проверьте правильность работы настраиваемого сценария.

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

Имя агента Приоритет Включено по умолчанию Системный агент
Admin Audit Log agent 255 Истина Да
Scripting agent 6 Ложь Нет
Mailbox Resources Management agent 5 Истина Нет
OAB Resources Management agent 4 Истина Нет
Query Base DN agent 3 Истина Нет
Provisioning Policy agent 2 Истина Нет
Rus agent 1 Истина Нет
Mailbox Creation Time agent 0 Истина Нет

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

Агент расширения командлетов Scripting agent в Exchange 2013 можно использовать для вставки собственной логики сценариев в выполнение командлетов Exchange. Scripting agentС помощью можно добавлять условия, переопределять значения и настраивать отчеты.

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

При включении Scripting agent агента расширения командлетов агент вызывается при каждом запуске командлета на сервере с Exchange 2013. Сюда входят не только командлеты, выполняемые непосредственно вами в командной консоли Exchange, но и командлеты, выполняемые службами Exchange и Центром администрирования Exchange (EAC). Мы настоятельно рекомендуем протестировать скрипты и любые изменения, внесенные в файл конфигурации, прежде чем скопировать обновленный файл конфигурации на серверы Exchange 2013 и включить Scripting agent агент расширения командлетов.

При каждом запуске командлета Exchange командлет вызывает агент расширения командлета Scripting agent . При вызове этого агента командлет проверяет, необходимо ли выполнение какого-либо сценария. Если для командлета настроено выполнение сценария, командлет пытается вызвать любой из интерфейсов API, определенных в сценарии. В сценарии доступны следующие API, вызываемые в указанном ниже порядке.

  1. ProvisionDefaultProperties. Этот API можно использовать для задания значений свойств для объектов при их создании. При установке значения оно возвращается командлету, который устанавливает его для свойства. Администратор может задать значения для свойств, если они не были указаны пользователем, или может переопределить значение, указанное пользователем. Этот API учитывает значения, установленные агентами с более высоким приоритетом. Агент Scripting agent расширения командлета не перезаписывает значения, заданные агентами с более высоким приоритетом.

  2. UpdateAffectedIConfigurable. Этот API можно использовать для задания значений свойств объектов после завершения остальной обработки, но Validate API еще не был вызван. Этот API учитывает значения, установленные агентами с более высоким приоритетом. Агент Scripting agent расширения командлета не перезаписывает значения, заданные агентами с более высоким приоритетом.

  3. Проверка. Этот API можно использовать для проверки значений свойств объекта, которые будут заданы командлетом . Он вызывается непосредственно перед записью командлетом каких-либо данных. Проверку можно настроить таким образом, чтобы командлет мог пройти или не пройти ее. Если командлет проходит проверку в этом API, то ему разрешается запись данных. Если командлет не проходит проверку, он возвращает ошибку, определенную в этом API.

  4. OnComplete: этот API используется после завершения обработки всех командлетов. Он может использоваться для выполнения задач после обработки, таких как запись данных во внешнюю базу данных.

Примечание.

Агент Scripting agent расширения командлетов не вызывается при выполнении командлетов с командой Get .

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

Файл Scripting agent конфигурации содержит все скрипты, которые требуется Scripting agent выполнить. Сценарии в файле конфигурации заключены в тегах XML, которые определяют начало и конец сценария, а также различные входные параметры, необходимые для передачи данных в сценарий. Сценарии пишутся по синтаксическим правилам Windows PowerShell. В файле конфигурации, имеющем формат XML, используются элементы и атрибуты, приведенные в следующей таблице.

Атрибуты файла конфигурации агента сценария

Элемент Атрибут Описание
Configuration Неприменимо Этот элемент содержит все скрипты, которые Scripting agent может выполнять агент расширения командлетов. Тег Feature является дочерним для этого тега.

В файле конфигурации есть только один Configuration тег.
Feature Неприменимо Этот элемент содержит набор сценариев, относящихся к какой-либо функции. Каждый скрипт, определенный в дочернем ApiCall теге, расширяет определенную часть конвейера выполнения командлета. Этот тег содержит атрибуты Name и Cmdlets .

Под тегом может быть несколько Feature тегов Configuration .
Name Этот атрибут содержит имя функции. Этот атрибут позволяет определить функцию, которая расширяется сценарием, содержащимся в теге.
Cmdlets В этом атрибуте содержится список командлетов Exchange, которые будут использоваться набором сценариев в этом расширении функции. Можно указать несколько командлетов, разделяя их запятыми.
ApiCall Неприменимо Этот элемент содержит сценарии, которые могут расширять участок конвейера выполнения командлета. Каждый сценарий определяется именем вызова API в расширяемом конвейере выполнения командлета. Ниже приведены имена API, которые могут быть расширены.
  • ProvisionDefaultProperties
  • UpdateAffectedIConfigurable
  • Validate
  • OnComplete
Name Этот атрибут включает в себя имя вызова API, который расширяет конвейер выполнения командлета.
Common Неприменимо Этот элемент содержит функции, которые могут использоваться любым сценарием в файле конфигурации.

Каждый сервер Exchange 2013 содержит файл ScriptingAgentConfig.xml.sample в папке %ExchangeInstallPath%CmdletExtensionAgents . При включении агента расширения командлета «Агент сценария» имя этого файла необходимо изменить на ScriptingAgentConfig.xml на каждом сервере Exchange 2013. Пример файла конфигурации содержит образцы сценариев, которые помогут понять правила добавления сценариев в файл конфигурации.

После добавления сценария в файл конфигурации или при внесении изменений в этот файл его необходимо обновить на каждом сервере Exchange 2013 в организации. Это необходимо сделать, чтобы убедиться, что каждый сервер содержит последнюю версию скриптов, которые Scripting Agent запускает агент расширения командлетов.

Некоторые символы, обычно используемые в сценариях, также имеют определенное значение в языке XML. Для использования этих символов в сценарии необходимо использовать escape-последовательности. Например, для следующих символов используются escape-последовательности.

  • Вместо знака > больше ( ) используйте >
  • Вместо знака меньше , чем ( < ), используйте $lt;
  • Вместо амперсанда ( & ) используйте &amp;

Включение агента сценария

Агент Scripting agent расширения командлетов отключен по умолчанию. При включении Scripting agentагент включается для всей организации Exchange 2013. Прежде чем включить Scripting agent, убедитесь, что Scripting agent файл конфигурации был правильно переименован и обновлен с помощью скриптов на каждом сервере Exchange 2013. Вы получите сообщение об ошибке при каждом запуске командлета, если неправильно переименовали файл конфигурации или не скопировали файл конфигурации на этот компьютер с другого сервера Exchange 2013.

Чтобы включить Scripting agent, необходимо выполнить следующие действия:

  1. Переименуйте файл ScriptingAgentConfig.xml.sample в %ExchangeInstallPath%Bin\CmdletExtensionAgents ScriptingAgentConfig.xml на каждом сервере Exchange 2013 в организации.

    Примечание.

    Файл конфигурации можно скопировать с одного сервера Exchange 2013 на другие серверы Exchange 2013. Перед копированием файла конфигурации убедитесь, что он обновлен.

  2. Добавьте свой сценарий в переименованный файл конфигурации на каждом сервере Exchange 2013 в организации.

  3. Scripting agent Включите агент расширения командлета. Дополнительные сведения о включении агентов расширения командлетов см. в разделе Управление агентами расширения командлетов.

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

По умолчанию Scripting agent агент расширения командлета запускается после каждого другого Scripting agent агента, за исключением агента. Если вы хотите, чтобы созданный скрипт заменил существующий агент, необходимо либо отключить другой агент, либо изменить приоритет любого из них, Scripting agent чтобы агент расширения командлетов был запущен первым. Дополнительные сведения об отключении или изменении приоритета агентов см. в разделе Управление агентами расширения командлетов.