Compartir vía


Tutorial: Actualizar un complemento

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

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

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

  1. 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.

  2. 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.

  1. Seleccione el (Ensamblado) Complemento básico y seleccione Actualizar.

    Seleccione Actualizar.

  2. 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á.

    Actualizar ensamblado: Diálogo complemento básico.

  3. 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

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

    Registrar nueva imagen.

  2. 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

    Cuadro de diálogo de registro de nueva imagen.

  3. Cuando la imagen esté registrada, la verá en la Plugin Registration Tool.

    La imagen registrada.

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

  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:

    Mensaje de error.

  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.

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.

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).