Microsoft Dynamics CRM - wtyczki
Wtyczka to niestandardowa logika biznesowa, która integruje się z Microsoft Dynamics CRM w celu modyfikacji lub rozszerzenia standardowego zachowania platformy. Wtyczki działają jako programy obsługi zdarzeń i są rejestrowane do wykonania w przypadku określonego zdarzenia w CRM. Wtyczki są napisane w języku C # lub VB i mogą działać w trybie synchronicznym lub asynchronicznym.
Niektóre scenariusze, w których napisałbyś wtyczkę, to:
Chcesz wykonać jakąś logikę biznesową, taką jak aktualizowanie niektórych pól rekordu lub aktualizowanie powiązanych rekordów itp. Podczas tworzenia lub aktualizowania rekordu CRM.
Chcesz zadzwonić do zewnętrznej usługi internetowej w przypadku pewnych zdarzeń, takich jak zapisywanie lub aktualizowanie rekordu.
Chcesz dynamicznie obliczać wartości pól po otwarciu dowolnego rekordu.
Chcesz zautomatyzować procesy, takie jak wysyłanie wiadomości e-mail do klientów na temat określonych zdarzeń w CRM.
Struktura zdarzeń
Struktura przetwarzania zdarzeń w CRM przetwarza synchroniczne i asynchroniczne żądania wtyczek, przekazując je do potoku wykonywania zdarzeń. Za każdym razem, gdy zdarzenie wyzwala logikę wtyczki, wiadomość jest wysyłana do usługi sieciowej organizacji CRM, gdzie może zostać odczytana lub zmodyfikowana przez inne wtyczki lub dowolne podstawowe operacje platformy.
Etapy potoku wtyczek
Cały potok wtyczek jest podzielony na wiele etapów, na których można zarejestrować własną logikę biznesową. Określony etap potoku wskazuje, na którym etapie cyklu wykonywania wtyczki działa kod wtyczki. Spośród wszystkich określonych etapów potoku w poniższej tabeli, możesz zarejestrować własne wtyczki tylko na zdarzeniach przed i po. Nie możesz zarejestrować wtyczek w głównych operacjach platformy.
| Zdarzenie | Pseudonim artystyczny | Opis |
|---|---|---|
| Przed wydarzeniem | Wstępna walidacja | Etap w potoku dla wtyczek, które mają zostać wykonane przed głównym działaniem systemu. Wtyczki zarejestrowane na tym etapie mogą być wykonywane poza transakcją bazy danych. |
| Przed wydarzeniem | Operacja wstępna | Etap w potoku dla wtyczek, które mają zostać wykonane przed głównym działaniem systemu. Wtyczki zarejestrowane na tym etapie są wykonywane w ramach transakcji bazy danych. |
| Podstawowe działanie platformy | MainOperation | Transakcja, główna operacja systemu, taka jak tworzenie, aktualizowanie, usuwanie itd. Na tym etapie nie można zarejestrować żadnych niestandardowych wtyczek. Tylko do użytku wewnętrznego. |
| Ogłosić wydarzenie | Po operacji | Etap w potoku dla wtyczek, które mają zostać wykonane po operacji głównej. Wtyczki zarejestrowane na tym etapie są wykonywane w ramach transakcji bazy danych. |
Za każdym razem, gdy aplikacja CRM wywoła zdarzenie (takie jak zapisanie lub aktualizacja rekordu), ma miejsce następująca sekwencja działań -
Zdarzenie wyzwala wywołanie usługi sieci Web, a wykonanie przechodzi przez etapy potoku zdarzenia (przed zdarzeniem, podstawowe operacje platformy, po zdarzeniu).
Informacje są pakowane wewnętrznie w postaci wiadomości OrganizationRequest i ostatecznie wysyłane do wewnętrznych metod usługi sieciowej CRM i podstawowych operacji platformy.
Komunikat OrganizationRequest jest najpierw odbierany przez wtyczki przed zdarzeniem, które mogą modyfikować informacje przed przekazaniem ich do podstawowych operacji platformy. Po wykonaniu podstawowych operacji platformy wiadomość jest pakowana jako OrganizationResponse i przekazywana do wtyczek po operacji. Wtyczki pooperacyjne mogą opcjonalnie modyfikować te informacje przed przekazaniem ich do wtyczki asynchronicznej.
Wtyczki otrzymują te informacje w postaci obiektu kontekstu, który jest przekazywany do metody Execute, po czym następuje dalsze przetwarzanie.
Po zakończeniu przetwarzania wszystkich wtyczek wykonanie jest przekazywane z powrotem do aplikacji, która wyzwoliła zdarzenie.
Wiadomości wtyczek
Komunikaty to zdarzenia, w których rejestrowana jest wtyczka (lub logika biznesowa). Na przykład możesz zarejestrować wtyczkę na stronie Utwórz wiadomość dla podmiotu kontaktowego. Spowoduje to uruchomienie logiki biznesowej za każdym razem, gdy tworzony jest nowy rekord Kontakt.
W przypadku encji niestandardowych poniżej przedstawiono obsługiwane komunikaty w zależności od tego, czy encja należy do użytkownika, czy do organizacji.
| Nazwa wiadomości | Typ własności |
|---|---|
| Przydzielać | Tylko podmioty będące własnością użytkowników |
| Stwórz | Podmioty należące do użytkowników i organizacji |
| Usunąć | Podmioty należące do użytkowników i organizacji |
| Dostęp uznany | Tylko podmioty będące własnością użytkowników |
| ModifyAccess | Tylko podmioty będące własnością użytkowników |
| Odzyskać | Podmioty należące do użytkowników i organizacji |
| RetrieveMultiple | Podmioty należące do użytkowników i organizacji |
| RetrievePrincipalAccess | Tylko podmioty będące własnością użytkowników |
| RetrieveSharedPrincipalsAndAccess | Tylko podmioty będące własnością użytkowników |
| RevokeAccess | Tylko podmioty będące własnością użytkowników |
| SetState | Podmioty należące do użytkowników i organizacji |
| SetStateDynamicEntity | Podmioty należące do użytkowników i organizacji |
| Aktualizacja | Podmioty należące do użytkowników i organizacji |
W przypadku domyślnych encji gotowych do użycia istnieje ponad 100 obsługiwanych komunikatów. Niektóre z tych komunikatów mają zastosowanie do wszystkich podmiotów, podczas gdy inne są specyficzne dla określonych podmiotów. Pełną listę obsługiwanych wiadomości można znaleźć w pliku Excel w pakiecie SDK:SDK\Message-entity support for plug-ins.xlsx
Writing Plugin
W tej sekcji nauczymy się podstaw pisania wtyczki. Będziemy tworzyć przykładową wtyczkę, która tworzy czynność Zadania, aby kontynuować kontakt z klientem za każdym razem, gdy do systemu zostanie dodany nowy klient, tj. Za każdym razem, gdy w CRM zostanie utworzony nowy rekord kontaktu.
Przede wszystkim musisz dołączyć odniesienia do Microsoft.Xrm.Sdkprzestrzeń nazw. CRM SDK zawiera wszystkie wymagane zestawy SDK. Zakładając, że już pobrałeś i zainstalowałeś SDK w rozdziale 2, otwórz Visual Studio. Utwórz nowy projekt typu Class Library. Możesz nazwać projekt jako SamplePlugins i kliknąć OK.
Dodaj odniesienie do Microsoft.Xrm.Sdkmontaż do twojego projektu. Zespół jest obecny wSDK/Bin.
Teraz utwórz klasę o nazwie PostCreateContact.cs i rozszerz klasę z IPlugin. Do tej pory Twój kod będzie wyglądał mniej więcej tak.
Będziesz także musiał dodać odniesienie do System.Runtime.Serialization. Po dodaniu wymaganych odwołań skopiuj następujący kod w plikuPostCreateContact klasa.
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);
}
}
}
}
}Poniżej znajduje się wyjaśnienie krok po kroku, co robi ten kod -
Step 1- Implementuje metodę Execute, przyjmując obiekt IServiceProvider jako parametr. Dostawca usług zawiera odniesienia do wielu przydatnych obiektów, których będziesz używać w ramach wtyczki.
Step 2 - Uzyskuje obiekt IPluginExecutionContext przy użyciu metody GetService z IServiceProvider.
Step 3- Pobiera obiekt jednostki docelowej z kolekcji InputParameters obiektu kontekstu. Ten obiekt klasy Entity odnosi się do rekordu podmiotu Contact, w którym została zarejestrowana nasza wtyczka.
Step 4- Następnie tworzy obiekt jednostki Zadanie i ustawia odpowiedni temat, opis, daty, kategorię i dotyczący celu. Dotyczący obiektu identyfikator wskazuje, dla którego rekordu kontaktu tworzony jest ten rekord czynności. Możesz zobaczyć, że kod pobiera identyfikator nadrzędnego rekordu Contact za pomocą context.OutputParameters i kojarzy go z utworzonym rekordem jednostki zadania.
Step 5 - Tworzy obiekt IOrganizationServiceFactory przy użyciu obiektu IServiceProvider.
Step 6 - Tworzy obiekt IOrganizationService przy użyciu obiektu IOrganizationServiceFactory.
Step 7- Wreszcie przy użyciu metody Create tego obiektu usługi. Tworzy dalsze działania, które są zapisywane w CRM.
Podpisywanie zestawu wtyczek
Ta sekcja ma zastosowanie tylko wtedy, gdy rejestrujesz zespół wtyczki po raz pierwszy. Aby móc wdrożyć wtyczkę, musisz zalogować się do zestawu za pomocą klucza. Kliknij rozwiązanie prawym przyciskiem myszy i kliknij opcję Właściwości.
Wybierz kartę Podpisywanie z opcji po lewej stronie i zaznacz opcję „Podpisz zespół”. Następnie wybierz opcję Nowy z opcji Wybierz plik klucza o silnej nazwie.
Wprowadź nazwę pliku klucza jako przykładowe wtyczki (może to być dowolna inna nazwa). Usuń zaznaczenie opcji Chroń mój plik kluczy hasłem i kliknij OK. Kliknij Zapisz.
Na koniec zbuduj rozwiązanie. Kliknij prawym przyciskiem myszy → Buduj. Zbudowanie rozwiązania spowoduje wygenerowanie biblioteki DLL, której użyjemy w następnym rozdziale do rejestracji tej wtyczki.
Obsługa wyjątków we wtyczce
Najczęściej Twoja logika wtyczki będzie musiała obsługiwać wyjątki w czasie wykonywania. W przypadku wtyczek synchronicznych możesz zwrócić plikInvalidPluginExecutionExceptionwyjątek, który spowoduje wyświetlenie okna dialogowego błędu dla użytkownika. Okno dialogowe błędu będzie zawierało niestandardowy komunikat o błędzie, który zostanie przekazany do obiektu Message obiektu wyjątku.
Jeśli spojrzysz na nasz kod, w naszym bloku catch rzucamy wyjątek InvalidPluginExecutionException.
throw new InvalidPluginExecutionException(ex.Message);Wniosek
Wtyczki są zdecydowanie kluczowe dla każdej niestandardowej implementacji CRM. W tym rozdziale skupiliśmy się na zrozumieniu modelu struktury zdarzeń, etapach potoku, komunikatach i napisaniu przykładowej wtyczki. W następnym rozdziale zarejestrujemy tę wtyczkę w CRM i zobaczymy, jak działa od końca do końca.