Microsoft Dynamics CRM - Plugin
Trình cắm thêm là một logic nghiệp vụ tùy chỉnh tích hợp với Microsoft Dynamics CRM để sửa đổi hoặc mở rộng hành vi tiêu chuẩn của nền tảng. Các trình cắm hoạt động như trình xử lý sự kiện và được đăng ký để thực thi trên một sự kiện cụ thể trong CRM. Các plugin được viết bằng C # hoặc VB và có thể chạy ở chế độ đồng bộ hoặc không đồng bộ.
Một số tình huống mà bạn sẽ viết một plugin là -
Bạn muốn thực hiện một số logic nghiệp vụ như cập nhật các trường nhất định của bản ghi hoặc cập nhật các bản ghi liên quan, v.v. khi bạn tạo hoặc cập nhật bản ghi CRM.
Bạn muốn gọi một dịch vụ web bên ngoài vào một số sự kiện nhất định như lưu hoặc cập nhật bản ghi.
Bạn muốn tính toán động các giá trị trường khi bất kỳ bản ghi nào được mở.
Bạn muốn tự động hóa các quy trình như gửi e-mail cho khách hàng của mình về các sự kiện nhất định trong CRM.
Khung sự kiện
Khung xử lý sự kiện trong CRM xử lý các yêu cầu plugin đồng bộ và không đồng bộ bằng cách chuyển nó đến đường dẫn thực thi sự kiện. Bất cứ khi nào một sự kiện kích hoạt logic plugin, một thông báo sẽ được gửi đến Dịch vụ Web của Tổ chức CRM nơi nó có thể được đọc hoặc sửa đổi bởi các plugin khác hoặc bất kỳ hoạt động cốt lõi nào của nền tảng.
Các giai đoạn đường ống của plugin
Toàn bộ đường dẫn plugin được chia thành nhiều giai đoạn mà trên đó bạn có thể đăng ký logic kinh doanh tùy chỉnh của mình. Giai đoạn đường ống được chỉ định cho biết ở giai đoạn nào của chu kỳ thực thi plugin, mã plugin của bạn chạy. Trong số tất cả các giai đoạn quy trình được chỉ định trong bảng sau, bạn chỉ có thể đăng ký các plugin tùy chỉnh của mình trên Trước và Sau sự kiện. Bạn không thể đăng ký plugin trên Hoạt động chính của nền tảng.
| Biến cố | Tên giai đoạn | Sự miêu tả |
|---|---|---|
| Trước sự kiện | Xác thực trước | Giai đoạn trong đường dẫn cho các trình cắm sẽ thực thi trước khi hệ thống chính hoạt động. Các trình cắm được đăng ký trong giai đoạn này có thể thực thi bên ngoài giao dịch cơ sở dữ liệu. |
| Trước sự kiện | Tiền hoạt động | Giai đoạn trong đường dẫn cho các trình cắm sẽ được thực thi trước khi hệ thống chính hoạt động. Các plugin đã đăng ký trong giai đoạn này được thực thi trong giao dịch cơ sở dữ liệu. |
| Hoạt động cốt lõi của nền tảng | Hoạt động chính | Intransaction, hoạt động chính của hệ thống, chẳng hạn như tạo, cập nhật, xóa, v.v. Không có trình cắm thêm tùy chỉnh nào có thể được đăng ký trong giai đoạn này. Chỉ sử dụng nội bộ. |
| Hậu sự kiện | Hậu phẫu | Giai đoạn trong đường dẫn cho các trình cắm sẽ được thực thi sau hoạt động chính. Các trình cắm được đăng ký trong giai đoạn này được thực thi trong giao dịch cơ sở dữ liệu. |
Bất cứ khi nào ứng dụng CRM gọi một sự kiện (như lưu hoặc cập nhật bản ghi), chuỗi hành động sau sẽ diễn ra:
Sự kiện kích hoạt một cuộc gọi dịch vụ Web và việc thực thi được chuyển qua các giai đoạn của đường dẫn sự kiện (trước sự kiện, hoạt động cốt lõi của nền tảng, sau sự kiện).
Thông tin được đóng gói nội bộ dưới dạng thông điệp OrganizationRequest và cuối cùng được gửi đến các phương pháp dịch vụ Web CRM nội bộ và các hoạt động cốt lõi của nền tảng.
Thông báo OrganizationRequest lần đầu tiên được nhận bởi các plugin trước sự kiện, có thể sửa đổi thông tin trước khi chuyển nó đến các hoạt động cốt lõi của nền tảng. Sau các hoạt động cốt lõi của nền tảng, thông báo được đóng gói dưới dạng OrganizationResponse và được chuyển đến các plugin sau hoạt động. Các plugin postoperations có thể tùy chọn sửa đổi thông tin này trước khi chuyển nó đến plugin async.
Các plugin nhận thông tin này dưới dạng đối tượng ngữ cảnh được chuyển cho phương thức Execute, sau đó quá trình xử lý tiếp theo sẽ xảy ra.
Sau khi tất cả quá trình xử lý plugin hoàn tất, quá trình thực thi được chuyển trở lại ứng dụng đã kích hoạt sự kiện.
Thông báo plugin
Thông báo là các sự kiện mà plugin (hoặc logic nghiệp vụ) được đăng ký. Ví dụ: bạn có thể đăng ký một plugin trên Tạo thông báo của thực thể Liên hệ. Điều này sẽ kích hoạt logic nghiệp vụ bất cứ khi nào một bản ghi Liên hệ mới được tạo.
Đối với các thực thể tùy chỉnh, sau đây là các thông báo được hỗ trợ dựa trên việc thực thể đó thuộc sở hữu của người dùng hay thuộc sở hữu của tổ chức.
| Tên tin nhắn | Loại quyền sở hữu |
|---|---|
| Chỉ định | Chỉ các pháp nhân do người dùng sở hữu |
| Tạo nên | Các pháp nhân do người dùng sở hữu và tổ chức sở hữu |
| Xóa bỏ | Các pháp nhân do người dùng sở hữu và tổ chức sở hữu |
| Cấp quyền truy cập | Chỉ các pháp nhân do người dùng sở hữu |
| ModifyAccess | Chỉ các pháp nhân do người dùng sở hữu |
| Lấy lại | Các pháp nhân do người dùng sở hữu và tổ chức sở hữu |
| Truy xuất | Các pháp nhân do người dùng sở hữu và tổ chức sở hữu |
| RetrievePrincipalAccess | Chỉ các pháp nhân do người dùng sở hữu |
| RetrieveSharedPrincipalsAndAccess | Chỉ các pháp nhân do người dùng sở hữu |
| Thu hồi truy cập | Chỉ các pháp nhân do người dùng sở hữu |
| SetState | Các pháp nhân do người dùng sở hữu và tổ chức sở hữu |
| SetStateDynamicEntity | Các pháp nhân do người dùng sở hữu và tổ chức sở hữu |
| Cập nhật | Các pháp nhân do người dùng sở hữu và tổ chức sở hữu |
Đối với các thực thể ngoài hộp mặc định, có hơn 100 thông báo được hỗ trợ. Một số thông báo này có thể áp dụng cho tất cả các thực thể trong khi một số thông báo cụ thể cho một số thực thể nhất định. Bạn có thể tìm thấy danh sách đầy đủ các thông báo được hỗ trợ trong tệp excel bên trong SDK:SDK\Message-entity support for plug-ins.xlsx
Viết plugin
Trong phần này, chúng ta sẽ tìm hiểu những điều cơ bản về cách viết một plugin. Chúng tôi sẽ tạo một plugin mẫu tạo hoạt động Nhiệm vụ để theo dõi với khách hàng bất cứ khi nào khách hàng mới được thêm vào hệ thống, tức là bất cứ khi nào Contactrecord mới được tạo trong CRM.
Trước hết, bạn cần bao gồm các tham chiếu đến Microsoft.Xrm.Sdkkhông gian tên. SDK CRM chứa tất cả các cụm SDK bắt buộc. Giả sử rằng bạn đã tải xuống và cài đặt SDK trong Chương 2, hãy mở Visual Studio. Tạo một dự án mới thuộc loại Thư viện lớp. Bạn có thể đặt tên dự án là SamplePlugins và nhấp vào OK.
Thêm tham chiếu của Microsoft.Xrm.Sdklắp ráp cho dự án của bạn. Hội có mặt ởSDK/Bin.
Bây giờ, hãy tạo một lớp có tên PostCreateContact.cs và mở rộng lớp học từ IPlugin. Cho đến bây giờ, mã của bạn sẽ giống như sau.
Bạn cũng sẽ cần thêm tham chiếu đến System.Runtime.Serialization. Khi bạn đã thêm các tham chiếu bắt buộc, hãy sao chép mã sau bên trongPostCreateContact lớp học.
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);
}
}
}
}
}Sau đây là giải thích từng bước về những gì mã này thực hiện:
Step 1- Thực hiện phương thức Execute bằng cách lấy đối tượng IServiceProvider làm tham số của nó. Nhà cung cấp dịch vụ chứa các tham chiếu đến nhiều đối tượng hữu ích mà bạn sẽ sử dụng trong plugin.
Step 2 - Lấy đối tượng IPluginExecutionContext bằng phương thức GetService của IServiceProvider.
Step 3- Lấy đối tượng của thực thể mục tiêu từ bộ sưu tập InputParameters của đối tượng ngữ cảnh. Đối tượng lớp Thực thể này đề cập đến bản ghi thực thể Liên hệ mà trên đó plugin của chúng tôi sẽ được đăng ký.
Step 4- Sau đó, nó tạo một đối tượng của thực thể Nhiệm vụ và đặt chủ đề, mô tả, ngày tháng, danh mục và liên quan đếnobjectid thích hợp. Relatedobjectid cho biết bản ghi hoạt động này đang được tạo cho bản ghi liên hệ nào. Bạn có thể thấy rằng mã lấy id của bản ghi Liên hệ mẹ bằng cách sử dụng context.OutputParameters và liên kết nó với bản ghi thực thể Tác vụ mà bạn đã tạo.
Step 5 - Tạo đối tượng của IOrganizationServiceFactory bằng cách sử dụng đối tượng IServiceProvider.
Step 6 - Tạo đối tượng của IOrganizationService bằng cách sử dụng đối tượng IOrganizationServiceFactory.
Step 7- Cuối cùng, sử dụng phương thức Create của đối tượng dịch vụ này. Nó tạo ra hoạt động tiếp theo được lưu trong CRM.
Ký hợp đồng plugin
Phần này chỉ áp dụng nếu bạn đăng ký lắp ráp plugin của mình lần đầu tiên. Bạn cần đăng nhập assembly bằng một khóa để có thể triển khai plugin. Nhấp chuột phải vào giải pháp và nhấp vào Thuộc tính.
Chọn tab Ký từ các tùy chọn bên trái và chọn tùy chọn 'Ký vào hội đồng'. Sau đó, chọn Mới từ tùy chọn Chọn tệp khóa tên mạnh.
Nhập tên tệp Khóa làm phần bổ sung mẫu (Đây có thể là bất kỳ tên nào khác mà bạn muốn). Bỏ chọn tùy chọn Bảo vệ tệp khóa của tôi bằng mật khẩu và nhấp vào OK. Nhấp vào để lưu.
Cuối cùng là xây dựng giải pháp. Nhấp chuột phải → Xây dựng. Việc xây dựng giải pháp sẽ tạo ra assembly DLL, mà chúng ta sẽ sử dụng trong chương tiếp theo để đăng ký plugin này.
Xử lý ngoại lệ trong plugin
Thông thường, logic plugin của bạn sẽ cần phải xử lý các ngoại lệ về thời gian chạy. Đối với các plugin đồng bộ, bạn có thể trả vềInvalidPluginExecutionExceptionngoại lệ, sẽ hiển thị hộp thoại lỗi cho người dùng. Hộp thoại lỗi sẽ chứa thông báo lỗi tùy chỉnh mà bạn chuyển đến đối tượng Thông báo của đối tượng ngoại lệ.
Nếu bạn nhìn vào mã của chúng tôi, chúng tôi đang ném ngoại lệ InvalidPluginExecutionException trong khối bắt của chúng tôi.
throw new InvalidPluginExecutionException(ex.Message);Phần kết luận
Các plugin chắc chắn rất quan trọng đối với bất kỳ triển khai CRM tùy chỉnh nào. Trong chương này, chúng tôi tập trung vào việc tìm hiểu mô hình khung sự kiện, các giai đoạn đường ống, thông báo và viết một plugin mẫu. Trong chương tiếp theo, chúng ta sẽ đăng ký plugin này trong CRM và xem nó hoạt động theo kịch bản đầu cuối.