Microsoft Dynamics CRM - Plugin
Plug-in adalah logika bisnis kustom yang terintegrasi dengan Microsoft Dynamics CRM untuk mengubah atau memperluas perilaku standar platform. Plug-in bertindak sebagai penangan peristiwa dan terdaftar untuk dijalankan pada peristiwa tertentu di CRM. Plugin ditulis dalam C # atau VB dan dapat berjalan baik dalam mode sinkron maupun asinkron.
Beberapa skenario di mana Anda akan menulis plugin adalah -
Anda ingin menjalankan beberapa logika bisnis seperti memperbarui bidang tertentu dari catatan atau memperbarui catatan terkait, dll. Saat Anda membuat atau memperbarui catatan CRM.
Anda ingin memanggil layanan web eksternal pada acara tertentu seperti menyimpan atau memperbarui rekaman.
Anda ingin menghitung nilai bidang secara dinamis saat rekaman apa pun dibuka.
Anda ingin mengotomatiskan proses seperti mengirim email ke pelanggan Anda pada acara tertentu di CRM.
Kerangka Acara
Kerangka Pemrosesan Peristiwa di CRM memproses permintaan plugin sinkron dan asinkron dengan meneruskannya ke pipeline eksekusi peristiwa. Setiap kali suatu peristiwa memicu logika plugin, sebuah pesan dikirim ke Layanan Web Organisasi CRM di mana ia dapat dibaca atau dimodifikasi oleh plugin lain atau operasi inti platform apa pun.
Tahapan Plugin Pipeline
Seluruh pipeline plugin dibagi dalam beberapa tahap tempat Anda dapat mendaftarkan logika bisnis kustom Anda. Tahap pipeline yang ditentukan menunjukkan pada tahap mana dari siklus eksekusi plugin, kode plugin Anda berjalan. Dari semua tahapan pipeline yang ditentukan dalam tabel berikut, Anda dapat mendaftarkan plugin kustom Anda hanya pada Pre- dan Post-event. Anda tidak dapat mendaftarkan plugin di Operasi Utama Inti Platform.
| Peristiwa | Nama panggung | Deskripsi |
|---|---|---|
| Pra-Acara | Pra-validasi | Tahapan dalam pipeline untuk plug-in yang akan dijalankan sebelum operasi sistem utama. Plug-in yang didaftarkan pada tahap ini dapat dijalankan di luar transaksi database. |
| Pra-Acara | Pra-operasi | Tahapan dalam pipeline untuk plug-in yang akan dijalankan sebelum operasi sistem utama. Plugin yang didaftarkan pada tahap ini dijalankan dalam transaksi database. |
| Operasi Inti Platform | MainOperation | Intransaction, operasi utama sistem, seperti membuat, memperbarui, menghapus, dan sebagainya. Tidak ada plugin kustom yang dapat didaftarkan pada tahap ini. Hanya untuk penggunaan internal. |
| Pasca-Acara | Pasca operasi | Tahapan dalam pipeline untuk plug-in yang akan dijalankan setelah operasi utama. Plug-in yang didaftarkan pada tahap ini dijalankan dalam transaksi database. |
Setiap kali aplikasi CRM memanggil suatu peristiwa (seperti menyimpan atau memperbarui catatan), urutan tindakan berikut terjadi -
Peristiwa memicu panggilan layanan Web dan eksekusi diteruskan melalui tahapan pipeline peristiwa (pra-peristiwa, operasi inti platform, pasca-peristiwa).
Informasi ini dikemas secara internal sebagai pesan OrganizationRequest dan akhirnya dikirim ke metode layanan Web CRM internal dan operasi inti platform.
Pesan OrganizationRequest pertama kali diterima oleh plugin pra-acara, yang dapat mengubah informasi sebelum meneruskannya ke operasi inti platform. Setelah operasi inti platform, pesan tersebut dikemas sebagai OrganizationResponse dan diteruskan ke plugin pasca operasi. Plugin pasca operasi dapat secara opsional mengubah informasi ini sebelum meneruskannya ke plugin async.
Plugin menerima informasi ini dalam bentuk objek konteks yang diteruskan ke metode Execute setelah pemrosesan lebih lanjut terjadi.
Setelah semua pemrosesan plugin selesai, eksekusi diteruskan kembali ke aplikasi yang memicu peristiwa tersebut.
Pesan Plugin
Pesan adalah peristiwa di mana plugin (atau logika bisnis) terdaftar. Misalnya, Anda dapat mendaftarkan plugin di Buat entitas Pesan Kontak. Ini akan mengaktifkan logika bisnis setiap kali catatan Kontak baru dibuat.
Untuk entitas kustom, berikut adalah pesan yang didukung berdasarkan apakah entitas tersebut milik pengguna atau milik organisasi.
| Nama Pesan | Jenis Kepemilikan |
|---|---|
| Menetapkan | Hanya entitas milik pengguna |
| Membuat | Entitas milik pengguna dan milik organisasi |
| Menghapus | Entitas milik pengguna dan milik organisasi |
| GrantAccess | Hanya entitas milik pengguna |
| ModifyAccess | Hanya entitas milik pengguna |
| Ambil | Entitas milik pengguna dan milik organisasi |
| RetrieveMultiple | Entitas milik pengguna dan milik organisasi |
| RetrievePrincipalAccess | Hanya entitas milik pengguna |
| RetrieveSharedPrincipalsAndAccess | Hanya entitas milik pengguna |
| Mencabut akses | Hanya entitas milik pengguna |
| SetState | Entitas milik pengguna dan milik organisasi |
| SetStateDynamicEntity | Entitas milik pengguna dan milik organisasi |
| Memperbarui | Entitas milik pengguna dan milik organisasi |
Untuk entitas out-of-the-box default, ada lebih dari 100 pesan yang didukung. Beberapa dari pesan ini berlaku untuk semua entitas sementara beberapa di antaranya khusus untuk entitas tertentu. Anda dapat menemukan daftar lengkap pesan yang didukung dalam file excel di dalam SDK:SDK\Message-entity support for plug-ins.xlsx
Plugin Menulis
Pada bagian ini, kita akan mempelajari dasar-dasar penulisan plugin. Kami akan membuat plugin sampel yang membuat aktivitas Tugas untuk ditindaklanjuti dengan pelanggan setiap kali pelanggan baru ditambahkan ke sistem, yaitu setiap kali Catatan Kontak baru dibuat di CRM.
Pertama-tama, Anda perlu menyertakan referensi ke Microsoft.Xrm.Sdknamespace. CRM SDK berisi semua rakitan SDK yang diperlukan. Dengan asumsi Anda telah mengunduh dan menginstal SDK di Bab 2, buka Visual Studio. Buat proyek baru berjenis Class Library. Anda dapat menamai proyek sebagai SamplePlugins dan klik OK.
Tambahkan referensi dari Microsoft.Xrm.Sdkperakitan untuk proyek Anda. Majelis hadir diSDK/Bin.
Sekarang, buat kelas bernama PostCreateContact.cs dan tingkatkan kelas dari IPlugin. Sampai saat ini, kode Anda akan terlihat seperti berikut ini.
Anda juga perlu menambahkan referensi ke System.Runtime.Serialization. Setelah Anda menambahkan referensi yang diperlukan, salin kode berikut di dalamPostCreateContact kelas.
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);
}
}
}
}
}Berikut adalah penjelasan langkah demi langkah tentang fungsi kode ini -
Step 1- Menerapkan metode Execute dengan mengambil objek IServiceProvider sebagai parameternya. Penyedia layanan berisi referensi ke banyak objek berguna yang akan Anda gunakan dalam plugin.
Step 2 - Mendapatkan objek IPluginExecutionContext menggunakan metode GetService dari IServiceProvider.
Step 3- Mendapat objek entitas target dari koleksi InputParameters objek konteks. Objek kelas Entitas ini merujuk ke catatan entitas Kontak tempat plugin kami akan didaftarkan.
Step 4- Kemudian membuat objek entitas Tugas dan menetapkan subjek, deskripsi, tanggal, kategori, dan terkait objek yang tepat. Mengenaiobjekid mengindikasikan untuk rekaman kontak mana rekaman aktivitas ini sedang dibuat. Anda dapat melihat bahwa kode mendapatkan id dari catatan kontak induk menggunakan konteks.OutputParameters dan mengaitkannya dengan catatan entitas tugas yang telah Anda buat.
Step 5 - Membuat objek IOrganizationServiceFactory menggunakan objek IServiceProvider.
Step 6 - Membuat objek IOrganizationService menggunakan objek IOrganizationServiceFactory.
Step 7- Terakhir, menggunakan metode Buat objek layanan ini. Ini menciptakan aktivitas tindak lanjut yang disimpan di CRM.
Menandatangani Majelis Plugin
Bagian ini hanya berlaku jika Anda mendaftarkan rakitan plugin Anda untuk pertama kalinya. Anda harus masuk ke assembly dengan kunci untuk dapat menerapkan plugin. Klik kanan solusi dan klik Properties.
Pilih tab Signing dari opsi kiri dan centang opsi 'Sign the assembly'. Kemudian, pilih Baru dari Pilih opsi file kunci nama yang kuat.
Masukkan nama file Key sebagai sampleplugins (Ini bisa berupa nama lain yang Anda inginkan). Hapus centang pada opsi Lindungi file kunci saya dengan kata sandi dan klik OK. Klik Simpan.
Terakhir, buat solusinya. Klik Kanan → Bangun. Membangun solusi akan menghasilkan DLL perakitan, yang akan kita gunakan di bab berikutnya untuk mendaftarkan plugin ini.
Penanganan Pengecualian di Plugin
Lebih sering daripada tidak, logika plugin Anda perlu menangani pengecualian waktu proses. Untuk plugin sinkron, Anda dapat mengembalikan fileInvalidPluginExecutionExceptionpengecualian, yang akan menampilkan kotak dialog kesalahan kepada pengguna. Dialog kesalahan akan berisi pesan kesalahan khusus yang Anda berikan ke objek Pesan dari objek pengecualian.
Jika Anda melihat kode kami, kami melemparkan pengecualian InvalidPluginExecutionException di blok catch kami.
throw new InvalidPluginExecutionException(ex.Message);Kesimpulan
Plugin sangat penting untuk implementasi CRM khusus apa pun. Dalam bab ini, kami fokus pada pemahaman model kerangka peristiwa, tahapan pipeline, pesan, dan penulisan plugin sampel. Di bab berikutnya, kami akan mendaftarkan plugin ini di CRM dan melihatnya berfungsi dari skenario ujung ke ujung.