Contexto de execução do plug-in
Sempre que um plug-in (ou extensão de fluxo de trabalho personalizado) é executado, uma infinidade de dados é disponibilizada pelo Microsoft Dataverse, que contém informações sobre o contexto no qual a operação atual reside. Os dois plug-ins e os conjuntos de fluxos de trabalho personalizados têm acesso a uma classe de IWorkflowContext, que pode ser acessada por diferentes métodos.
Em plug-ins, o IPluginExecutionContext pode ser acessado por meio do parâmetro IServiceProvider do método Execute chamando o método GetService.
public class SamplePlugin : IPlugin
{
public void Execute(IServiceProvider serviceProvider)
{
// Obtain the execution context from the service provider.
IPluginExecutionContext context = (IPluginExecutionContext)
serviceProvider.GetService(typeof(IPluginExecutionContext));
}
}
Em extensões de fluxo de trabalho personalizadas, o IPluginExecutionContext é passado como um parâmetro do método Execute do tipo CodeActivityContext.
public class SampleWorkflowExtension : CodeActivity
{
protected override void Execute(CodeActivityContext context)
{
// Obtain the execution context from the code activity context.
IWorkflowContext workflowContext = context.GetExtension();
}
}
Tanto IPluginExecutionContext como IWorkflowContext implementam a interface IExecutionContext. Cada um também expõe informações específicas ao seu tipo. Para obter mais informações, consulte Compreender o contexto de execução.
Propriedades de IExecutionContext
Duas das propriedades mais notáveis da interface IExecutionContext são InputParameters e OutputParameters. Outras propriedades usadas com frequência são PreEntityImages, PostEntityImages e SharedVariables.
InputParameters
InputParameters estão contidos na coleção InputParameters do contexto de execução e são do tipo Entity. Esta propriedade permite que você veja quais valores de entidade foram apresentados ao plug-in antes da implementação de uma determinada operação.
Por exemplo, se você deseja validar os dados e evitar que eles sejam salvos se a validação não for bem-sucedida, as etapas a serem executadas serão semelhantes às seguintes:
Registre seu plug-in para ser executado no estágio de Pré-Validação em Criação e/ou Atualização da entidade que deseja validar.
Valide os dados no plug-in lendo os valores da coleção InputParameters. Em Criar, você deseja recuperar a coleção Destino.
Lançar um InvalidPluginExecutionException se os dados fornecidos não forem válidos.
Ou talvez você queira atualizar os valores em sua entidade (como retirar caracteres especiais de um número de telefone) antes que os dados sejam salvos. Você pode lidar com essa situação com as seguintes etapas:
Registre seu plug-in para ser executado no estágio de Pré-Operação em Criação e/ou Atualização da entidade que deseja atualizar.
Atualize os dados no plug-in editando os valores da coleção InputParameters. Em Criar, você deseja recuperar a coleção Destino.
OutputParameters
Os parâmetros de saída estão contidos na coleção OutputParameters do contexto de execução e são do tipo Entidade. Os parâmetros de saída só são fornecidos depois que a operação especificada tiver ocorrido. Dessa forma, você só poderá usar essa coleção quando estiver manipulando eventos na fase PostOperation.
Por exemplo, se deseja alterar os valores retornados pela operação, poderá modificá-los executando as seguintes etapas:
Registre seu plug-in para ser executado na fase de PostOperation na Criação e/ou Atualização da entidade que deseja atualizar.
Atualize os dados no plug-in editando os valores da coleção OutputParameters. Em Criar, você deseja recuperar a coleção Destino.
PreEntityImages e PostEntityImages
Ao registrar plug-ins para serem executados na estrutura de eventos, é possível fornecer uma cópia ou um instantâneo imutável dos dados. Isso é ideal, especialmente quando você precisa fazer referência a valores dos dados antes ou depois de uma operação ter ocorrido, por exemplo, para o registro ou a auditoria personalizada.
Embora seja possível recuperar os valores da entidade usando o Contexto da Organização em um plug-in por meio de uma solicitação de Recuperação, o uso de imagens da entidade para realizar essa tarefa é muito mais eficiente e altamente recomendado.
SharedVariables
As variáveis compartilhadas permitem configurar dados que podem ser passados de um plug-in para uma etapa que ocorre posteriormente no pipeline de implementação. Embora seja altamente recomendável configurar plug-ins para não ter estado ou nenhuma dependência de eventos externos, às vezes há exceções a essa regra.
Uma exceção pode ser quando você deseja garantir que não tenha nenhum plug-in “descontrolado” em seu ambiente. Ou seja, eles estão sendo ativados em um cenário de recursão infinita. Também é possível usar o contexto de execução para determinar a profundidade em que seu plug-in está sendo executado atualmente, mas em determinadas situações, pode ser apropriado rastrear manualmente. Por exemplo, talvez seu plug-in esteja iniciando erroneamente a lógica de atualização em um plug-in configurado para ser executado na atualização da entidade, o que, por sua vez, está causando sua execução infinita. Para solucionar isso, é possível criar um padrão para contar o número de vezes que esse plug-in pode ser executado. Um exemplo seria configurar um limite de cinco execuções de um plug-in com as seguintes etapas:
No plug-in, verifique se a variável compartilhada RunCount existe e, caso não exista, crie uma que seja inicializada com zero.
Verifique se o valor da variável de RunCount é maior que cinco e, se for, lance um InvalidPluginExecutionException.
No final do plug-in, aumente a variável de RunCount em 1.
Observação
Esta é apenas uma proteção extra contra um bug que acidentalmente faz com que os plug-ins sobrecarreguem os recursos. Verifique se você está criando seus plug-ins de forma que esse cenário não ocorra. O Dataverse também fornece proteções para evitar plug-ins "descontrolados" como esses, mas os métodos de recuperação consomem muito mais recursos do que esse método e são mais difíceis de diagnosticar.