Comprender el contexto de los datos pasados a un complemento

 

Publicado: noviembre de 2016

Se aplica a: Dynamics CRM 2015

Cuando un complemento se ejecuta en respuesta a un evento de canalización de ejecuciones para el que está registrado, se llama al método Execute del complemento. El método pasa un objeto IServiceProvider como parámetro, que contiene varios objetos útiles. En las siguientes secciones se describe parte de la información que se pasa a un complemento cuando se ejecuta.

En este tema

Obtenga acceso a contexto de ejecución del complemento

Acceso al servicio de la organización

Acceso al servicio de notificación

Parámetros de entrada y salida

Imágenes anteriores y posteriores a la entidad

Obtenga acceso a contexto de ejecución del complemento

IPluginExecutionContext contiene información que describe el entorno de tiempo de ejecución que ejecuta el complemento, información relacionada con la canalización de ejecuciones e información de negocio de la entidad. El contexto está contenido en el parámetro System.IServiceProvider que se pasa en tiempo de ejecución a un complemento por medio del método Execute.

// Obtain the execution context from the service provider.
IPluginExecutionContext context = (IPluginExecutionContext)
    serviceProvider.GetService(typeof(IPluginExecutionContext));

Cuando se activa un evento del sistema para el que está registrado un complemento, el sistema crea y rellena el contexto y lo pasa a un complemento a través de las clases y métodos mencionados con anterioridad. El contexto de ejecución se pasa a cada complemento registrado de la canalización cuando se ejecuta. Cada complemento de canalización de ejecuciones puede modificar las propiedades grabables en contexto. Por ejemplo, dados un complemento registrado anterior al evento y otro complemento registrado posterior al evento, el complemento posterior al evento puede recibir un contexto que haya modificado el complemento anterior al evento. La misma situación se aplica a los complementos registrados en la misma fase.

Todas las propiedades de IPluginExecutionContext son de solo lectura. Sin embargo, el complemento puede modificar el contenido de las propiedades que son colecciones. Para obtener más información sobre la prevención de bucle infinito, vea Depth.

Acceso al servicio de la organización

Para tener acceso al servicio de la organización de Microsoft Dynamics 365, se requiere que el código del complemento cree una instancia del servicio por medio del método ServiceProvider.GetService.

// Obtain the organization service reference.
IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

La plataforma proporciona las direcciones URL del servicio web y las credenciales de red correctas para cuando use este método. No se admite crear una instancia del proxy de servicio web propio porque creará problemas de interbloqueo y autenticación.

Acceso al servicio de notificación

Los complementos registrados sincrónicos pueden publicar el contexto de la ejecución a Bus de servicio de Microsoft Azure. El objeto de proveedor de servicios que se pasa al complemento contiene una referencia a IServiceEndpointNotificationService. Es a través de ese servicio de notificación por el que los complementos sincrónicos envían los mensajes asincrónicos a Bus de servicio de Microsoft Azure. Para obtener más información acerca de Microsoft Azure, vea Integración de Azure con Microsoft Dynamics CRM. Para obtener más información sobre la grabación de un complemento que se puede publicar en Bus de servicio de Microsoft Azure, vea Escribir un complemento con Azure personalizado.

Parámetros de entrada y salida

La propiedad InputParameters contiene los datos que incluye el mensaje de solicitud actualmente en proceso por la canalización de ejecuciones del evento. El código del complemento tiene acceso a estos datos. La propiedad es de tipo ParameterCollection donde las claves para obtener acceso a los datos de solicitud son los nombres de las propiedades públicas reales de la solicitud. Por ejemplo, observe CreateRequest. Una propiedad de CreateRequest se denomina Target, que es de tipo Entity. Se trata de la entidad sobre la que opera actualmente la plataforma. Para tener acceso a los datos de la entidad usaría el nombre "Target" como clave de la colección de parámetros de entrada. También necesita convertir la instancia devuelta.

// The InputParameters collection contains all the data passed in the message request.
if (context.InputParameters.Contains("Target") &&
    context.InputParameters["Target"] is Entity)
{
    // Obtain the target entity from the input parameters.
    Entity entity = (Entity)context.InputParameters["Target"];

Tenga en cuenta que no todas las solicitudes contienen una propiedad Target que sea de tipo Entity, por lo que tendrá que buscar en cada solicitud o respuesta. Por ejemplo, DeleteRequest tiene una propiedad Target , pero su tipo es EntityReference. El código de ejemplo anterior se debería cambiar como se indica a continuación.

// The InputParameters collection contains all the data passed in the message request.
if (context.InputParameters.Contains("Target") &&    context.InputParameters["Target"] is EntityReference)
{
    // Obtain the target entity from the input parameters.
    EntityReference entity = (EntityReference)context.InputParameters["Target"];
}

Una vez que tenga acceso a los datos de la entidad, puede leerlos y editarlos. Los cambios de datos en el contexto realizados por los complementos registrados en la fase 10 o 20 de la canalización se pasan en el contexto a la operación principal en la fase 30.

Importante

No todos los campos en el registro de la entidad que se pasan a un complemento a través del contexto se pueden editar. Debe comprobar la propiedad de metadatos IsValidForUpdate del campo para comprobar que no está definida como false. Intentar cambiar el valor de un campo que no pueda actualizarse da lugar a una excepción.

De forma similar, la propiedad OutputParameters contiene los datos que incluye el mensaje de respuesta, por ejemplo CreateResponse, que actualmente se están pasando a través de la canalización de ejecuciones del evento. Sin embargo, el resultado de la operación de la plataforma principal es que solo los complementos posteriores al evento sincrónicos y los complementos registrados asincrónicos tienen la propiedad OutputParameters rellenada como la respuesta. La propiedad es de tipo ParameterCollection donde las claves para obtener acceso a los datos de respuesta son los nombres de las propiedades públicas reales de la respuesta.

Imágenes anteriores y posteriores a la entidad

PreEntityImages y PostEntityImages contienen instantáneas de los atributos de la entidad principal antes (pre) y después (post) la operación de la plataforma de base.Microsoft Dynamics 365 rellena imágenes de preentidad y postentidad en función de los privilegios de seguridad del usuario del sistema suplantado. Sólo los atributos de entidad establecidos en un valor o que son null están disponibles en imágenes anteriores o posteriores a la entidad. Puede especificar que la plataforma rellene esas propiedades PreEntityImages y PostEntityImages cuando registra el complemento. El valor de alias de entidad especificado durante el registro del complemento se usa como clave en la colección de imágenes del código del complemento.

Existen algunos eventos donde no están disponibles las imágenes. Por ejemplo, sólo los complementos posteriores al evento sincrónicos y los complementos registrados asincrónicos tienen la propiedad PostEntityImages rellenada. La operación de creación no admite una imagen previa y una operación de eliminación no admite una imagen posterior. Además, solo un pequeño subconjunto de mensajes admite las imágenes previa y posterior como se muestra en la siguiente tabla.

Solicitud de mensaje	Propiedad	Descripción
AssignRequest	Destino	La entidad asignada.
CreateRequest	Destino	La entidad creada.
DeleteRequest	Destino	La entidad eliminada.
DeliverIncomingEmailRequest	EmailId	Identificador de correo electrónico entregado.
DeliverPromoteEmailRequest	EmailId	Identificador de correo electrónico entregado.
ExecuteWorkflowRequest	Destino	La entidad de flujo de trabajo.
MergeRequest	Destino	La entidad principal, en la que los datos de la entidad secundaria se combinan.
MergeRequest	SubordinateId	La entidad secundaria que se va a combinar en la entidad principal.
SendEmailRequest	EmailId	Identificador de entidad de envío.
SetStateRequest	EntityMoniker	La entidad para la que se establece el estado.
UpdateRequest	Destino	La entidad actualizada.

El registro para que las imágenes previas o posteriores tengan acceso a los valores de atributo de entidad da lugar a mejoras en el rendimiento del complemento si se compara con la obtención de atributos de entidad en el código del complemento por medio de las solicitudes RetrieveRequest o RetrieveMultipleRequest.

Seguridad Nota

Una preimagen pasada en el contexto de ejecución a un complemento o una actividad de flujo de trabajo de complemento personalizada puede contener datos que el usuario que ha iniciado sesión no tiene privilegios para acceder. Los administradores de Microsoft Dynamics 365 y otros usuarios con permisos de alto nivel pueden registrar complementos para ejecutarse en la cuenta de usuario del "sistema" o el código de complementos puede realizar llamadas como usuario del "sistema" en nombre del usuario del portal. Si esto ocurre, los usuarios que han iniciado sesión pueden obtener acceso a datos a los que su seguridad de nivel de campo no permite obtener acceso.Más información:Suplantación en complementos

Ver también

Desarrollo de complementos
Administrar las excepciones en complementos
Canalización de ejecución del evento
Usar mensajes (clases de respuesta y solicitud) con el método Execute
Usar el servicio web IOrganizationService para leer y escribir datos o metadatos
Registrar e implementar complementos

© 2017 Microsoft. Todos los derechos reservados. Copyright