Microsoft Dynamics CRM - Плагины
Подключаемый модуль - это настраиваемая бизнес-логика, которая интегрируется с Microsoft Dynamics CRM для изменения или расширения стандартного поведения платформы. Плагины действуют как обработчики событий и регистрируются для выполнения при определенном событии в CRM. Плагины написаны на C # или VB и могут работать в синхронном или асинхронном режиме.
Вот некоторые сценарии, в которых вы могли бы написать плагин:
Вы хотите выполнить некоторую бизнес-логику, такую как обновление определенных полей записи или обновление связанных записей и т. Д., Когда вы создаете или обновляете запись CRM.
Вы хотите вызвать внешнюю веб-службу при определенных событиях, таких как сохранение или обновление записи.
Вы хотите динамически вычислять значения полей при открытии любой записи.
Вы хотите автоматизировать такие процессы, как отправка электронных писем своим клиентам об определенных событиях в CRM.
Рамки событий
Платформа обработки событий в CRM обрабатывает синхронные и асинхронные запросы подключаемых модулей, передавая их конвейеру выполнения событий. Каждый раз, когда событие запускает логику подключаемого модуля, в веб-службу организации CRM отправляется сообщение, где оно может быть прочитано или изменено другими подключаемыми модулями или любыми основными операциями платформы.
Этапы конвейера плагина
Весь конвейер плагинов разделен на несколько этапов, на которых вы можете зарегистрировать свою собственную бизнес-логику. Указанный этап конвейера указывает, на каком этапе цикла выполнения плагина выполняется код вашего плагина. Из всех этапов конвейера, указанных в следующей таблице, вы можете зарегистрировать свои настраиваемые плагины только до и после событий. Вы не можете зарегистрировать плагины в основных операциях Platform Core.
| Событие | Сценический псевдоним | Описание |
|---|---|---|
| До события | Предварительная проверка | Этап в конвейере для подключаемых модулей, которые должны выполняться перед основной операцией системы. Плагины, зарегистрированные на этом этапе, могут выполняться вне транзакции базы данных. |
| До события | Перед операцией | Этап в конвейере для подключаемых модулей, которые должны выполняться перед основной операцией системы. Плагины, зарегистрированные на этом этапе, выполняются в транзакции базы данных. |
| Операция ядра платформы | MainOperation | Интранзакция, основная операция системы, такая как создание, обновление, удаление и так далее. На этом этапе нельзя зарегистрировать настраиваемые плагины. Только для внутреннего использования. |
| Сообщение событие | Послеоперационный | Этап в конвейере для подключаемых модулей, которые должны выполняться после основной операции. Плагины, зарегистрированные на этом этапе, выполняются в транзакции базы данных. |
Каждый раз, когда приложение CRM вызывает событие (например, сохранение или обновление записи), происходит следующая последовательность действий:
Событие запускает вызов веб-службы, и выполнение проходит через этапы конвейера событий (до события, операции ядра платформы, после события).
Информация упаковывается внутри как сообщение OrganizationRequest и, наконец, отправляется во внутренние методы веб-службы CRM и основные операции платформы.
Сообщение OrganizationRequest сначала принимается подключаемыми модулями перед событием, которые могут изменять информацию перед передачей ее в основные операции платформы. После основных операций платформы сообщение упаковывается как OrganizationResponse и передается подключаемым модулям после операции. Плагины постопераций могут при желании изменить эту информацию перед передачей в плагин async.
Плагины получают эту информацию в виде объекта контекста, который передается методу Execute, после чего происходит дальнейшая обработка.
После того, как вся обработка плагина завершена, выполнение передается обратно в приложение, которое вызвало событие.
Сообщения плагина
Сообщения - это события, на которые зарегистрирован плагин (или бизнес-логика). Например, вы можете зарегистрировать плагин для создания сообщения контакта. Это будет запускать бизнес-логику всякий раз, когда создается новая запись контакта.
Для настраиваемых сущностей следующие сообщения поддерживаются в зависимости от того, принадлежит ли сущность пользователю или организации.
| Имя сообщения | Тип собственности |
|---|---|
| Назначить | Только объекты, принадлежащие пользователям |
| Создайте | Юридические лица, принадлежащие пользователям и организациям |
| удалять | Юридические лица, принадлежащие пользователям и организациям |
| Предоставление доступа | Только объекты, принадлежащие пользователям |
| ModifyAccess | Только объекты, принадлежащие пользователям |
| Получить | Юридические лица, принадлежащие пользователям и организациям |
| RetrieveMultiple | Юридические лица, принадлежащие пользователям и организациям |
| RetrievePrincipalAccess | Только объекты, принадлежащие пользователям |
| RetrieveSharedPrincipalsAndAccess | Только объекты, принадлежащие пользователям |
| RevokeAccess | Только объекты, принадлежащие пользователям |
| SetState | Юридические лица, принадлежащие пользователям и организациям |
| SetStateDynamicEntity | Юридические лица, принадлежащие пользователям и организациям |
| Обновить | Юридические лица, принадлежащие пользователям и организациям |
Для стандартных сущностей по умолчанию поддерживается более 100 сообщений. Некоторые из этих сообщений применимы ко всем объектам, в то время как некоторые из них относятся к определенным объектам. Вы можете найти полный список поддерживаемых сообщений в файле Excel внутри SDK:SDK\Message-entity support for plug-ins.xlsx
Плагин написания
В этом разделе мы изучим основы написания плагина. Мы будем создавать образец плагина, который создает действие Task для последующей работы с клиентом всякий раз, когда в систему добавляется новый клиент, то есть всякий раз, когда в CRM создается новая запись Contactrecord.
Прежде всего, вам нужно будет включить ссылки на Microsoft.Xrm.Sdkпространство имен. CRM SDK содержит все необходимые сборки SDK. Предполагая, что вы уже загрузили и установили SDK из главы 2, откройте Visual Studio. Создайте новый проект типа Class Library. Вы можете назвать проект SamplePlugins и нажать OK.
Добавьте ссылку на Microsoft.Xrm.Sdkсборка к вашему проекту. Сборка присутствует вSDK/Bin.
Теперь создайте класс с именем PostCreateContact.cs и расширить класс от IPlugin. До сих пор ваш код будет выглядеть примерно так.
Вам также потребуется добавить ссылку на System.Runtime.Serialization. После добавления необходимых ссылок скопируйте следующий код внутриPostCreateContact класс.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Microsoft.Xrm.Sdk;
namespace SamplePlugins {
public class PostCreateContact:IPlugin {
/// A plug-in that creates a follow-up task activity when a new account is created.
/// Register this plug-in on the Create message, account entity,
/// and asynchronous mode.
public void Execute(IServiceProviderserviceProvider) {
// Obtain the execution context from the service provider.
IPluginExecutionContext context =(IPluginExecutionContext)
serviceProvider.GetService(typeof(IPluginExecutionContext));
// The InputParameters collection contains all the data
passed in the message request.
if(context.InputParameters.Contains("Target")&&
context.InputParameters["Target"]isEntity) {
// Obtain the target entity from the input parameters.
Entity entity = (Entity)context.InputParameters["Target"];
try {
// Create a task activity to follow up with the account customer in 7 days
Entity followup = new Entity("task");
followup["subject"] = "Send e-mail to the new customer.";
followup["description"] =
"Follow up with the customer. Check if there are any new issues
that need resolution.";
followup["scheduledstart"] = DateTime.Now;
followup["scheduledend"] = DateTime.Now.AddDays(2);
followup["category"] = context.PrimaryEntityName;
// Refer to the contact in the task activity.
if(context.OutputParameters.Contains("id")) {
Guid regardingobjectid = new Guid(context.OutputParameter
s["id"].ToString());
string regardingobjectidType = "contact";
followup["regardingobjectid"] =
new EntityReference(rega rdingobjectidType,regardingobjectid);
}
// Obtain the organization service reference.
IOrganizationServiceFactory serviceFactory =
(IOrganizationSer viceFactory)serviceProvider.GetService
(typeof(IOrganizationServiceFactory));
IOrganizationService service =
serviceFactory.CreateOrganizationService(context.UserId);
// Create the followup activity
service.Create(followup);
} catch(Exception ex) {
throw new InvalidPluginExecutionException(ex.Message);
}
}
}
}
}Ниже приводится пошаговое объяснение того, что делает этот код.
Step 1- Реализует метод Execute, принимая объект IServiceProvider в качестве параметра. Поставщик услуг содержит ссылки на множество полезных объектов, которые вы собираетесь использовать в плагине.
Step 2 - Получает объект IPluginExecutionContext с помощью метода GetService IServiceProvider.
Step 3- Получает объект целевой сущности из коллекции InputParameters объекта контекста. Этот объект класса Entity ссылается на запись сущности Contact, в которой будет зарегистрирован наш плагин.
Step 4- Затем он создает объект сущности Task и устанавливает надлежащую тему, описание, даты, категорию и относящийся к объекту. Параметр aboutobjectid указывает, для какой записи контакта создается эта запись активности. Вы можете видеть, что код получает идентификатор родительской записи контакта с помощью context.OutputParameters и связывает его с записью сущности Task, которую вы создали.
Step 5 - Создает объект IOrganizationServiceFactory, используя объект IServiceProvider.
Step 6 - Создает объект IOrganizationService, используя объект IOrganizationServiceFactory.
Step 7- Наконец, используя метод Create этого служебного объекта. Он создает последующие действия, которые сохраняются в CRM.
Подписание сборки плагина
Этот раздел применим, только если вы впервые регистрируете сборку плагина. Вам необходимо войти в сборку с помощью ключа, чтобы иметь возможность развернуть плагин. Щелкните решение правой кнопкой мыши и выберите "Свойства".
Выберите вкладку «Подписание» в левой части окна и установите флажок «Подписать сборку». Затем выберите «Создать» в «Выбрать файл ключа строгого имени».
Введите имя файла ключей в качестве подключаемых модулей (это может быть любое другое имя). Снимите флажок Защитить мой ключевой файл паролем и нажмите ОК. Щелкните Сохранить.
Наконец, создайте решение. Щелкните правой кнопкой мыши → Сборка. При сборке решения будет сгенерирована сборочная DLL, которую мы будем использовать в следующей главе для регистрации этого плагина.
Обработка исключений в плагине
Чаще всего логика вашего плагина должна обрабатывать исключения времени выполнения. Для синхронных плагинов вы можете вернутьInvalidPluginExecutionExceptionисключение, которое покажет пользователю диалоговое окно с ошибкой. В диалоговом окне ошибки будет содержаться настраиваемое сообщение об ошибке, которое вы передаете объекту Message объекта исключения.
Если вы посмотрите на наш код, мы выбрасываем исключение InvalidPluginExecutionException в нашем блоке catch.
throw new InvalidPluginExecutionException(ex.Message);Заключение
Плагины, безусловно, имеют решающее значение для любой пользовательской реализации CRM. В этой главе мы сосредоточились на понимании модели фреймворка событий, этапов конвейера, сообщений и написании образца плагина. В следующей главе мы зарегистрируем этот плагин в CRM и посмотрим, как он работает от начала до конца.