Microsoft Dynamics CRM — плагины

Плагин — это настраиваемая бизнес-логика, которая интегрируется с Microsoft Dynamics CRM для изменения или расширения стандартного поведения платформы. Плагины действуют как обработчики событий и регистрируются для выполнения на определенном событии в CRM. Плагины написаны на C # или VB и могут работать как в синхронном, так и в асинхронном режиме.

Некоторые сценарии, где вы бы написали плагин:

• Вы хотите выполнить некоторую бизнес-логику, такую ​​как обновление определенных полей записи или обновление связанных записей и т. Д. При создании или обновлении записи CRM.

• Вы хотите вызывать внешний веб-сервис для определенных событий, таких как сохранение или обновление записи.

• Вы хотите динамически вычислять значения поля при открытии любой записи.

• Вы хотите автоматизировать такие процессы, как отправка электронных писем вашим клиентам по определенным событиям в CRM.

Вы хотите выполнить некоторую бизнес-логику, такую ​​как обновление определенных полей записи или обновление связанных записей и т. Д. При создании или обновлении записи CRM.

Вы хотите вызывать внешний веб-сервис для определенных событий, таких как сохранение или обновление записи.

Вы хотите динамически вычислять значения поля при открытии любой записи.

Вы хотите автоматизировать такие процессы, как отправка электронных писем вашим клиентам по определенным событиям в CRM.

Event Framework

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

Этапы плагинов

Весь конвейер плагинов разделен на несколько этапов, на которых вы можете зарегистрировать свою собственную бизнес-логику. Указанный этап конвейера указывает, на какой стадии цикла выполнения плагина выполняется ваш код плагина. Из всех указанных этапов конвейера в следующей таблице вы можете зарегистрировать свои пользовательские плагины только до и после событий. Вы не можете зарегистрировать плагины в Platform Core Main Operations.

Всякий раз, когда приложение CRM вызывает событие (например, сохранение или обновление записи), происходит следующая последовательность действий:

• Событие инициирует вызов веб-службы, и выполнение передается через этапы конвейера событий (до события, основные операции платформы, после события).

• Информация внутренне упаковывается как сообщение OrganizationRequest и, наконец, отправляется во внутренние методы веб-службы CRM и основные операции платформы.

• Сообщение OrganizationRequest сначала принимается подключаемыми модулями перед событием, которые могут изменить информацию, прежде чем передавать ее в основные операции платформы. После основных операций платформы сообщение упаковывается как OrganizationResponse и передается в плагин после операции. Плагины после операций могут по желанию изменить эту информацию, прежде чем передавать ее в асинхронный плагин.

• Плагины получают эту информацию в виде объекта контекста, который передается методу Execute, после чего происходит дальнейшая обработка.

• После завершения всей обработки плагина выполнение передается обратно в приложение, которое вызвало событие.

Событие инициирует вызов веб-службы, и выполнение передается через этапы конвейера событий (до события, основные операции платформы, после события).

Информация внутренне упаковывается как сообщение OrganizationRequest и, наконец, отправляется во внутренние методы веб-службы CRM и основные операции платформы.

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

Плагины получают эту информацию в виде объекта контекста, который передается методу Execute, после чего происходит дальнейшая обработка.

После завершения всей обработки плагина выполнение передается обратно в приложение, которое вызвало событие.

Плагин Сообщения

Сообщения — это события, в которых зарегистрирован плагин (или бизнес-логика). Например, вы можете зарегистрировать плагин в сущности «Создать сообщение контакта». Это будет запускать бизнес-логику всякий раз, когда создается новая запись контакта.

Для пользовательских объектов ниже приведены поддерживаемые сообщения, основанные на том, принадлежит ли объект пользователю или организации.

Для стандартных готовых сущностей существует более 100 поддерживаемых сообщений. Некоторые из этих сообщений применимы ко всем объектам, а некоторые относятся к определенным объектам. Вы можете найти полный список поддерживаемых сообщений в файле Excel внутри SDK: поддержка SDK \ Message-entity для plug-ins.xlsx

Написание плагин

В этом разделе мы изучим основы написания плагина. Мы создадим образец подключаемого модуля, который создает задачу Task для последующей работы с клиентом при каждом добавлении нового клиента в систему, то есть при создании новой записи Contactrecord в CRM.

Прежде всего, вам нужно будет включить ссылки на пространство имен Microsoft.Xrm.Sdk . CRM SDK содержит все необходимые сборки SDK. Предполагая, что вы уже загрузили и установили SDK в Главе 2, откройте Visual Studio. Создайте новый проект типа Библиотека классов. Вы можете назвать проект как SamplePlugins и нажать ОК.

Добавьте ссылку на сборку 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);
            }
         }
      }
   }
}

Ниже приведено пошаговое объяснение того, что делает этот код:

Шаг 1 — Реализует метод Execute, принимая в качестве параметра объект IServiceProvider. Поставщик услуг содержит ссылки на многие полезные объекты, которые вы собираетесь использовать в плагине.

Шаг 2 — Получает объект IPluginExecutionContext, используя метод GetService IServiceProvider.

Шаг 3 — Получает объект целевого объекта из коллекции объекта контекста InputParameters. Этот объект класса Entity ссылается на запись объекта Contact, в которой будет зарегистрирован наш плагин.

Шаг 4 — Затем он создает объект объекта «Задача» и устанавливает надлежащий предмет, описание, даты, категорию и относящиеся к объекту. Usingobjectid указывает, для какой записи контакта создается эта запись активности. Вы можете видеть, что код получает идентификатор родительской записи Contact с помощью context.OutputParameters и связывает его с созданной вами записью сущности Task.

Шаг 5 — Создает объект IOrganizationServiceFactory, используя объект IServiceProvider.

Шаг 6 — Создает объект IOrganizationService с использованием объекта IOrganizationServiceFactory.

Шаг 7 — Наконец, используя метод Create этого сервисного объекта. Создает последующее действие, которое сохраняется в CRM.

Подписание сборки плагина

Этот раздел применим только в том случае, если вы регистрируете сборку вашего плагина впервые. Вы должны войти в сборку с ключом, чтобы иметь возможность развернуть плагин. Щелкните правой кнопкой мыши решение и выберите Свойства.

Выберите вкладку «Подпись» слева и установите флажок «Подписать сборку». Затем выберите «Создать» из опции «Выбрать файл ключа строгого имени».

Введите имя файла ключей в качестве sampleplugins (это может быть любое другое имя). Снимите флажок Защитить мой ключевой файл с помощью пароля и нажмите ОК. Нажмите Сохранить.

Наконец, создайте решение. Щелкните правой кнопкой мыши → Build. Построение решения сгенерирует сборку DLL, которую мы будем использовать в следующей главе, чтобы зарегистрировать этот плагин.

Обработка исключений в плагине

Чаще всего ваша логика плагина должна обрабатывать исключения во время выполнения. Для синхронных плагинов вы можете вернуть исключение InvalidPluginExecutionException , которое покажет пользователю диалоговое окно с ошибкой. Диалог ошибок будет содержать пользовательское сообщение об ошибке, которое вы передаете объекту Message объекта исключения.

Если вы посмотрите на наш код, мы добавляем исключение InvalidPluginExecutionException в наш блок catch.

throw new InvalidPluginExecutionException(ex.Message); 

Заключение

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