Phần bổ trợ là 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. Phần bổ trợ đóng vai trò là 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 plugin là –
- Bạn muốn thực thi một số logic nghiệp vụ chẳng hạn 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 trong một số sự kiện nhất định, chẳng hạn 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 quy trình thực thi sự kiện. Bất cứ khi nào một sự kiện kích hoạt logic phần bổ trợ, thì một thông báo sẽ được gửi đến Dịch vụ web của Tổ chức CRM nơi phần bổ trợ khác hoặc bất kỳ hoạt động cốt lõi nào của nền tảng có thể đọc hoặc sửa đổi.
Giai đoạn quy trình bổ trợ
Toàn bộ đường dẫn plugin được chia thành nhiều giai đoạn mà bạn có thể đăng ký logic nghiệp vụ tùy chỉnh của mình. Giai đoạn đường ống được chỉ định cho biết mã plugin của bạn sẽ chạy ở giai đoạn nào của chu kỳ thực thi plugin. 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ý phần bổ trợ tùy chỉnh của mình trên Sự kiệ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 lõi nền tảng.
| Sự kiện | Tên giai đoạn | Sự miêu tả |
| Trước sự kiện | xác nhận trước | Giai đoạn trong quy trình dành cho các phần bổ trợ sẽ thực thi trước khi vận hành hệ thống chính. Các plug-in đã đă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 | trước khi vận hành | Giai đoạn trong quy trình dành cho các phần bổ trợ sẽ được thực thi trước khi vận hành hệ thống chính. 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 | Giao dịch, 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ó plug-in tùy chỉnh nào có thể được đăng ký trong giai đoạn này. Chỉ sử dụng nội bộ. |
| Sau sự kiện | hậu phẫu | Giai đoạn trong quy trình cho các phần bổ trợ sẽ được thực thi sau hoạt động chính. Các plug-in đã đă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 đây sẽ diễn ra –
- Sự kiện kích hoạt một cuộc gọi dịch vụ Web và quá trình thực thi được chuyển qua các giai đoạn quy trình 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 báo OrganizationRequest và cuối cùng được gửi đến các phương thức 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 phần bổ trợ trước sự kiện, phần bổ trợ này 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 phần bổ trợ sau hoạt động. Các phần bổ trợ hậu hoạt động có thể tùy chọn sửa đổi thông tin này trước khi chuyển nó đến phần bổ trợ không đồng bộ.
- Các plugin nhận thông tin này ở dạng đối tượng ngữ cảnh được chuyển đến phương thức Execute, sau đó quá trình xử lý tiếp theo sẽ diễn ra.
- Sau khi tất cả quá trình xử lý plugin hoàn tất, quá trình thực thi sẽ được chuyển trở lại ứng dụng đã kích hoạt sự kiện.
Tin nhắn 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ý plugin trên thực thể Tạo thông báo của người 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 Người 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 tổ chức.
| Tên tin nhắn | Loại quyền sở hữu |
| Giao phó | Chỉ các thực thể do người dùng sở hữu |
| Tạo nên | Thực thể do người dùng sở hữu và tổ chức sở hữu |
| Xóa bỏ | Thực thể do người dùng sở hữu và tổ chức sở hữu |
| Cấp phép truy cập | Chỉ các thực thể do người dùng sở hữu |
| Sửa đổi quyền truy cập | Chỉ các thực thể do người dùng sở hữu |
| Lấy lại | Thực thể do người dùng sở hữu và tổ chức sở hữu |
| Lấy Nhiều | Thực thể do người dùng sở hữu và tổ chức sở hữu |
| Lấy Hiệu TrưởngTruy Cập | Chỉ các thực thể do người dùng sở hữu |
| Truy xuất SharedPrincipalsAndAccess | Chỉ các thực thể do người dùng sở hữu |
| Thu hồi truy cập | Chỉ các thực thể do người dùng sở hữu |
| SetState | Thực thể do người dùng sở hữu và tổ chức sở hữu |
| SetStateDynamicEntity | Thực thể do người dùng sở hữu và tổ chức sở hữu |
| Cập nhật | Thực thể do người dùng sở hữu và tổ chức sở hữu |
Đối với các thực thể sẵn dùng 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ố trong số chúng dành riêng cho một số thực thể nhất định. Bạn có thể tìm thấy danh sách đầy đủ thông báo được hỗ trợ trong tệp excel bên trong SDK: SDK\Hỗ trợ thực thể thông báo cho trình cắm.xlsx
Plugin viết
Trong phần này, chúng ta sẽ tìm hiểu những kiến thức cơ bản về cách viết plugin. Chúng tôi sẽ tạo một plugin mẫu tạo hoạt động Tác vụ để theo dõi khách hàng bất cứ khi nào có khách hàng mới được thêm vào hệ thống, tức là bất cứ khi nào một Bản ghi liên hệ mới được tạo trong CRM.
Trước hết, bạn cần bao gồm các tham chiếu đến không gian tên Microsoft.Xrm.Sdk . CRM SDK chứa tất cả các tập hợp SDK cần thiết. 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 kiểu Thư viện lớp. Bạn có thể đặt tên dự án là SamplePlugins và nhấn OK.
Thêm tham chiếu của Microsoft.Xrm.Sdk vào dự án của bạn. Việc lắp ráp có trong SDK/Bin .
Bây giờ, tạo một lớp có tên PostCreateContact.cs và mở rộng lớp 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 vào lớp 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);
}
}
}
}
}
Sau đây là giải thích từng bước về chức năng của đoạn mã này –
Bước 1 – Triển khai 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.
Bước 2 – Lấy đối tượng IPluginExecutionContext bằng phương thức GetService của IServiceProvider.
Bước 3 – Lấy đối tượng của thực thể đích 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ể Người liên hệ mà phần bổ trợ của chúng ta sẽ được đăng ký trên đó.
Bước 4 – Sau đó, nó tạo một đối tượng của thực thể Tác vụ và đặt chủ đề, mô tả, ngày tháng, danh mục và đối tượng liên quan phù hợp. Đối tượng liên quan cho biết bản ghi hoạt động này đang được tạo cho bản ghi người liên hệ nào. Bạn có thể thấy rằng mã lấy id của bản ghi Người liên hệ gốc bằng cách sử dụng context.OutputParameters và liên kết nó với bản ghi thực thể Nhiệm vụ mà bạn đã tạo.
Bước 5 – Tạo đối tượng của IOrganizationServiceFactory bằng cách sử dụng đối tượng IServiceProvider.
Bước 6 – Tạo đối tượng của IOrganizationService bằng cách sử dụng đối tượng IOrganizationServiceFactory.
Bước 7 – Cuối cùng, sử dụng phương thức Tạo của đối tượng dịch vụ này. Nó tạo 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ý cụm plugin của mình lần đầu tiên. Bạn cần đăng nhập vào hội đồng 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ý bản lắp ráp’. 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 Key là sampleplugins (Đâ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, xây dựng giải pháp. Nhấp chuột phải → Xây dựng. Xây dựng giải pháp sẽ tạo DLL lắp ráp, mà chúng tôi 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 xử lý các ngoại lệ trong thời gian chạy. Đối với các plugin đồng bộ, bạn có thể trả về một ngoại lệ UnlimitedPluginExecutionException , ngoại lệ này sẽ hiển thị hộp thoại báo 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 xem mã của chúng tôi, chúng tôi sẽ ném ngoại lệ InvalidPluginExecutionException vào khối bắt của chúng tôi.
throw new InvalidPluginExecutionException(ex.Message);
Phần kết luận
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 quy trình, thông báo và viết plugin mẫu. Trong chương tiếp theo, chúng tôi sẽ đăng ký plugin này trong CRM và xem nó hoạt động từ đầu đến cuối theo kịch bản nào