Tutorial: Actualizar un complemento

Este tutorial es el tercero de una serie que muestra cómo trabajar con complementos.

• Tutorial: Escribir y registrar un complemento
• Tutorial: Depurar un complemento
• Tutorial: Actualizar un complemento (este tutorial)

Para obtener una explicación detallada de los conceptos auxiliares y los detalles técnicos, consulte:

• Use complementos para ampliar los procesos de negocio
• Escribir un complemento
• Registrar un complemento
• Depuración de complementos

Objetivo

En este tutorial se describen las tareas comunes que se realizan con complementos. En este tutorial:

• Actualizar un ensamblado de complementos
• Crear y registrar un complemento sincrónico
• Usar los datos de configuración en el complemento
• Generar un error para mostrárselo al usuario
• Configurar y usar una imagen previa de la entidad en el código
• Anulación del registro de un ensamblado, un complemento o un paso

El objetivo de este tutorial es:

• Crear un complemento sincrónico registrado en la etapa de prevalidación del mensaje de actualización de la tabla de cuentas.
• Evalúe un conjunto de valores de cadena pasados como datos de configuración cuando se registre el complemento.
• Si el nombre de la cuenta se cambia a uno de estos valores y el valor anterior no contenía el nuevo nombre, cancele la operación y envíe un mensaje de error de vuelta al usuario.

Requisitos previos

• Tutorial completo : Escritura y registro de un complemento.
• Tutorial: Se recomienda depurar un complemento pero no es obligatorio.

Nota

Dado que muchos pasos básicos se describen en detalle en Tutorial: Escritura y registro de un complemento, este tutorial no incluye el mismo nivel de detalle para esos pasos.

Crear una nueva clase de complemento

1. En Visual Studio, agregue una nueva clase al proyecto BasicPlugin denominado ValidateAccountName.cs.

   Nota

   Al realizar un cambio significativo en un ensamblado, actualice la versión del ensamblado. Este paso es especialmente importante si planea actualizar un ensamblado que forma parte de una solución administrada. La versión forma parte del nombre completo del ensamblado, que es un identificador único del ensamblado. Es posible que el proceso de actualización de la solución no reconozca que el ensamblado cambió cuando el nombre completo del ensamblado no cambia.

2. Agregue el código siguiente a la clase y vuelva a generar el ensamblado.

using Microsoft.Xrm.Sdk;
using System;
using System.Collections.Generic;
using System.Linq;

namespace BasicPlugin
{
  public class ValidateAccountName : IPlugin
  {
    //Invalid names from unsecure configuration
    private List<string> invalidNames = new List<string>();

    // Constructor to capture the unsecure configuration
    public ValidateAccountName(string unsecure)
    {
      // Parse the configuration data and set invalidNames
      if (!string.IsNullOrWhiteSpace(unsecure))
        unsecure.Split(',').ToList().ForEach(s =>
        {
          invalidNames.Add(s.Trim());
        });
    }
    public void Execute(IServiceProvider serviceProvider)
    {

      // Obtain the tracing service
      ITracingService tracingService =
      (ITracingService)serviceProvider.GetService(typeof(ITracingService));
      try
      {

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

        // Verify all the requirements for the step registration
        if (context.InputParameters.Contains("Target") && //Is a message with Target
            context.InputParameters["Target"] is Entity && //Target is an entity
            ((Entity)context.InputParameters["Target"]).LogicalName.Equals("account") && //Target is an account
            ((Entity)context.InputParameters["Target"])["name"] != null && //account name is passed
            context.MessageName.Equals("Update") && //Message is Update
            context.PreEntityImages["a"] != null && //PreEntityImage with alias 'a' included with step
            context.PreEntityImages["a"]["name"] != null) //account name included with PreEntityImage with step
        {
          // Obtain the target entity from the input parameters.  
          var entity = (Entity)context.InputParameters["Target"];
          var newAccountName = (string)entity["name"];
          var oldAccountName = (string)context.PreEntityImages["a"]["name"];

          if (invalidNames.Count > 0)
          {
            tracingService.Trace("ValidateAccountName: Testing for {0} invalid names:", invalidNames.Count);

            if (invalidNames.Contains(newAccountName.ToLower().Trim()))
            {
              tracingService.Trace("ValidateAccountName: new name '{0}' found in invalid names.", newAccountName);

              // Test whether the old name contained the new name
              if (!oldAccountName.ToLower().Contains(newAccountName.ToLower().Trim()))
              {
                tracingService.Trace("ValidateAccountName: new name '{0}' not found in '{1}'.", newAccountName, oldAccountName);

                string message = string.Format("You can't change the name of this account from '{0}' to '{1}'.", oldAccountName, newAccountName);

                throw new InvalidPluginExecutionException(message);
              }

              tracingService.Trace("ValidateAccountName: new name '{0}' found in old name '{1}'.", newAccountName, oldAccountName);
            }

            tracingService.Trace("ValidateAccountName: new name '{0}' not found in invalidNames.", newAccountName);
          }
          else
          {
            tracingService.Trace("ValidateAccountName: No invalid names passed in configuration.");
          }
        }
        else
        {
          tracingService.Trace("ValidateAccountName: The step for this plug-in is not configured correctly.");
        }
      }
      catch (Exception ex)
      {
        tracingService.Trace("BasicPlugin: {0}", ex.ToString());
        throw;
      }
    }
  }
}

Acerca del código

• Esta clase incluye un constructor para capturar la configuración no segura que se establece al configurar un paso.
• Esta clase requiere una configuración del paso específico para funcionar correctamente:
  • Actualizar mensaje
  • En la tabla de cuentas
  • Con el nombre de cuenta incluido en los atributos
  • Con PreEntityImage utilizando alias específico "a"
  • Con PreEntityImage incluidas las columnas de nombre.
• Si la configuración del paso no es correcta, el complemento escribe en el seguimiento que no está configurado correctamente.
• Si no define nombres no válidos en la configuración, el complemento registra en la traza que no se proporcionó ningún nombre no válido a la configuración.
• Si el nuevo nombre coincide con cualquiera de los nombres no válidos que estableció mediante la configuración y el nombre original no contiene el nuevo nombre, el complemento produce un InvalidPluginExecutionException con el mensaje que indica que no se permite esta operación.

Actualizar el registro de ensamblados de complementos

Ya ha registrado el ensamblado existente desde Tutorial: Escritura y registro de un complemento. Para agregar el nuevo complemento ValidateAccountName sin anular el registro del ensamblado existente, actualícelo.

1. Seleccione el Complemento básico (Ensamblado) y, a continuación, seleccione Actualizar.

   

2. En el cuadro de diálogo Actualizar ensamblado: Complemento básico, especifique la ubicación del ensamblado seleccionando los puntos suspensivos (…). El conjunto se carga.

   

3. Compruebe que el ensamblado y ambos complementos están seleccionados y seleccione Actualizar complementos seleccionados.

Configurar un nuevo paso

Configurar el complemento ValidateAccountName usando estas configuraciones:

Configuración	valor
Mensaje	Actualización
Entidad principal	cuenta
Atributos de filtro	nombre
Etapa de ejecución de la canalización de eventos	Prevalidación
Modo de ejecución	Sincrónico
Configuración no segura	prueba, foo, bar

Agregar una imagen

1. Haga clic con el botón secundario en el paso que acaba de registrar y seleccione Registrar nueva imagen.

   

2. En el diálogo Registrar nueva imagen, configure la imagen con estos valores:

   Configuración	valor
   Tipo de imagen	Imagen previa
   Nombre	cuenta
   Alias de la entidad	a
   Parámetros	nombre

   

3. Al registrar la imagen, la verá en la herramienta Registro de complementos.

   

Importante

El comportamiento predeterminado al crear una imagen de entidad es seleccionar todas las columnas. Sin embargo, esta selección puede reducir el rendimiento del servicio web. Incluya solo las columnas que necesita.

Probar el complemento

1. Abra la aplicación e intente actualizar un nombre de cuenta existente a test, foo, o bar.

2. Al intentar guardar, deberá ver el siguiente mensaje:

   

3. Si actualiza una cuenta existente con un nombre que incluya test, foo, o bar, y después actualiza la cuenta a test, foo, o bar no debería ver el mensaje.

Anular ensamblaje, complemento y paso

Use la herramienta Registro de complementos para anular el registro (eliminar) cualquier ensamblado, complemento o paso. Al eliminar un ensamblado, se eliminan todos los complementos y los pasos de ese ensamblado.