Extensiones de flujo de trabajo

Puede ampliar las opciones disponibles en el diseñador de flujo de trabajo que se usa en Microsoft Dataverse. Agregue estas extensiones agregando un ensamblado que contiene una clase que extiende la clase CodeActivity . Estas extensiones se denominan normalmente ensamblados de flujo de trabajo o actividades de flujo de trabajo.

Puede usar estas extensiones personalizadas en el diseñador de flujo de trabajo, las acciones personalizadas y los diálogos (en desuso).

Cuándo crear una extensión de flujo de trabajo

Si no encuentra la funcionalidad que necesita mediante las actividades de proceso predeterminadas, agregue actividades personalizadas para que estén disponibles en el editor que se usa para redactar procesos de flujo de trabajo, diálogo y acción.

De forma predeterminada, estos procesos incluyen un conjunto común de actividades que puede realizar, como se muestra en la tabla siguiente:

Use la actividad Realizar acción para ejecutar cualquier acción personalizada o los siguientes mensajes del sistema denominados Acciones de comando:

Si tiene soluciones de Dynamics 365 Sales o Service, puede encontrar otras acciones de comando en función de la solución:

Para obtener más información, consulte:

• Configuración de fases y pasos de flujo de trabajo
• Uso de diálogos de Dataverse para procesos guiados
• Creación de una acción personalizada

Tecnología usada

Puede registrar un ensamblado creado mediante la biblioteca de actividades de .NET Framework que define actividades personalizadas. Estas actividades aparecen en el editor de aplicaciones web y se invocan cuando se ejecuta el proceso.

Las actividades de flujo de trabajo personalizadas requieren la creación de un ensamblado de .NET Framework que incluya una o varias clases derivadas de la clase CodeActivity abstracta. Esta clase proporciona el método Execute(CodeActivityContext) al que llama la plataforma dataverse cuando se ejecuta la actividad. Cada clase del ensamblado define una actividad específica.

Las actividades de flujo de trabajo deben definir parámetros de entrada y salida visibles en el diseñador de procesos. Estos parámetros permiten a alguien pasar datos a la actividad de flujo de trabajo y recibir la salida procesada. Al escribir la clase, agregue propiedades a estos parámetros y anótelos con atributos de .NET para proporcionar los metadatos que Dataverse usa para mostrar su actividad de flujo de trabajo personalizada en el diseñador con los parámetros necesarios.

Creación de un ensamblado de actividad de flujo de trabajo personalizado

En estos pasos se describe cómo crear una actividad de flujo de trabajo personalizada mediante Visual Studio. Para obtener un ejemplo paso a paso completo, consulte Tutorial: Creación de una extensión de flujo de trabajo.

1. Cree un proyecto de biblioteca de clases destinado a .NET Framework 4.6.2.

   Importante

   Aunque los ensamblados compilados con versiones posteriores suelen funcionar, se produce un error si usan características introducidas después de la versión 4.6.2.

2. Instale el paquete NuGet Microsoft.CrmSdk.Workflow .

   Este paquete incluye el paquete Microsoft.CrmSdk.CoreAssemblies .

3. (Opcional) Si desea usar clases de tabla con ligadura temprana, inclúyalas en el proyecto.

   Para obtener más información, consulte:

   • Programación en tiempo de ejecución y en tiempo de compilación mediante el SDK para .NET
   • Generar clases de enlace en tiempo de compilación para SDK para .NET

4. Agregue una clase pública. El nombre de la clase debe corresponderse con la acción que realiza la actividad.

5. Agregue las siguientes directivas using.

   using System.Activities;
   using Microsoft.Xrm.Sdk;
   using Microsoft.Xrm.Sdk.Workflow;
   

6. Agregue propiedades a la clase para representar los parámetros de entrada o salida. Use atributos de .NET para proporcionar los metadatos necesarios para exponer estas propiedades al diseñador de procesos de flujo de trabajo.

   Para obtener más información, vea Agregar parámetros.

7. Haga que la clase derive de la clase CodeActivity e implemente el método Execute(CodeActivityContext) que contiene las operaciones que realiza la actividad.

   Para obtener más información, vea Agregar el código al método Execute.

8. Firme el ensamblado.

9. Compile el ensamblado.

10. Registre su ensamblaje mediante la herramienta de registro de complementos. Establezca las Name propiedades y WorkflowActivityGroupName para definir el texto que muestra el diseñador de flujo de trabajo.

    Para obtener más información, consulte Registrar el ensamblado.

11. Pruebe la actividad del flujo de trabajo invocándola desde un flujo de trabajo, un cuadro de diálogo o procesos de acción.

12. (Recomendado) Agregue la tarea de flujo de trabajo a una solución.

Incorporación de parámetros

Al definir parámetros para la clase, definalos como tipos InArgument<T>, OutArgument<T> o InOutArgument<T> . Estos tipos proporcionan métodos heredados de una clase argument común para obtener o establecer los parámetros. El código usa estos métodos en el Execute método . Para obtener más información, vea Agregar el código al método Execute.

Cuando la actividad de flujo de trabajo personalizada usa parámetros de entrada o salida, agregue los atributos de .NET adecuados a las propiedades de clase pública que las definen. El diseñador de procesos lee estos datos para definir cómo se pueden establecer los parámetros en el diseñador de procesos.

Puede usar los siguientes tipos de propiedades como parámetros de entrada o salida:

Parámetros de entrada y salida

Para definir el texto que se va a mostrar para un parámetro de entrada o salida en el diseñador de procesos, use el siguiente patrón con atributos de .NET:

[Input("Integer input")]
public InArgument<int> IntInput { get; set; }

o bien

[Output("Integer output")]
public OutArgument<int> IntOutput { get; set; }

Una sola propiedad de la clase puede ser un parámetro de entrada y salida mediante la inclusión de ambos atributos:

[Input("Int input")]  
[Output("Int output")]  
public InOutArgument<int> IntParameter { get; set; }

Valores necesarios

Para requerir un parámetro de entrada al usar la actividad del flujo de trabajo en un proceso, use el atributo [RequiredArgument].

Valores predeterminados

Cuando se pasa un valor como parámetro de entrada o se establece un parámetro de salida sin definir el valor, especifique un valor predeterminado. Por ejemplo, el código siguiente establece el valor predeterminado de una propiedad bool:

[Input("Bool input")]
[Default("True")]
public InArgument<bool> Bool { get; set; }

El formato del valor predeterminado depende del tipo de propiedad. Los ejemplos se encuentran en la tabla siguiente:

Parámetros de referenciaDeEntidad

Cuando defina una propiedad para un EntityReference parámetro, use el ReferenceTarget atributo . Este atributo establece qué tipo de tabla se permite. Por ejemplo:

[Input("EntityReference input")]
[Output("EntityReference output")]
[ReferenceTarget("account")]
public InOutArgument<EntityReference> AccountReference { get; set; }

Parámetros OptionSetValue

Cuando defina una propiedad para un OptionSetValue parámetro, use el AttributeTarget atributo . Este atributo define qué tabla y columna contienen el conjunto válido de valores para el parámetro . Por ejemplo:

[Input("Account IndustryCode value")]
[AttributeTarget("account", "industrycode")]
[Default("3")]
public InArgument<OptionSetValue> IndustryCode { get; set; }

Agrega tu código al método Execute

La lógica que se incluye en el método CodeActivity.Execute(CodeActivityContext) define lo que hace la actividad de flujo de trabajo.

Parámetros de referencia

Para hacer referencia a los parámetros que defina para la clase, use los métodos Argument.Get o Argument.Set(ActivityContext, Object). Estos métodos requieren la instancia codeActivityContext que se pasa al Execute método . En el ejemplo siguiente se muestra cómo acceder al valor de un parámetro de entrada y establecer el valor de un parámetro de salida.

using Microsoft.Xrm.Sdk.Workflow;
using System.Activities;

namespace SampleWorkflowActivity
{
  public class IncrementByTen : CodeActivity
  {
    [RequiredArgument]
    [Input("Decimal input")]
    public InArgument<decimal> DecInput { get; set; }

    [Output("Decimal output")]
    public OutArgument<decimal> DecOutput { get; set; }

    protected override void Execute(CodeActivityContext context)
    {
      decimal input = DecInput.Get(context);
      DecOutput.Set(context, input + 10);
    }
  }
}

Obtener información contextual

Cuando el código requiere información contextual, acceda a ella mediante el método CodeActivityContext.GetExtension<T> con la IWorkflowContext interfaz . Este objeto se deriva de la IExecutionContext interfaz , que proporciona acceso a muchas propiedades de solo lectura que describen el contexto de la operación. El IWorkflowContext proporciona información contextual similar específica del flujo de trabajo que se ejecuta que usa el ensamblado de flujo de trabajo.

Usa el código siguiente en tu función Execute para acceder a IWorkflowContext.

protected override void Execute(CodeActivityContext context)
{
 IWorkflowContext workflowContext = context.GetExtension<IWorkflowContext>();
...

Utilice el SDK para .NET

Cuando necesite realizar operaciones de datos mediante el SDK para .NET, acceda a él mediante el método CodeActivityContext.GetExtension<T> con la IOrganizationServiceFactory interfaz. Desde allí, use el CreateOrganizationService(Nullable<Guid>) método para acceder a una instancia del proxy de servicio que puede usar para realizar operaciones de datos. La propiedad IWorkflowContext.InitiatingUserId se puede usar para determinar el contexto de usuario que se utilizará si quiere que la operación se realice en el mismo contexto que el proceso de llamada. Utilice el siguiente código en su función Execute para obtener acceso al servicio de la organización:

protected override void Execute(CodeActivityContext context)
{
 IWorkflowContext workflowContext = context.GetExtension<IWorkflowContext>();
 IOrganizationServiceFactory serviceFactory = context.GetExtension<IOrganizationServiceFactory>();

 // Use the context service to create an instance of IOrganizationService.             
 IOrganizationService service = serviceFactory.CreateOrganizationService(workflowContext.InitiatingUserId);
...

Registrar el ensamblado

Use la herramienta Registro de complementos (PRT) para registrar ensamblados que contienen actividades de flujo de trabajo personalizadas. Esta herramienta es la misma que se usa para registrar complementos. Para los complementos y las actividades de flujo de trabajo personalizadas, debe registrar el ensamblado para cargarlo en el entorno. Sin embargo, no se registran los pasos de las actividades personalizadas del flujo de trabajo.

Para las actividades de flujo de trabajo personalizadas, especifique las siguientes propiedades para controlar lo que muestra el diseñador de procesos de flujo de trabajo.

Depurar actividades de flujo de trabajo

Al implementar actividades de flujo de trabajo personalizadas en Dataverse, puede capturar perfiles para reproducir para la depuración local y usar el servicio de seguimiento para escribir información en una tabla.

En el ejemplo siguiente se muestra cómo usar el servicio de seguimiento para escribir el mensaje: Add your message.

protected override void Execute(CodeActivityContext context)
{
//Create the tracing service
ITracingService tracingService = context.GetExtension<ITracingService>();

//Use the tracing service
tracingService.Trace("{0} {1} {2}.", "Add", "your", "message");
...

Para obtener más información, consulte:

• Depurar actividades de flujo de trabajo
• Utilizar seguimiento
• Ver registros de seguimiento

Agregar a la solución

Al registrar ensamblados mediante la herramienta de registro del complemento, se agregan a la solución Predeterminada. No confunda esta solución con la solución predeterminada de Common Data Service. Dado que la solución Predeterminada contiene todas las personalizaciones no administradas aplicadas al entorno, para poder distribuir la actividad de flujo de trabajo personalizada mediante una solución, debe agregarla a una solución no administrada. Por ejemplo, puede agregarlo a la Solución Predeterminada de Common Data Service o a cualquier solución no administrada que haya creado.

Administración de cambios en actividades de flujo de trabajo personalizadas

Debe mantener el código para las actividades de flujo de trabajo personalizadas. Dado que los cambios de código pueden incluir cambios que rompen la compatibilidad, debe gestionar estos cambios. Siga los distintos pasos para actualizar o mejorar los ensamblados de flujo de trabajo personalizados.

Al registrar un ensamblado que contiene actividades de flujo de trabajo personalizadas, se incluye la versión del ensamblado. La herramienta de registro extrae esta información mediante la reflexión del ensamblado. Puede controlar el número de versión mediante el AssemblyInfo.cs archivo del proyecto de Visual Studio.

Encontrará una sección en la parte inferior que tiene este aspecto:

// Version information for an assembly consists of the following four values:
//
//      Major Version
//      Minor Version 
//      Build Number
//      Revision
//
// You can specify all the values or you can default the Build and Revision Numbers 
// by using the '*' as shown below:
//[assembly: AssemblyVersion("1.0.0.*")]
[assembly: AssemblyVersion("1.0.0.0")]
[assembly: AssemblyFileVersion("1.0.0.0")]

Esta información de versión es importante porque permite aplicar actualizaciones a ensamblados implementados o ensamblados de actualización cuando quiera incluir nuevas funcionalidades.

Actualización de un ensamblado de actividad de flujo de trabajo personalizado

Al corregir errores o refactorizar código sin realizar cambios significativos en las clases públicas o firmas de método, actualice el ensamblado para que todos los procesos en ejecución empiecen a usar automáticamente la nueva versión del ensamblado.

Para actualizar un ensamblado

1. Cambie solo los valores número de compilación y revisión del AssemblyInfo.csAssemblyVersion atributo. Por ejemplo, cambie de 1.0.0.0 a 1.0.10.5.
2. Utiliza la herramienta de registro de complementos para actualizar el ensamblado. Para obtener más información, vea Actualizar un ensamblado.

Actualización de un ensamblado de actividad de flujo de trabajo personalizado

Si realiza cambios que incluyen cambios significativos en clases públicas o firmas de método, como cambiar los parámetros, interrumpirá los procesos actualmente en ejecución definidos para usar las firmas originales. En este caso, debe actualizar el ensamblado. Esta acción crea una nueva actividad de flujo de trabajo personalizada que expone las opciones para definir qué versión se va a aplicar en el diseñador de procesos. Este control de versiones permite que cada proceso que use esta actividad se vuelva a configurar para adaptarse a los cambios incluidos en el nuevo ensamblado. Una vez actualizados todos los procesos que usan el ensamblado original para usar el ensamblado actualizado, puede anular el registro del ensamblado anterior.

Para actualizar un ensamblado

1. Asegúrese de que el nuevo ensamblado tiene el mismo Name, PublicKeyTokeny Culture que el ensamblado existente.

2. Cambie los valores versión principal o versión secundaria en el AssemblyInfo.csAssemblyVersion atributo . Por ejemplo, cambie de 1.0.0.0 a 2.0.0.0.

3. Use la herramienta Registro de complementos para registrar el ensamblado como un nuevo ensamblado. Para obtener más información, vea Registrar un ensamblado.

4. Para cada proceso que utilice la actividad de flujo de trabajo personalizada, desactive el proceso y luego edite los pasos que utilizan dicha actividad personalizada.

   Encontrará un selector de versiones en el diseñador de procesos que puede usar para elegir qué versión del ensamblado se debe usar.

   

Cuando todos los procesos se hayan convertido para usar el nuevo ensamblado, use la herramienta de Registro de Complementos para anular el registro del ensamblado, de manera que ya no esté disponible. Para obtener más información, consulte Anular el registro de componentes.

Guía de rendimiento

Las consideraciones de rendimiento para las extensiones de flujo de trabajo son las mismas que para los complementos normales. Para obtener más información, consulte Análisis del rendimiento del complemento.

A diferencia de un complemento normal, las extensiones de flujo de trabajo no proporcionan la oportunidad de registrar explícitamente el código para un paso específico. No controla si el código de la extensión de flujo de trabajo se ejecuta de forma sincrónica o asincrónica. El código que se ejecuta de forma sincrónica requiere especial atención porque afecta directamente a la experiencia del usuario de la aplicación.

Como componentes reutilizables, puede agregar extensiones de flujo de trabajo a cualquier flujo de trabajo o acción personalizada. Puede configurar el flujo de trabajo como un flujo de trabajo en tiempo real , lo que significa que se ejecuta sincrónicamente. Las acciones personalizadas siempre son sincrónicas, pero no participan en una transacción de base de datos a menos que establezca Habilitar reversión.

Tenga en cuenta que, en un flujo de trabajo sincrónico o una acción personalizada que participa en la transacción, cualquier error producido por la extensión de flujo de trabajo hace que toda la transacción sea revertida. Esta reversión es una operación costosa que puede afectar al rendimiento.

Use el valor de la IWorkflowContextpropiedad .WorkflowMode para determinar si el flujo de trabajo se ejecuta de forma sincrónica.

Fases de flujo de trabajo en tiempo real

Cuando se usa una extensión de flujo de trabajo en un flujo de trabajo en tiempo real (sincrónico), la canalización de ejecución de eventos invoca la extensión en fases específicas. En la tabla siguiente se muestran estas fases. Para más información, consulte Canalización de ejecución de eventos.

Usa el valor en la propiedad IWorkflowContext.StageName para detectar la fase.

Para la operación De actualización , puede configurar la fase mediante las opciones Antes o Después en el diseñador de flujo de trabajo. Para obtener más información, consulte Uso de flujos de trabajo en tiempo real.

Si la extensión de flujo de trabajo depende de los datos pasados en el contexto de ejecución, la fase en la que se ejecuta controla si los datos están disponibles en IWorkflowContext.InputParameters y IWorkflowContext.OutputParameters.

Imágenes de entidad para extensiones de flujo de trabajo

No se pueden configurar imágenes de entidad para extensiones de flujo de trabajo. Solo registra el ensamblado y la actividad del flujo de trabajo se ejecuta en el contexto del flujo de trabajo. Las imágenes de entidades de extensiones de flujos de trabajo están disponibles mediante los valores clave PreBusinessEntity y PostBusinessEntity respectivamente para imágenes anteriores y posteriores a la entidad. Para obtener más información, consulte Imágenes de entidad.

Consulte también

Prácticas recomendadas e instrucciones sobre la programación de complementos y flujos de trabajo
Tutorial: Crear extensión de flujo de trabajo
Ejemplo: crear una actividad de flujo de trabajo personalizada
Ejemplo: Actualización del próximo cumpleaños mediante una actividad de flujo de trabajo personalizada
Ejemplo: Cálculo de una puntuación de crédito con una actividad de flujo de trabajo personalizada