Extensibilidad de Dataverse
En este tema vamos a explorar los puntos de extensibilidad de Dataverse a disposición de los desarrolladores. La arquitectura de Dataverse implementa una arquitectura basada en mensajes para el procesamiento de solicitudes. Cada mensaje de solicitud se procesa a través de una canalización de eventos que tiene puntos de extensión para ejecutar una lógica empresarial personalizada implementada mediante complementos. Hay muchos mensajes que se proporcionan de forma inmediata y cada vez que se crea una nueva tabla se agregan nuevos mensajes para respaldar esa tabla. Al crear una API personalizada, también crea un mensaje nuevo.
Un concepto clave es que, independientemente de cómo se acceda a los datos, siempre se procesarán como un mensaje a través de la canalización de eventos y se ejecutará la lógica comercial personalizada. Esto sucede tanto si se usa la interfaz de usuario de una aplicación, o una de las API, como si se realizan operaciones de administración como la importación de datos. No se pueden modificar directamente los datos de Dataverse que pasarían por alto la lógica personalizada registrada o el sistema en ejecución.
Usar la API de Dataverse
Dataverse proporciona dos estilos de API que los desarrolladores pueden utilizar para interactuar con los datos: la API web y el servicio de organización. A continuación se proporciona una descripción general de cada uno:
API web de Dataverse
La API web está disponible en un punto de conexión RESTful de OData v4. Úsela para cualquier lenguaje de programación que admita solicitudes HTTP y autenticación mediante OAuth 2.0. Encuentre más ejemplos.
Servicio de Dataverse Organization
El servicio de organización es un .NET SDK con ensamblados .NET proporcionado por Microsoft junto con generadores de clases para clases de tabla.
Cuando se usa el servicio de organización de un complemento de Dataverse, se crea una instancia del servicio, que está disponible para el código del complemento sin necesidad de autenticarse. Para obtener una instancia de la lógica de su complemento, debe utilizar el serviceProvider que se pasa al complemento para obtener una instancia del generador de servicios de la organización (IOrganizationService). Si usa el generador, puede obtener una instancia del servicio de organización. El siguiente es un ejemplo de un complemento simple que obtiene una instancia y la usa para crear una fila de la tabla de cuentas.
public void Execute(IServiceProvider serviceProvider)
{
IPluginExecutionContext pluginContext = serviceProvider.Get<IPluginExecutionContext>();
IOrganizationServiceFactory factory = serviceProvider.Get<IOrganizationServiceFactory>();
IOrganizationService orgService = serviceProvider.GetOrganizationService(pluginContext.UserId);
Entity newAccount = new Entity("account");
newAccount["name"] = "Fourth Coffee";
Guid accountid = orgService.Create(newAccount);
}
También puede utilizar el servicio de organización fuera de los complementos, por ejemplo, desde un portal personalizado ASP.NET, una Azure Function o incluso una aplicación de consola. Desde este tipo de aplicaciones, utilizaría el servicio de organización del ServiceClient de Dataverse, que proporciona soporte para aplicaciones que utilizan .NET full framework 4.6.2, 4.7.2, 4.8 y .NET Core 3.0, 3.1, 5.0., 6.0. La clase ServiceClient implementa la interfaz IOrganizationService. ServiceClient también implementa IOrganizationServiceAsync2, lo que también hace que estén disponibles versiones asincrónicas de los métodos.
El siguiente ejemplo obtiene una instancia de ServiceClient y crea una nueva fila de la tabla de cuentas.
ServiceClient serviceClient =
new ServiceClient("Url=https://yourenv.crm.dynamics.com;AuthType=OAuth;AppId=;RedirectUri=http://localhost ;LoginPrompt=Always");
Entity newAccount = new Entity("account");
newAccount["name"] = "Fourth Coffee";
Guid accountid = serviceClient.Create(newAccount);
Hay más ejemplos de uso del servicio de organización disponibles. También puede revisar más detalles sobre las cadenas de conexión y las opciones disponibles.
Las API admiten sus propios enfoques para crear consultas de datos, además de admitir FetchXML. FetchXML es un lenguaje de consulta propietario que se utiliza en Dataverse. El lenguaje FetchXML permite elaborar consultas complejas en tablas relacionadas y utilizar las condiciones y los operadores específicos de Dataverse. El conector Dataverse de Power Automate también es compatible con FetchXML.
Canalización de eventos
Cuando realiza una acción, como crear un registro en una aplicación o crear un registro usando la API, Dataverse procesa un mensaje de creación. El mensaje se procesa en la canalización de eventos que proporciona un conjunto coherente de fases por las que pasa el mensaje. Cada fase, excepto la operación principal, puede tener un complemento adjunto para ejecutar la lógica personalizada. Las siguientes son las fases admitidas cuando un mensaje comienza en la parte superior y avanza a través de las fases de la canalización:
Conocer bien cómo se procesan los mensajes puede ayudar a comprender los comportamientos y a descubrir cómo y dónde resulta mejor implementar la lógica personalizada. Conocer la canalización también es esencial para reconocer cómo encajan los complementos y las API personalizadas. Lea más sobre los detalles del marco de trabajo de eventos.
Compilación de complementos
Los complementos son clases .NET que implementan una interfaz IPlugin proporcionada por los ensamblados SDK de Dataverse. De acuerdo con esta interfaz, solo es necesario implementar un método llamado Ejecutar. El siguiente es un ejemplo de una implementación mínima:
public sealed class MyFirstPlugin : IPlugin
{
public void Execute(IServiceProvider serviceProvider)
{
//Business Logic
}
}
El método Ejecutar tiene un parámetro de tipo IServiceProvider. Esta interfaz tiene un método GetService que puede utilizar para recuperar los servicios disponibles para un complemento. Están disponibles los siguientes ejemplos de los servicios:
IPluginExecutionContext: le concede acceso al mensaje que se está procesando y a información sobre el solicitante.
ITracingService: le concede acceso para escribir en Tracelog con fines de diagnóstico.
IOrganizationServiceFactory: le concede acceso para recuperar un OrganizationService para su uso al acceder a los datos desde el complemento.
El siguiente es un ejemplo de uso de GetService para obtener el contexto de ejecución:
IPluginExecutionContext context = (IPluginExecutionContext) serviceProvider.GetService(typeof(IPluginExecutionContext));
El uso de context.InputParameters puede brindarle acceso al mensaje y contexto de origen. OutputParameters puede brindarle acceso a lo que se le devuelve al llamador.
Conocer bien el contexto de ejecución es fundamental para un desarrollador de complementos. Obtenga más información sobre el contexto de ejecución.
Para que se ejecute un complemento, debe estar registrado para la ejecución de un mensaje específico. Se puede conseguir por medio de la herramienta de registro de complementos.
API personalizadas
Las operaciones en Dataverse se definen como mensajes. Las API personalizadas ofrecen una forma basada en código de definir nuevos mensajes para ampliar los servicios web de Dataverse. Al igual que los mensajes del sistema, estos mensajes se pueden invocar, pero para ejecutar una lógica empresarial personalizada. Por ejemplo, si tiene requisitos específicos para buscar un cliente utilizando una secuencia predefinida de llamadas API, en lugar de que cada llamador de API implemente esa secuencia, podría implementar una API personalizada findcustomer. La API findcustomer ahora implementaría la lógica necesaria para buscar al cliente y devolver los resultados. Esto garantizaría que, en lugar de que cada aplicación tenga que averiguar cómo encontrar un cliente y hacerlo de manera inconsistente, pueda llamar a la API personalizada que procesará las solicitudes de búsqueda de la misma manera en cada ocasión. Y si se requieren cambios, deberán implementarse en un solo lugar.
Para definir una nueva API personalizada, comience creando un registro de API personalizado. Lo puede hacer a través del Maker Portal, a través del código o usando las soluciones de Dataverse. Como parte de la creación del registro, deberá identificar el nombre de la API personalizada, así como los parámetros de solicitud y respuesta.
Para implementar la lógica de la API personalizada, deberá crear un complemento y registrarlo en la fase de la operación principal de la canalización. La implementación de API personalizada es el único escenario en el que se puede registrar un complemento en la fase de la operación principal. Verá un ejemplo de cómo hacerlo más adelante en el ejercicio.
Una vez implementado, puede utilizar el mensaje personalizado de las API de Dataverse, Power Apps y Power Automate. El siguiente es un ejemplo del uso de la API personalizada findcustomer de C#.
var req = new OrganizationRequest("fabrikam_findcustomer")
{
["CustomerName"] = "Contoso",
["CustomerAddress"] = "1 Redmond Way"
};
var resp = serviceClient.Execute(req);
Tampoco puede implementar un complemento ni permitir que la API personalizada se utilice para desencadenar otra automatización. Por ejemplo, crear una API personalizada que contenga datos sobre un evento que ocurrió en otro sistema permitiría que ese sistema llamase a esa API en Dataverse, donde muchos puntos de integración diferentes con Azure, o Web Hooks, o Power Automate, o los complementos asincrónicos en la API podrán iniciar otras automatizaciones.