Cómo crear un sencillo plug-in
A aquellos que sienten vértigo en cuanto se enfrentan a una línea de código este post les va a encantar.
Como sabéis, un plug-in es una pequeña extensión (en la versión anterior los llamábamos 'Callouts') que nosotros mismos podemos crear e incluir en nuestro Crm para ampliar su funcionalidad.
En concreto, este ejemplo hará que nuestro Crm escriba automáticamente en un fichero de texto cada vez que un contacto es creado en el sistema. Nótese que el ejemplo puede ser modificado para escribir cualquier tipo de cosa cuando cualquier otro tipo de registro es creado.
Nota: Voy a intentar que los pasos sean lo más sencillos posibles, aunque en los pasos más triviales no me entretendré demasiado.
Empezamos:
1-Abrimos Visual Studio 2005 y vamos a Archivo - Nuevo - Proyecto - Librería de clases (en la sección de C#).
2-Por otra parte, hemos de ir a la carpeta ..\gac que se encuentra en el cd de instalación de Crm 4.0.
Acordaos de que también es posible descargar el CD de instalación desde microsoft.com/download de manera gratuita.
Una vez en la carpeta buscamos los archivos 'microsoft.crm.sdk.dll' y 'microsoft.crm.sdktypeproxy.dll' y los copiamos a cualquier otra carpeta (por ejemplo, al escritorio, o a nuestra carpeta de proyectos de visual studio).
3-Volvemos a Visual Studio y hacemos click en el menu Proyecto - Añadir referencia.
Se nos presentará un dialogo en el que haremos click en la pestaña Buscar, y una vez ahí buscaremos los dos archivos que copiamos al escritorio en el paso 2.
Cuando los tengais seleccionados (podeis coger los dos a la vez) aceptais y vereis que las referencias han sido añadidas al panel que hay a la derecha de la pantalla en la sección de referencias.
4-Si os fijais en la parte de arriba del código habrá varias líneas del tipo 'using System;', etc.
Justo debajo de esas lineas vamos a escribir estas otras líneas (nótese que el código distingue entre mayúsculas y minúsculas, por tando prestad especial atención):
using Microsoft.Crm.Sdk;
using Microsoft.Crm.SdkTypeProxy;
using System.IO;
5-Ahora hemos de firmar digitalmente el plugin, o de lo contrario Crm no lo aceptará. Para ello vamos al menu Proyecto, y abajo del todo habrá una opción que se llamará Propiedades de 'bla bla'.
Una vez dentro del menú de propiedades, hacemos click en la pestaña 'Firmado' (Signing en la versión inglesa que tengo yo instalada) y haemos click en 'Firmar el ensamblado', lo cual habilitará la lista desplegable que tiene justo debajo.
Hacemos click en dicha lista y seleccionamos la opción 'Nuevo'. En la ventanita que aparece escribimos 'mi_clave' y desmarcamos la casilla que dice 'Proteger con password'.
6-Ya estamos listos para empezar a escribir código!
Lo primero es reemplazar esto:
namespace nombre_proyecto
{
public class Class1
{
}
}
por esto otro:
namespace ContactCreatePlugin
{
public class ContactCreatePlugin : IPlugin
{
public void Execute(IPluginExecutionContext context)
{
}
}
}
Notese que TODO plug-in va a tener estas mismas líneas. El plug-in ejecutará todas aquellas líneas que escribamos dentro del método Execute.
7-El código que pego a continuación es específico del ejemplo que estamos construyendo.
En concreto, esta función es una función de .net genérica para escribir en un fichero. Copiaremos este código justo antes del método Execute:
IMPORTANTE: Esta ruta es válida en un Windows 2003 en Inglés. Si vuestro idioma es otro, es posible que esta ruta no exista y debáis modificarla.
private void WriteToFile(string message)
{
using (StreamWriter sw = File.AppendText("C:\\Program Files\\Microsoft Dynamics CRM\\Server\\bin\\assembly\\plugin_output.txt"))
{
sw.WriteLine(message);
}
}
8-Dentro del método Execute no tenemos más que llamar a la función WriteToFile, así:
WriteToFile(“Hola Mundo”);
9-Ya podemos compilar nuestro código.
Vuestra pantalla de Visual Studio se debería parecer a esto si todo ha ido bien:
Para compilarlo, simplemente pulsamos en el menú Build - Build proyect.
10-Nuestro plug-in ya está compilado y podemos ir a buscarlo a la carpeta donde hayamos especificado que se guarde el proyecto. En mi caso es D:\VS\blog1\blog1\bin\Debug.
Podéis hacer una copia del archivo .dll que hay en esa carpeta y pegarlo en otra carpeta donde guardéis vuestros plug-ins. Si este es el primero, es un buen momento para crear dicha carpeta :)
11-El siguiente paso consiste en registrar nuestro plug-in en nuestro servidor de Crm. Para ello usaremos una herramienta que ha creado nuestro grupo de producto llamada 'Plugin Registration Tool'. El código fuente de dicha herramienta se puede descargar de manera gratuita desde msdn.
No obstante, para vuestra comodidad he incluido aquí una versión precompilada de dicha herramienta. Simplemente hemos de extraer el contenido de este fichero adjunto en cualquier carpeta auxiliar y posteriormente ejecutaremos el fichero contenido dentro.
Se nos presentará una pantalla similar a esta donde deberemos indicar el nombre de nuestro servidor, usuario, etc:
12-Tras darle a connect e introducir el password que nos pide se nos presentará la ventana principal de la aplicación, donde pulsaremos en 'Register - Register new assembly' para registrar la DLL que generamos en el paso 9.
Aparecerá entonces la siguiente ventana:
Pulsamos en el botón que muestra 3 puntos suspensivos y buscamos el mencionado archivo. Después pulsamos en 'Register selected Plugins'.
13.En el panel de plugins registrados aparecerá una nueva entrada con el nombre de nuestro archivo. Hacemos click con el botón derecho sobre él, y seleccionamos 'Register new step'. Con este paso especificaremos los eventos en los que se lanzará el plugin.
En concreto, en el campo Message escribimos 'create' y en el campo Primary Entity escribimos 'contact'. El resultado será este:
Hacemos click en 'Register new step' y listo. Nuestro plug-in ya está en funcionamiento.
14. Para asegurarnos de que todo funciona perfectamente, iremos a Crm y crearemos un nuevo contacto. Esto provocará que un nuevo fichero de texto aparezca en la carpeta C:\Program Files\Microsoft Dynamics CRM\Server\bin\assembly\
Es posible que la ejecución del plugin nos de un error, lo que es probable que esté debido a permisos de escritura en dicha carpeta
Para verificarlo podéis abrir un explorador de archivos, buscar la carpeta assembly, hacer click derecho sobre dicha carpeta y pinchar la pestaña seguridad, la cual debería mostrar que la cuenta 'Network Service' tiene permisos de escritura (Write) sobre la carpeta, como muestra esta captura:
Esto es todo. Espero que este post os sirva de ayuda a la hora de empezar a trabajar con plug-ins. Ya veréis como una vez se han hecho 2 o 3 todos empiezan a parecer igual de fáciles.
Para más información sobre plugins y SDK en general, podéis encontrar la documentación oficial aquí.