Microsoft Dynamics CRM - Plugin
Un plug-in è una logica aziendale personalizzata che si integra con Microsoft Dynamics CRM per modificare o estendere il comportamento standard della piattaforma. I plug-in agiscono come gestori di eventi e vengono registrati per essere eseguiti su un particolare evento in CRM. I plug-in sono scritti in C # o VB e possono essere eseguiti in modalità sincrona o asincrona.
Alcuni scenari in cui scriveresti un plugin sono:
Si desidera eseguire una logica aziendale come l'aggiornamento di determinati campi di un record o l'aggiornamento dei record correlati, ecc. Quando si crea o si aggiorna un record CRM.
Si desidera chiamare un servizio Web esterno su determinati eventi come il salvataggio o l'aggiornamento di un record.
Si desidera calcolare dinamicamente i valori dei campi quando viene aperto un record.
Desideri automatizzare processi come l'invio di e-mail ai tuoi clienti su determinati eventi in CRM.
Framework degli eventi
Event Processing Framework in CRM elabora le richieste di plug-in sincrone e asincrone passandole alla pipeline di esecuzione degli eventi. Ogni volta che un evento attiva la logica di un plug-in, viene inviato un messaggio al servizio Web dell'organizzazione CRM dove può essere letto o modificato da altri plug-in o da qualsiasi operazione principale della piattaforma.
Fasi della pipeline del plugin
L'intera pipeline dei plug-in è suddivisa in più fasi in cui è possibile registrare la logica aziendale personalizzata. La fase della pipeline specificata indica in quale fase del ciclo di esecuzione del plug-in viene eseguito il codice del plug-in. Tra tutte le fasi della pipeline specificate nella tabella seguente, è possibile registrare i plug-in personalizzati solo su eventi pre e post. Non è possibile registrare plug-in su Platform Core Main Operations.
| Evento | Nome d'arte | Descrizione |
|---|---|---|
| Pre-Evento | Pre-convalida | Fase nella pipeline per i plug-in che devono essere eseguiti prima dell'operazione di sistema principale. I plug-in registrati in questa fase possono essere eseguiti al di fuori della transazione del database. |
| Pre-Evento | Preoperativo | Fase nella pipeline per i plug-in che devono essere eseguiti prima del funzionamento del sistema principale. I plugin registrati in questa fase vengono eseguiti all'interno della transazione del database. |
| Operazione principale della piattaforma | MainOperation | Intransazione, l'operazione principale del sistema, come creare, aggiornare, eliminare e così via. Nessun plug-in personalizzato può essere registrato in questa fase. Solo per uso interno. |
| Post-evento | Post-operazione | Fase nella pipeline per i plug-in che devono essere eseguiti dopo l'operazione principale. I plug-in registrati in questa fase vengono eseguiti all'interno della transazione del database. |
Ogni volta che l'applicazione CRM richiama un evento (come il salvataggio o l'aggiornamento di un record), viene eseguita la seguente sequenza di azioni:
L'evento attiva una chiamata al servizio Web e l'esecuzione viene passata attraverso le fasi della pipeline dell'evento (pre-evento, operazioni principali della piattaforma, post-evento).
Le informazioni vengono impacchettate internamente come messaggio OrganizationRequest e infine inviate ai metodi del servizio Web CRM interno e alle operazioni principali della piattaforma.
Il messaggio OrganizationRequest viene prima ricevuto dai plug-in pre-evento, che possono modificare le informazioni prima di passarle alle operazioni principali della piattaforma. Dopo le operazioni principali della piattaforma, il messaggio viene impacchettato come OrganizationResponse e passato ai plug-in post-operazione. I plug-in post-operatorio possono facoltativamente modificare queste informazioni prima di passarle al plug-in asincrono.
I plugin ricevono queste informazioni sotto forma di oggetto di contesto che viene passato al metodo Execute, dopodiché avviene l'ulteriore elaborazione.
Al termine dell'elaborazione del plug-in, l'esecuzione viene ritrasmessa all'applicazione che ha attivato l'evento.
Messaggi del plugin
I messaggi sono gli eventi su cui è registrato il plugin (o la logica aziendale). Ad esempio, puoi registrare un plug-in sull'entità Crea messaggio di contatto. Ciò attiverà la logica aziendale ogni volta che viene creato un nuovo record di contatto.
Per le entità personalizzate, di seguito sono riportati i messaggi supportati in base al fatto che l'entità sia di proprietà dell'utente o dell'organizzazione.
| Nome messaggio | Tipo di proprietà |
|---|---|
| Assegnare | Solo entità di proprietà dell'utente |
| Creare | Entità di proprietà dell'utente e di proprietà dell'organizzazione |
| Elimina | Entità di proprietà dell'utente e di proprietà dell'organizzazione |
| Concedere l'accesso | Solo entità di proprietà dell'utente |
| ModifyAccess | Solo entità di proprietà dell'utente |
| Recuperare | Entità di proprietà dell'utente e di proprietà dell'organizzazione |
| RetrieveMultiple | Entità di proprietà dell'utente e di proprietà dell'organizzazione |
| RetrievePrincipalAccess | Solo entità di proprietà dell'utente |
| RetrieveSharedPrincipalsAndAccess | Solo entità di proprietà dell'utente |
| Revocare l'accesso | Solo entità di proprietà dell'utente |
| SetState | Entità di proprietà dell'utente e di proprietà dell'organizzazione |
| SetStateDynamicEntity | Entità di proprietà dell'utente e di proprietà dell'organizzazione |
| Aggiornare | Entità di proprietà dell'utente e di proprietà dell'organizzazione |
Per le entità predefinite predefinite, ci sono più di 100 messaggi supportati. Alcuni di questi messaggi sono applicabili a tutte le entità mentre alcuni di essi sono specifici per determinate entità. Puoi trovare l'elenco completo dei messaggi supportati in un file excel all'interno dell'SDK:SDK\Message-entity support for plug-ins.xlsx
Plugin di scrittura
In questa sezione impareremo le basi per scrivere un plugin. Creeremo un plug-in di esempio che crea un'attività Task da seguire con il cliente ogni volta che un nuovo cliente viene aggiunto al sistema, ovvero ogni volta che viene creato un nuovo Contactrecord in CRM.
Prima di tutto, dovresti includere i riferimenti a Microsoft.Xrm.Sdkspazio dei nomi. L'SDK CRM contiene tutti gli assembly SDK richiesti. Supponendo che tu abbia già scaricato e installato l'SDK nel Capitolo 2, apri Visual Studio. Crea un nuovo progetto di tipo Libreria di classi. È possibile denominare il progetto come SamplePlugins e fare clic su OK.
Aggiungi il riferimento di Microsoft.Xrm.Sdkassemblaggio al tuo progetto. L'assemblea è presente inSDK/Bin.
Ora crea una classe denominata PostCreateContact.cs ed estendi la classe da IPlugin. Fino ad ora, il tuo codice sarà simile al seguente.
Sarà inoltre necessario aggiungere un riferimento a System.Runtime.Serialization. Dopo aver aggiunto i riferimenti richiesti, copia il codice seguente all'interno del filePostCreateContact classe.
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);
}
}
}
}
}Di seguito è riportata una spiegazione dettagliata di ciò che fa questo codice:
Step 1- Implementa il metodo Execute prendendo l'oggetto IServiceProvider come parametro. Il fornitore di servizi contiene riferimenti a molti oggetti utili che utilizzerai all'interno del plugin.
Step 2 - Ottiene l'oggetto IPluginExecutionContext utilizzando il metodo GetService di IServiceProvider.
Step 3- Ottiene l'oggetto dell'entità di destinazione dalla raccolta InputParameters dell'oggetto contesto. Questo oggetto della classe Entity fa riferimento al record dell'entità Contact su cui verrebbe registrato il nostro plugin.
Step 4- Crea quindi un oggetto di entità Task e imposta oggetto, descrizione, date, categoria eidoggetto pertinenti. L'idoggetto relativo indica per quale record di contatto viene creato questo record di attività. Puoi vedere che il codice ottiene l'ID del record del contatto principale utilizzando context.OutputParameters e lo associa al record dell'entità Task che hai creato.
Step 5 - Crea l'oggetto di IOrganizationServiceFactory utilizzando l'oggetto IServiceProvider.
Step 6 - Crea l'oggetto di IOrganizationService utilizzando l'oggetto IOrganizationServiceFactory.
Step 7- Infine, utilizzando il metodo Create di questo oggetto di servizio. Crea l'attività di follow-up che viene salvata in CRM.
Firma dell'assembly del plugin
Questa sezione è applicabile solo se stai registrando l'assembly del tuo plugin per la prima volta. È necessario accedere all'assembly con una chiave per poter distribuire il plug-in. Fare clic con il pulsante destro del mouse sulla soluzione e fare clic su Proprietà.
Seleziona la scheda Firma dalle opzioni a sinistra e seleziona l'opzione "Firma l'assieme". Quindi, seleziona Nuovo dall'opzione Scegli un file chiave con nome sicuro.
Immettere il nome del file chiave come sampleplugins (può essere qualsiasi altro nome desiderato). Deseleziona l'opzione Proteggi il mio file chiave con una password e fai clic su OK. Fare clic su Salva.
Infine, crea la soluzione. Fare clic con il pulsante destro del mouse → Crea. La creazione della soluzione genererà la DLL dell'assembly, che useremo nel prossimo capitolo per registrare questo plugin.
Gestione delle eccezioni nel plugin
Il più delle volte, la logica del tuo plug-in dovrà gestire le eccezioni in fase di esecuzione. Per i plugin sincroni, puoi restituire un fileInvalidPluginExecutionExceptioneccezione, che mostrerà una finestra di dialogo di errore all'utente. La finestra di dialogo di errore conterrà il messaggio di errore personalizzato passato all'oggetto Message dell'oggetto eccezione.
Se guardi il nostro codice, stiamo lanciando l'eccezione InvalidPluginExecutionException nel nostro blocco catch.
throw new InvalidPluginExecutionException(ex.Message);Conclusione
I plugin sono decisamente cruciali per qualsiasi implementazione CRM personalizzata. In questo capitolo ci siamo concentrati sulla comprensione del modello del framework degli eventi, sulle fasi della pipeline, sui messaggi e sulla scrittura di un plug-in di esempio. Nel prossimo capitolo, registreremo questo plugin in CRM e lo vedremo funzionare da uno scenario end-to-end.