Tutorial: Actualizar un complemento

Artículo
02/23/2023

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

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

Para una explicación detallada de los conceptos relacionados y la información técnica, consulte:

Objetivo

Este tutorial describirá acciones comunes adicionales que realizará con los complementos. En este tutorial usted realizará lo siguiente:

Actualizar un ensamblado de complementos
Crear y registrar un complemento sincrónico
Usar los datos de configuración en el complemento
Lanzar un error para mostrar al usuario
Configurar y usar una imagen previa de la entidad en el código
Anular el registro y 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.
El complemento evaluará 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

Completar Tutorial: Escribir y registrar un complemento
Tutorial: Se recomienda depurar un complemento pero no es obligatorio.

Nota

Puesto que muchos pasos básicos se describen en detalle en Tutorial: Escribir y registrar un complemento, no se incluye el mismo nivel de detalle para los mismos pasos en este tutorial.

Crear una nueva clase de complemento

En Visual Studio, agregue una nueva tipo al proyecto BasicPlugin llamado ValidateAccountName.cs

Nota

Cuando realiza un cambio significativo en un ensamblado, debe actualizar la versión del ensamblado. Esto es particularmente importante si tiene la intención de actualizar un ensamblado que es parte de un solución administrada. La versión es 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 ha cambiado cuando el nombre completo del ensamblado no ha cambiado.
Agregue el siguiente código a la clase y vuelva a crear 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 establecerá 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 solo escribirá en el seguimiento que no está configurado correctamente
Si no se establecen nombres no válidos en la configuración, el complemento escribirá únicamente en el seguimiento que no se pasaron nombres no válidos a la configuración
Si el nuevo nombre coincide con alguno de los nombres no válidos establecidos usando la configuración Y el nombre original no contiene el nuevo nombre, se producirá una InvalidPluginExecutionException con el mensaje al usuario de que esta operación no está permitida.

Actualizar el registro de ensamblados de complementos

El ensamblado existente de Tutorial: Escribir y registrar un complemento ya debe estar registrado. Para agregar el nuevo complemento ValidateAccountName sin registrar el ensamblado existente, deberá actualizarlo.

Seleccione el (Ensamblado) Complemento básico y seleccione Actualizar.
En el diálogo Actualizar un ensamblado: Complemento básico, especifique la ubicación del ensamblado haciendo clic en los puntos suspensivos (…) y el ensamblado se cargará.
Compruebe que el ensamblado y ambos complementos están seleccionados y haga clic en Actualizar complementos seleccionados.

Configurar un nuevo paso

Configurar el complemento ValidateAccountName usando estas configuraciones:

Configuración	valor
Mensaje	Actualización
Entidad principal	account
Atributos de filtro	nombre
Fase de canalización de eventos de ejecución	PreValidation
Modo de ejecución	Sincrónico
Configuración no segura	test, foo, bar

Registrar nuevo paso.

Agregar una imagen

Haga clic con el botón secundario en el paso que acaba de registrar y seleccione Registrar nueva imagen.
En el diálogo Registrar nueva imagen, configure la imagen con estos valores:

Configuración Value

Tipo de imagen Imagen previa

Nombre account

Alias de entidad a.m.

Parámetros nombre
Cuando la imagen esté registrada, la verá en la Plugin Registration Tool.

Configuración	Value
Tipo de imagen	Imagen previa
Nombre	account
Alias de entidad	a.m.
Parámetros	nombre

Importante

El comportamiento predeterminado al crear una imagen de entidad es seleccionar todas las columnas. Sin embargo, esto puede resultar en una reducción del rendimiento del servicio web. Los desarrolladores solo deben incluir aquellas columnas que son obligatorias.

Probar el complemento

Abra la aplicación e intente actualizar un nombre de cuenta existente a test, foo, o bar.
Al intentar guardar, deberá ver el siguiente mensaje:
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.

Anule el registro del ensamblado, complemento, y paso

Use la Plugin Registration Tool para Anular el registro (eliminar) cualquier ensamblado, complemento o paso. La eliminación de un ensamblado eliminarán todos los complementos y pasos para ese complemento.

anular el registro de un ensamblado.