Microsoft Dynamics CRM - ปลั๊กอิน

ปลั๊กอินคือตรรกะทางธุรกิจแบบกำหนดเองที่รวมเข้ากับ Microsoft Dynamics CRM เพื่อปรับเปลี่ยนหรือขยายลักษณะการทำงานมาตรฐานของแพลตฟอร์ม ปลั๊กอินทำหน้าที่เป็นตัวจัดการเหตุการณ์และได้รับการลงทะเบียนเพื่อดำเนินการกับเหตุการณ์เฉพาะใน CRM ปลั๊กอินเขียนด้วยภาษา C # หรือ VB และสามารถทำงานได้ทั้งในโหมดซิงโครนัสหรืออะซิงโครนัส

บางสถานการณ์ที่คุณจะเขียนปลั๊กอินคือ -

• คุณต้องการดำเนินการตามตรรกะทางธุรกิจบางอย่างเช่นการอัปเดตฟิลด์บางฟิลด์ของเรกคอร์ดหรืออัปเดตเรกคอร์ดที่เกี่ยวข้อง ฯลฯ เมื่อคุณสร้างหรืออัปเดตเรกคอร์ด CRM

• คุณต้องการเรียกใช้บริการเว็บภายนอกเกี่ยวกับเหตุการณ์บางอย่างเช่นการบันทึกหรืออัปเดตเรกคอร์ด

• คุณต้องการคำนวณค่าฟิลด์แบบไดนามิกเมื่อเปิดบันทึกใด ๆ

• คุณต้องการทำให้กระบวนการอัตโนมัติเช่นการส่งอีเมลไปยังลูกค้าของคุณเกี่ยวกับเหตุการณ์บางอย่างใน CRM

กรอบเหตุการณ์

Event Processing Framework ใน CRM ประมวลผลคำร้องขอปลั๊กอินซิงโครนัสและอะซิงโครนัสโดยส่งไปยังไปป์ไลน์การดำเนินการเหตุการณ์ เมื่อใดก็ตามที่เหตุการณ์ทริกเกอร์ตรรกะของปลั๊กอินข้อความจะถูกส่งไปยัง CRM Organization Web Service ซึ่งสามารถอ่านหรือแก้ไขโดยปลั๊กอินอื่น ๆ หรือการทำงานหลักของแพลตฟอร์ม

ขั้นตอนไปป์ไลน์ของปลั๊กอิน

ไปป์ไลน์ปลั๊กอินทั้งหมดแบ่งออกเป็นหลายขั้นตอนซึ่งคุณสามารถลงทะเบียนตรรกะทางธุรกิจที่กำหนดเองได้ ขั้นตอนไปป์ไลน์ที่ระบุระบุว่าในขั้นตอนใดของรอบการเรียกใช้ปลั๊กอินโค้ดปลั๊กอินของคุณจะทำงาน จากขั้นตอนไปป์ไลน์ที่ระบุทั้งหมดในตารางต่อไปนี้คุณสามารถลงทะเบียนปลั๊กอินที่กำหนดเองได้เฉพาะในช่วงก่อนและหลังเหตุการณ์ คุณไม่สามารถลงทะเบียนปลั๊กอินบน Platform Core Main Operations ได้

เหตุการณ์	ชื่อเวที	คำอธิบาย
ก่อนเหตุการณ์	การตรวจสอบล่วงหน้า	สเตจในไปป์ไลน์สำหรับปลั๊กอินที่จะดำเนินการก่อนการทำงานของระบบหลัก ปลั๊กอินที่ลงทะเบียนในขั้นตอนนี้อาจดำเนินการภายนอกธุรกรรมฐานข้อมูล
ก่อนเหตุการณ์	ก่อนการดำเนินการ	สเตจในไปป์ไลน์สำหรับปลั๊กอินที่จะดำเนินการก่อนการทำงานของระบบหลัก ปลั๊กอินที่ลงทะเบียนในขั้นตอนนี้จะดำเนินการภายในธุรกรรมฐานข้อมูล
การทำงานหลักของแพลตฟอร์ม	หลัก	Intransaction การทำงานหลักของระบบเช่นสร้างอัปเดตลบและอื่น ๆ ไม่สามารถลงทะเบียนปลั๊กอินที่กำหนดเองได้ในขั้นตอนนี้ สำหรับใช้ภายในเท่านั้น.
หลังเหตุการณ์	หลังการผ่าตัด	สเตจในไปป์ไลน์สำหรับปลั๊กอินซึ่งจะดำเนินการหลังจากการดำเนินการหลัก ปลั๊กอินที่ลงทะเบียนในขั้นตอนนี้จะดำเนินการภายในธุรกรรมฐานข้อมูล

เมื่อใดก็ตามที่แอปพลิเคชัน CRM เรียกใช้เหตุการณ์ (เช่นการบันทึกหรืออัปเดตเรกคอร์ด) ลำดับการดำเนินการต่อไปนี้จะเกิดขึ้น -

• เหตุการณ์จะทริกเกอร์การเรียกใช้บริการเว็บและการดำเนินการจะถูกส่งผ่านขั้นตอนไปป์ไลน์เหตุการณ์ (ก่อนเหตุการณ์, การดำเนินการหลักของแพลตฟอร์ม, หลังเหตุการณ์)

• ข้อมูลจะถูกบรรจุภายในเป็นข้อความ OrganizationRequest และส่งไปยังวิธีการบริการเว็บ CRM ภายในและการดำเนินการหลักของแพลตฟอร์มในที่สุด

• ข้อความ OrganizationRequest จะได้รับก่อนโดยปลั๊กอินก่อนเหตุการณ์ซึ่งสามารถแก้ไขข้อมูลก่อนที่จะส่งต่อไปยังการดำเนินการหลักของแพลตฟอร์ม หลังจากการดำเนินการหลักของแพลตฟอร์มข้อความจะถูกบรรจุเป็น OrganizationResponse และส่งต่อไปยังปลั๊กอินหลังการดำเนินการ ปลั๊กอิน postoperations สามารถเลือกแก้ไขข้อมูลนี้ได้ก่อนที่จะส่งต่อไปยังปลั๊กอิน async

• ปลั๊กอินรับข้อมูลนี้ในรูปแบบของวัตถุบริบทที่ส่งผ่านไปยังเมธอด Execute หลังจากนั้นการประมวลผลต่อไปจะเกิดขึ้น

• หลังจากการประมวลผลปลั๊กอินทั้งหมดเสร็จสิ้นการดำเนินการจะถูกส่งกลับไปยังแอปพลิเคชันที่เรียกใช้เหตุการณ์

ข้อความปลั๊กอิน

ข้อความคือเหตุการณ์ที่ลงทะเบียนปลั๊กอิน (หรือตรรกะทางธุรกิจ) ตัวอย่างเช่นคุณสามารถลงทะเบียนปลั๊กอินบนเอนทิตีสร้างข้อความของผู้ติดต่อ สิ่งนี้จะทำให้ตรรกะทางธุรกิจเริ่มทำงานเมื่อใดก็ตามที่มีการสร้างเรกคอร์ดผู้ติดต่อใหม่

สำหรับเอนทิตีแบบกำหนดเองต่อไปนี้เป็นข้อความที่สนับสนุนโดยขึ้นอยู่กับว่าเอนทิตีเป็นของผู้ใช้หรือองค์กรที่เป็นเจ้าของ

ชื่อข้อความ	ประเภทการเป็นเจ้าของ
กำหนด	เอนทิตีที่ผู้ใช้เป็นเจ้าของเท่านั้น
สร้าง	เอนทิตีที่ผู้ใช้เป็นเจ้าของและองค์กรที่เป็นเจ้าของ
ลบ	เอนทิตีที่ผู้ใช้เป็นเจ้าของและองค์กรที่เป็นเจ้าของ
GrantAccess	เอนทิตีที่ผู้ใช้เป็นเจ้าของเท่านั้น
ModifyAccess	เอนทิตีที่ผู้ใช้เป็นเจ้าของเท่านั้น
ดึงข้อมูล	เอนทิตีที่ผู้ใช้เป็นเจ้าของและองค์กรที่เป็นเจ้าของ
RetrieveMultiple	เอนทิตีที่ผู้ใช้เป็นเจ้าของและองค์กรที่เป็นเจ้าของ
RetrievePrincipalAccess	เอนทิตีที่ผู้ใช้เป็นเจ้าของเท่านั้น
RetrieveSharedPrincipalsAndAccess	เอนทิตีที่ผู้ใช้เป็นเจ้าของเท่านั้น
RevokeAccess	เอนทิตีที่ผู้ใช้เป็นเจ้าของเท่านั้น
SetState	เอนทิตีที่ผู้ใช้เป็นเจ้าของและองค์กรที่เป็นเจ้าของ
SetStateDynamicEntity	เอนทิตีที่ผู้ใช้เป็นเจ้าของและองค์กรที่เป็นเจ้าของ
อัปเดต	เอนทิตีที่ผู้ใช้เป็นเจ้าของและองค์กรที่เป็นเจ้าของ

สำหรับเอนทิตีที่ไม่อยู่ในกรอบเริ่มต้นมีข้อความที่รองรับมากกว่า 100 ข้อความ ข้อความเหล่านี้บางส่วนสามารถใช้ได้กับเอนทิตีทั้งหมดในขณะที่บางข้อความเป็นข้อความเฉพาะสำหรับบางเอนทิตี คุณสามารถค้นหารายการข้อความที่รองรับทั้งหมดในไฟล์ excel ภายใน SDK:SDK\Message-entity support for plug-ins.xlsx

การเขียนปลั๊กอิน

ในส่วนนี้เราจะเรียนรู้พื้นฐานการเขียนปลั๊กอิน เราจะสร้างปลั๊กอินตัวอย่างที่สร้างกิจกรรมงานเพื่อติดตามผลกับลูกค้าเมื่อใดก็ตามที่มีการเพิ่มลูกค้าใหม่ในระบบกล่าวคือเมื่อใดก็ตามที่มีการสร้าง Contactrecord ใหม่ใน CRM

ก่อนอื่นคุณจะต้องรวมการอ้างอิงถึง Microsoft.Xrm.Sdkเนมสเปซ CRM SDK ประกอบด้วยชุดประกอบ SDK ที่จำเป็นทั้งหมด สมมติว่าคุณได้ดาวน์โหลดและติดตั้ง SDK ในบทที่ 2 แล้วให้เปิด Visual Studio สร้างโครงการใหม่ประเภท Class Library คุณสามารถตั้งชื่อโครงการเป็น 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);
            }
         }
      }
   }
}

ต่อไปนี้เป็นคำอธิบายทีละขั้นตอนว่ารหัสนี้ทำอะไร -

Step 1- ใช้เมธอด Execute โดยใช้วัตถุ IServiceProvider เป็นพารามิเตอร์ ผู้ให้บริการมีการอ้างอิงถึงวัตถุที่มีประโยชน์มากมายที่คุณกำลังจะใช้ภายในปลั๊กอิน

Step 2 - รับวัตถุ IPluginExecutionContext โดยใช้เมธอด GetService ของ IServiceProvider

Step 3- รับวัตถุของเอนทิตีเป้าหมายจากคอลเล็กชัน InputParameters ของวัตถุบริบท อ็อบเจ็กต์คลาสเอนทิตีนี้อ้างถึงเรกคอร์ดเอนทิตีผู้ติดต่อที่จะลงทะเบียนปลั๊กอินของเรา

Step 4- จากนั้นจะสร้างออบเจ็กต์ของเอนทิตีงานและตั้งค่าหัวเรื่องคำอธิบายวันที่หมวดหมู่และวัตถุประสงค์ที่เหมาะสม Releobjectid ระบุว่าผู้ติดต่อใดกำลังสร้างเรกคอร์ดกิจกรรมนี้ คุณจะเห็นได้ว่ารหัสได้รับ id ของเรกคอร์ดผู้ติดต่อหลักโดยใช้บริบทเอาท์พุทพารามิเตอร์และเชื่อมโยงกับเรกคอร์ดเอนทิตีงานที่คุณสร้างขึ้น

Step 5 - สร้างวัตถุของ IOrganizationServiceFactory โดยใช้วัตถุ IServiceProvider

Step 6 - สร้างออบเจ็กต์ของ IOrganizationService โดยใช้อ็อบเจ็กต์ IOrganizationServiceFactory

Step 7- สุดท้ายใช้เมธอด Create ของเซอร์วิสออบเจ็กต์นี้ สร้างกิจกรรมติดตามผลซึ่งได้รับการบันทึกไว้ใน CRM

การลงนามใน Plugin Assembly

ส่วนนี้ใช้ได้เฉพาะในกรณีที่คุณลงทะเบียนแอสเซมบลีปลั๊กอินเป็นครั้งแรก คุณต้องลงชื่อเข้าใช้แอสเซมบลีด้วยคีย์เพื่อให้สามารถใช้งานปลั๊กอินได้ คลิกขวาที่โซลูชันแล้วคลิกคุณสมบัติ

เลือกแท็บการลงนามจากตัวเลือกด้านซ้ายและเลือกตัวเลือก "ลงชื่อเข้าใช้แอสเซมบลี" จากนั้นเลือกสร้างจากตัวเลือกเลือกไฟล์คีย์ชื่อที่คาดเดายาก

ป้อนชื่อไฟล์คีย์เป็น sampleplugins (อาจเป็นชื่ออื่นก็ได้ที่คุณต้องการ) ยกเลิกการเลือกตัวเลือกป้องกันไฟล์คีย์ของฉันด้วยรหัสผ่านแล้วคลิกตกลง คลิกบันทึก

สุดท้ายสร้างโซลูชัน คลิกขวา→สร้าง การสร้างโซลูชันจะสร้างแอสเซมบลี DLL ซึ่งเราจะใช้ในบทถัดไปเพื่อลงทะเบียนปลั๊กอินนี้

การจัดการข้อยกเว้นในปลั๊กอิน

บ่อยกว่านั้นตรรกะปลั๊กอินของคุณจะต้องจัดการกับข้อยกเว้นรันไทม์ สำหรับปลั๊กอินซิงโครนัสคุณสามารถส่งคืนไฟล์InvalidPluginExecutionExceptionข้อยกเว้นซึ่งจะแสดงกล่องโต้ตอบข้อผิดพลาดให้กับผู้ใช้ กล่องโต้ตอบข้อผิดพลาดจะมีข้อความแสดงข้อผิดพลาดแบบกำหนดเองที่คุณส่งผ่านไปยังวัตถุข้อความของวัตถุข้อยกเว้น

หากคุณดูรหัสของเราเรากำลังทิ้งข้อยกเว้น InvalidPluginExecutionException ในบล็อก catch ของเรา

throw new InvalidPluginExecutionException(ex.Message);

สรุป

ปลั๊กอินมีความสำคัญอย่างยิ่งต่อการใช้งาน CRM แบบกำหนดเอง ในบทนี้เรามุ่งเน้นไปที่การทำความเข้าใจกับรูปแบบกรอบเหตุการณ์ขั้นตอนไปป์ไลน์ข้อความและการเขียนปลั๊กอินตัวอย่าง ในบทถัดไปเราจะลงทะเบียนปลั๊กอินนี้ใน CRM และดูว่ามันทำงานได้ตั้งแต่ end-to-end