Entender o contexto de execução

O Pipeline de Execução de Eventos transmite aos plug-ins registrados uma grande quantidade de dados sobre a operação atual que está sendo processada e o ambiente de execução do código personalizado. As seções a seguir descrevem os dados passados para o plug-in ou a atividade de fluxo de trabalho personalizada.

Acesso ao contexto de execução para plug-ins

Com plug-ins, acesse esses dados em seu código definindo uma variável que implementa a IPluginExecutionContext interface:

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

Isso IPluginExecutionContext fornece algumas informações sobre o Stage para o qual o plug-in está registrado, bem como sobre o ParentContext.

Mais informações: ParentContext

Acesse o contexto de execução para atividades personalizadas de fluxo de trabalho

Com atividades personalizadas de fluxo de trabalho, acesse esses dados em seu código definindo uma variável que implementa a IWorkflowContext interface:

// Obtain the execution context using the GetExtension method.  
protected override void Execute(CodeActivityContext context)
{
 IWorkflowContext workflowContext = context.GetExtension<IWorkflowContext>();
...

Isso IWorkflowContext fornece algumas informações sobre o fluxo de trabalho dentro do qual a atividade de fluxo de trabalho personalizada está em execução.

ParentContext

O ParentContext fornece informações sobre qualquer operação que acione o plug-in ou a atividade de fluxo de trabalho personalizada a ser executada.

Com exceção de casos documentados específicos, evite depender dos valores encontrados na ParentContext para aplicar sua lógica de negócios. A ordem específica na qual as operações ocorrem não é garantida e pode ser alterada ao longo do tempo.

Se você optar por usar uma dependência dos valores encontrados no ParentContext, execute as etapas para garantir que seu código seja resiliente para se adaptar a possíveis alterações. Teste a lógica regularmente para verificar se as condições de que você depende permanecem em vigor ao longo do tempo.

Contexto de Execução

A IExecutionContext interface fornece o restante das informações. As IPluginExecutionContext classes e as IWorkflowContext classes implementam essa interface.

Para plug-ins, todas as propriedades dessa classe de contexto de execução fornecem informações úteis que talvez você precise acessar em seu código.

Duas das propriedades mais importantes são as InputParameters e as OutputParameters.

Outras propriedades usadas com frequência são SharedVariables, PreEntityImagese PostEntityImages.

ColeçõesDeParâmetros

Todas as propriedades do contexto de execução são somente leitura. Mas o InputParameters, OutputParameterse SharedVariables são ParameterCollection valores. Você pode alterar o comportamento da operação modificando os valores dos itens nessas coleções, dependendo do estágio no pipeline de execução de eventos para o qual o plug-in está registrado.

Os ParameterCollection valores são definidos como KeyValuePair estruturas. Para acessar uma propriedade, você precisa saber o nome da propriedade que a mensagem expõe. Por exemplo, para acessar a Entity propriedade passada como parte da CreateRequestpropriedade, você precisa saber que o nome dessa propriedade é Target. Em seguida, você pode acessar esse valor usando um código como este:

var entity = (Entity)context.InputParameters["Target"];

Use a documentação Microsoft.Xrm.Sdk.Messages e Microsoft.Crm.Sdk.Messages para conhecer os nomes das mensagens definidas nos assemblies do SDK. Para ações personalizadas, consulte os nomes dos parâmetros definidos no sistema.

Parâmetros de Entrada

O InputParameters representa o valor da propriedade OrganizationRequest.Parameters que representa a operação proveniente dos serviços Web.

Conforme descrito em Usar mensagens com o SDK para .NET, todas as operações que ocorrem no sistema são, em última análise, instâncias da OrganizationRequest classe que o IOrganizationServicemétodo .Execute processa.

Conforme descrito no Event Framework, as operações passam por uma série de estágios. Você pode registrar seu plug-in em estágios que ocorrem antes que os dados sejam gravados no banco de dados. Nos estágios PreValidation e PreOperation , você pode ler e alterar os valores do InputParameters para que possa controlar o resultado esperado da operação de dados.

Se você perceber que os valores na coleção InputParameters representam uma condição que não pode ser permitida, lance um InvalidPluginExecutionException (de preferência na fase de PreValidation) que cancele a operação e exiba um erro ao usuário usando um plug-in síncrono ou registre o erro se o plug-in for assíncrono. Para obter mais informações, consulte Cancelando uma operação.

ParâmetrosDeSaída

OutputParameters representa o valor da propriedade OrganizationResponse.Results, que representa o valor de retorno da operação. Cada uma das classes de resposta de mensagem derivadas de OrganizationResponse contém propriedades específicas. Para acessar essas propriedades, use o valor da chave que geralmente é o mesmo que o nome das propriedades na classe de resposta. No entanto, isso nem sempre é verdade. A tabela a seguir lista as propriedades da classe de resposta da mensagem que têm chaves diferentes do nome das propriedades.

O sistema não preenche o OutputParameters até após a transação de banco de dados, portanto, eles só estarão disponíveis para plug-ins registrados no estágio PostOperation. Se você quiser alterar os valores retornados pela operação, poderá modificá-los dentro do OutputParameters.

Variáveis compartilhadas

Use a propriedade SharedVariables para passar dados da interface de programação de aplicativos ou de um plug-in para uma etapa que ocorre posteriormente no fluxo de execução. Como essa propriedade é um ParameterCollection valor, os plug-ins podem adicionar, ler ou modificar propriedades para compartilhar dados com as etapas subsequentes.

O exemplo a seguir mostra como passar um PrimaryContact valor de um plug-in registrado para uma etapa Pré-Operação para uma etapa Pós-Operação.

public class PreOperation : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        // Obtain the execution context from the service provider.
        Microsoft.Xrm.Sdk.IPluginExecutionContext context = (Microsoft.Xrm.Sdk.IPluginExecutionContext)
            serviceProvider.GetService(typeof(Microsoft.Xrm.Sdk.IPluginExecutionContext));

        // Create or retrieve some data that will be needed by the post event
        // plug-in. You could run a query, create an entity, or perform a calculation.
        //In this sample, the data to be passed to the post plug-in is
        // represented by a GUID.
        Guid contact = new Guid("{74882D5C-381A-4863-A5B9-B8604615C2D0}");

        // Pass the data to the post event plug-in in an execution context shared
        // variable named PrimaryContact.
        context.SharedVariables.Add("PrimaryContact", (Object)contact.ToString());
    }
}

public class PostOperation : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        // Obtain the execution context from the service provider.
        Microsoft.Xrm.Sdk.IPluginExecutionContext context = (Microsoft.Xrm.Sdk.IPluginExecutionContext)
            serviceProvider.GetService(typeof(Microsoft.Xrm.Sdk.IPluginExecutionContext));

        // Obtain the contact from the execution context shared variables.
        if (context.SharedVariables.Contains("PrimaryContact"))
        {
            Guid contact =
                new Guid((string)context.SharedVariables["PrimaryContact"]);

            // Do something with the contact.
        }
    }
}

Passando uma variável compartilhada da API

Para introduzir uma variável compartilhada ao chamar uma API, use a palavra-chave tag da API Web ou do SDK para .NET para passar um valor de cadeia de caracteres.

Você pode acessar esse valor na coleção Variável Compartilhada usando a tag chave. Uma vez definido, você não pode alterar esse valor.

Para obter mais informações, consulte Adicionar uma variável compartilhada ao contexto de execução do plug-in.

Imagens de entidade

Quando você registra uma etapa para um plug-in que inclui uma tabela como um dos parâmetros, você pode especificar que uma cópia dos dados da tabela seja incluída como um instantâneo ou imagem usando as propriedades PreEntityImages e PostEntityImages.

Esses dados fornecem um ponto de comparação para os dados da tabela à medida que fluem pelo pipeline de eventos. Usar essas imagens fornece um desempenho muito melhor do que incluir código em um plug-in para recuperar uma tabela apenas para comparar os valores de atributo.

Quando você define uma imagem de entidade, especifica um valor de alias de entidade que pode ser usado para acessar a imagem específica. Por exemplo, se você definir uma imagem de pré-entidade com o alias 'a', poderá usar o código a seguir para acessar o valor do name atributo.

var oldAccountName = (string)context.PreEntityImages["a"]["name"];

Mais informações:

• Definir imagens de entidade
• Imagens de entidade para extensões de fluxo de trabalho

Consulte também

Estrutura de Eventos
Escrever um plug-in