Entender el contexto de ejecución
La Canalización de ejecución de eventos pasa a los complementos registrados una cantidad grande de datos sobre la operación que se procesa en estos momentos y el entorno de ejecución del código personalizado. Las siguientes secciones describen los datos que se pasan a su complemento o actividad de flujo de trabajo personalizado.
Para complementos
Con complementos puede obtener acceso a estos datos en el código si establece una variable que implemente la interfaz IPluginExecutionContext:
// Obtain the execution context from the service provider.
IPluginExecutionContext context = (IPluginExecutionContext)
serviceProvider.GetService(typeof(IPluginExecutionContext));
Este IPluginExecutionContext proporciona información sobre la Stage para la que está registrado el complemento así como información sobre el ParentContext.
Más información: ParentContext
Para actividades personalizadas del flujo de trabajo
Con actividades personalizadas del flujo de trabajo puede obtener acceso a estos datos en el código si establece una variable que implemente la interfaz IWorkflowContext:
// Obtain the execution context using the GetExtension method.
protected override void Execute(CodeActivityContext context)
{
IWorkflowContext workflowContext = context.GetExtension<IWorkflowContext>();
...
Este IWorkflowContext proporciona información sobre el flujo de trabajo en el que se ejecuta la actividad de flujo de trabajo personalizado.
| Propiedad | Descripción |
|---|---|
| ParentContext | Obtiene el contexto principal. Consulte ParentContext |
| StageName | Obtiene la información de la fase de la instancia de proceso. |
| WorkflowCategory | Obtiene la información de categoría del proceso de la instancia del proceso: Es un flujo de trabajo o un diálogo (obsoleto). |
| WorkflowMode | Indica cómo se debe ejecutar el flujo de trabajo. 0 = asincrónico, = 1 sincrónico |
ParentContext
El ParentContext proporciona información sobre cualquier operación que desencadene la ejecución del complemento o de la actividad de flujo de trabajo personalizada.
Salvo casos documentos específicos, debe evitar tomar una dependencia de los valores que encuentre en ParentContext para aplicar la lógica de negocios. El orden específico en el que se realizan las operaciones no está garantizado y puede cambiar a lo largo del tiempo.
Si elige tomar una dependencia en valores encontrados en el ParentContext, deberá dar pasos para asegurarse de que el código es resistente para adaptarse a cambios potenciales. Debe probar la lógica periódicamente para comprobar que las condiciones de las depende se mantienen en vigor a lo largo del tiempo.
ExecutionContext
El resto de la información disponible es proporcionada por la interfaz IExecutionContext que implementan las clases IPluginExecutionContext y IWorkflowContext.
Para los complementos todas las propiedades de esta clase de contexto de ejecución proporcionan información útil que puede necesitar para tener acceso desde su código.
Nota
Para las actividades de flujo de trabajo personalizadas no se usan normalmente estas propiedades.
Dos de las más importantes son las propiedades InputParameters y OutputParameters.
Otras propiedades usadas con frecuencia son SharedVariables, PreEntityImages y PostEntityImages.
Sugerencia
Una buena manera de visualizar los datos que se pasan al contexto de ejecución es instalar la solución del generador de perfiles de complementos que está disponible como parte de la herramienta de registro de complementos. El generador de perfiles capturará la información de contexto así como información que permite reproducir el evento localmente para poder depurar. En la herramienta de registro de complementos, puede descargar un documento XML con todos los datos del evento que desencadenó el flujo de trabajo. Más información: Ver datos del perfil de complementos
ParameterCollections
Todas las propiedades del contexto de ejecución son de solo lectura. Pero los InputParameters, OutputParameters, y SharedVariables son valores ParameterCollection. Puede manipular los valores de los elementos de estas colecciones para cambiar el comportamiento de la operación, en función de la fase de la canalización de ejecuciones de eventos para la que está registrado el complemento.
Los valores ParameterCollection se definen como estructuras KeyValuePair. Para obtener acceso a una propiedad deberá conocer el nombre de la propiedad que revela el mensaje. Por ejemplo, para obtener acceso a la propiedad Entity que se pasa como parte de CreateRequest, es necesario saber que el nombre de esa propiedad es Target. A continuación puede obtener acceso a este valor utilizando código como éste:
var entity = (Entity)context.InputParameters["Target"];
Use la documentación de Microsoft.Xrm.Sdk.Messages y Microsoft.Crm.Sdk.Messages para conocer los nombres de los mensajes definidos en los ensamblados del SDK. Para acciones personalizadas, consulte los nombres de los parámetros definidos en el sistema.
InputParameters
Los InputParameters representan el valor de la propiedad OrganizationRequest.Parameters que representa la operación procedente de los servicios web.
Como se describe en Usar mensajes con SDK para .NET, todas las operaciones que se producen en el sistema son en definitiva instancias de al case OrganizationRequest que está procesando el método IOrganizationService.Execute .
Como se describe en Marco de trabajo de eventos, las operaciones pasan a través de una serie de fases y puede registrar el complemento en fases que se producen antes de que los datos se escriban en la base de datos. En las fases PreValidation y PreOperation, puede leer y cambiar los valores de los InputParameters de modo que puede controlar el resultado esperado de la operación de datos.
Si encuentra que los valores de la colección de InputParameters representan una condición que no puede permitir, puede lanzar una InvalidPluginExecutionException (preferentemente en la fase de PreValidation) que cancelará la operación y mostrará un error al usuario con un complemento sincrónico, o registrará el error si el complemento es asincrónico. Más información: Cancelación de una operación
OutputParameters
Los OutputParameters representan el valor de la propiedad OrganizationResponse.Results que representa el valor devuelto de la operación. Cada una de las clases de respuesta de mensaje que se deriva de OrganizationResponse contiene propiedades específicas. Para obtener acceso a estas propiedades debe usar el valor de clave que es normalmente igual que el nombre de las propiedades en la clase de respuesta. No obstante, esto no siempre es verdad. La siguiente tabla muestra las propiedades de clases de respuesta de mensaje que tienen claves diferentes del nombre de las propiedades.
Los OutputParameters no se rellenan hasta después de la transacción de base de datos, de modo que solo están disponibles para complementos registrados en la fase PostOperation. Si desea cambiar los valores devueltos por la operación, puede modificarlos en los OutputParameters.
Variables compartidas
La propiedad SharedVariables permite incluir los datos que se pueden pasar de la API o un complemento a un paso que se produce después en la canalización de ejecuciones. Dado que este es un valor de ParameterCollection, los complementos pueden agregar, leer o modificar propiedades para compartir datos con pasos posteriores.
El siguiente ejemplo muestra cómo se puede pasar un valor PrimaryContact desde un complemento registrado para un paso de PreOperation a un paso PostOperation.
public class PreOperation : IPlugin
{
public void Execute(IServiceProvider serviceProvider)
{
// Obtain the execution context from the service provider.
Microsoft.Xrm.Sdk.IPluginExecutionContext context = (Microsoft.Xrm.Sdk.IPluginExecutionContext)
serviceProvider.GetService(typeof(Microsoft.Xrm.Sdk.IPluginExecutionContext));
// Create or retrieve some data that will be needed by the post event
// plug-in. You could run a query, create an entity, or perform a calculation.
//In this sample, the data to be passed to the post plug-in is
// represented by a GUID.
Guid contact = new Guid("{74882D5C-381A-4863-A5B9-B8604615C2D0}");
// Pass the data to the post event plug-in in an execution context shared
// variable named PrimaryContact.
context.SharedVariables.Add("PrimaryContact", (Object)contact.ToString());
}
}
public class PostOperation : IPlugin
{
public void Execute(IServiceProvider serviceProvider)
{
// Obtain the execution context from the service provider.
Microsoft.Xrm.Sdk.IPluginExecutionContext context = (Microsoft.Xrm.Sdk.IPluginExecutionContext)
serviceProvider.GetService(typeof(Microsoft.Xrm.Sdk.IPluginExecutionContext));
// Obtain the contact from the execution context shared variables.
if (context.SharedVariables.Contains("PrimaryContact"))
{
Guid contact =
new Guid((string)context.SharedVariables["PrimaryContact"]);
// Do something with the contact.
}
}
}
Importante
Cualquier tipo de datos agregado a la colección de variables compartidas debe ser serializable; en caso contrario, el servidor no sabrá como serializar los datos y la ejecución de complementos no se realizará correctamente.
Nota
Para un complemento registrado para las fases PreOperation o PostOperation para tener acceso a las variables compartidas de un complemento registrado para la fase PreValidation que se ejecuta al Crear, Actualizar, Eliminar o por una RetrieveExchangeRateRequest, debe tener acceso a la colección ParentContext.SharedVariables. Para el resto de los casos, IPluginExecutionContext.SharedVariables contiene la colección.
Pasar una variable compartida desde la API web
Si necesita introducir una variable compartida cuando llama a una API, use la palabra clave tag desde la API web o desde el SDK para .NET para pasar un valor de cadena.
Este valor será accesible en la colección de Variables Compartidas usando la clave tag. Una vez establecido, este valor no se puede cambiar, es inmutable.
Más información: Agregar una variable compartida al contexto de ejecución del complemento.
Imágenes de entidad
Al registrar una paso para un complemento que incluye una tabla como uno de los parámetros, tiene la opción de especificar que una copia de los datos de la tabla se incluya como instantánea o imagen mediante las propiedades PreEntityImages y/o PostEntityImages.
Estos datos proporcionan un punto de comparación para los datos de tabla mientras atraviesan la canalización de eventos. El uso de estas imágenes proporciona un rendimiento mucho mejor que incluir código en un complemento para recuperar una tabla solo para comparar los valores de atributo.
Al definir una imagen de la entidad, especifique un valor de alias de entidad que puede usar para tener acceso a la imagen específica. Por ejemplo, si define pre una imagen de preentidad con el alias 'a', puede usar el siguiente código para acceder al valor del atributo name.
var oldAccountName = (string)context.PreEntityImages["a"]["name"];
Más información:
Consultar también
Marco de trabajo de eventos
Escribir un complemento
Nota
¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)
La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente las Cuestiones de GitHub como mecanismo de retroalimentación para el contenido y lo sustituiremos por un nuevo sistema de retroalimentación. Para más información, consulta: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de