Tutorial: Atualizar um plug-in

Este tutorial é o terceiro de uma série que mostra como trabalhar com plug-ins.

• Tutorial: Escrever e registrar um plug-in
• Tutorial: Depurar um plug-in
• Tutorial: Atualizar um plug-in (este tutorial)

Para obter uma explicação detalhada dos conceitos relacionados e dos detalhes técnicos, consulte:

• Use plug-ins para estender processos corporativos
• Escrever um plug-in
• Registrar um plug-in
• Depuração de plug-ins

Goal

Este tutorial descreve tarefas comuns que você executa com plug-ins. Neste tutorial, você:

• Atualizar um conjunto de plug-in
• Criar e registrar um plug-in síncrono
• Usar dados de configuração no plug-in
• Gerar um erro para mostrar ao usuário
• Configurar e usar uma imagem de pré-entidade em seu código
• Desregistrar um assembly, um plug-in ou uma etapa

O objetivo deste tutorial é:

• Crie um plug-in síncrono registrado no estágio de pré-validação da mensagem de Atualização da tabela Conta.
• Avalie um conjunto de valores de string fornecidos como dados de configuração quando o plug-in for registrado.
• Se o nome da conta for alterado para um desses valores e o valor anterior não contiver o novo nome, cancele a operação e envie uma mensagem de erro de volta para o usuário.

Pré-requisitos

• Tutorial Completo: Gravar e registrar um plug-in.
• Tutorial: Depurar um plug-in é recomendado, mas não obrigatório.

Criar uma nova classe de plug-in

1. Em Visual Studio, adicione uma nova classe ao projeto BasicPlugin chamado ValidateAccountName.cs.

   Note

   Se você fizer uma alteração significativa em uma montagem, atualize a versão da montagem. Essa etapa é particularmente importante se você planeja atualizar um assembly que faz parte de uma solução gerenciada. A versão faz parte do nome totalmente qualificado do assembly, que é um identificador exclusivo do assembly. O processo de atualização da solução pode não reconhecer que o assembly foi alterado quando o nome totalmente qualificado do assembly não é alterado.

2. Adicione o código a seguir à classe e recompile o assembly.

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;
      }
    }
  }
}

Observações sobre o código

• Essa classe inclui um construtor para capturar a configuração não seguras que você define ao configurar uma etapa.
• Essa classe requer uma configuração de etapa específica para funcionar corretamente:
  • Atualizar mensagem
  • Na tabela de contas
  • Com o nome da conta incluído nos atributos
  • Com PreEntityImage usando o alias específico 'a'
  • Com PreEntityImage incluindo as colunas de nomes.
• Se a configuração da etapa não estiver correta, o plug-in gravará no rastreamento que ele não está configurado corretamente.
• Se você não definir nomes inválidos na configuração, o plug-in gravará no rastreamento que nenhum nome inválido foi passado para a configuração.
• Se o novo nome corresponder a qualquer um dos nomes inválidos definidos usando a configuração e o nome original não contiver o novo nome, o plug-in gerará uma InvalidPluginExecutionException mensagem com a mensagem de que essa operação não é permitida.

Atualizar o registro do conjunto do plug-in

Você já registrou o assembly existente no Tutorial: Gravar e registrar um plug-in. Para adicionar o novo plug-in ValidateAccountName sem cancelar o registro do assembly existente, atualize-o.

1. Selecione o (Assembly) Basic Plugin e selecione Atualizar.

   

2. Na caixa de diálogo Atualizar Assemblagem: Plug-in Básico, especifique o local da assemblagem selecionando as reticências (…). O conjunto é carregado.

   

3. Verifique se a montagem e ambos os plug-ins estão selecionados e selecione Atualizar plug-ins selecionados.

Configurar uma nova etapa

Configure o plug-in ValidateAccountName usando estas configurações:

Adicionar uma imagem

1. Clique com o botão direito do mouse na etapa que você acabou de registrar e selecione Registrar Nova Imagem.

   

2. Na caixa de diálogo Registrar Nova Imagem , defina a imagem com estas configurações:

   Setting	Value
   Tipo de imagem	Imagem anterior
   Nome	conta
   Nome alternativo da entidade	a
   Parameters	nome

   

3. Ao registrar a imagem, você a verá na ferramenta Registro de Plug-in.

   

Teste o plug-in

1. Abra o aplicativo e tente atualizar um nome de conta existente para test, fooou bar.

2. Ao tentar salvar, você deverá ver a seguinte mensagem:

   

3. Se você atualizar uma conta existente com um nome que inclua test, fooou bar, em seguida, atualizar a conta para test, fooou bar você não deve ver a mensagem.

Cancelar o registro de assembly, plug-in e etapa

Use a ferramenta de Registro de Plug-in para desregistrar (excluir) qualquer conjunto, plug-in ou etapa. Excluir um assembly exclui todos os plug-ins e etapas desse assembly.