Compreender o contexto de dados passado para um plug-in

 

Publicado: janeiro de 2017

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Quando um plug-in é executado em resposta a um evento de pipeline de execução para o qual esteja registrado, o método Execute de plug-in é chamado. Esse método transmite um objeto IServiceProvider como parâmetro, que contém alguns objetos úteis. As seções a seguir descrevem algumas das informações transmitidas a um plug-in quando executado.

Neste tópico

Acesse o contexto de execução do plug-in

Acesse o serviço da organização

Acesse o serviço de notificação

Parâmetros de entrada e saída

Imagens pré- e pós-entidade

Acesse o contexto de execução do plug-in

IPluginExecutionContext contém informações que descrevem o ambiente em tempo de execução que o plug-in executa, informações relacionadas ao pipeline de execução e as informações de entidade de negócios. O contexto do parâmetro está contido no System.IServiceProvider transmitido em tempo de execução para um plug-in, através do seu método Execute.

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

Quando um evento de sistema é acionado para o qual um plug-in está registrado, o sistema cria e preenche o contexto e o transmite para um plug-in através das classes e métodos mencionados anteriormente. O contexto de execução é transmitido para cada plug-in registrado no pipeline quando eles são executados. Cada plug-in no pipeline de execução é capaz de modificar as propriedades graváveis no contexto. Por exemplo, dado um plug-in registrado para um pré-evento e outro plug-in registrado para um pós-evento, o plug-in pós-evento pode receber um contexto que tenha sido modificado pelo plug-in pré-evento. A mesma situação aplica-se aos plug-ins registrados no mesmo estágio.

Todas as propriedades de IPluginExecutionContext são somente leitura. No entanto, o seu plug-in pode modificar o conteúdo das propriedades que sejam coleções. Para obter mais informações sobre a prevenção do loop infinito, consulte Depth.

Acesse o serviço da organização

Para acessar o serviço da organização Microsoft Dynamics 365, exige-se que o código de plug-in crie uma instância de serviço através do método ServiceProvider.GetService.

// Obtain the organization service reference.
IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

A plataforma fornece as URLs corretas de serviço Web e as credenciais de rede para você, quando usar esse método. Instanciar seu próprio proxy de serviço Web não é suportado, pois isso criará problemas de deadlock e autenticação.

Acesse o serviço de notificação

Os plug-ins síncronos registrados podem postar o contexto de execução no Barramento de Serviço do Microsoft Azure. O objeto de provedor de serviços transmitido para o plug-in contém uma referência ao IServiceEndpointNotificationService. É através desse serviço de notificação que os plug-ins síncronos podem enviar mensagens mediadas para um Barramento de Serviço do Microsoft Azure. Para obter mais informações sobre o Microsoft Azure, consulte Integração do Azure com o Microsoft Dynamics 365. Para obter mais informações sobre como gravar um plug-in que possa postar no Barramento de Serviço do Microsoft Azure, consulte Redigir um plug-in com reconhecimento de Azure personalizado.

Parâmetros de entrada e saída

A propriedade InputParameters contém os dados que estão na mensagem de solicitação sendo processada atualmente pelo pipeline de execução do evento. O seu código de plug-in pode acessar esses dados. A propriedade é do tipo ParameterCollection, em que as chaves para acessar os dados da solicitação são os nomes das propriedades públicas reais na solicitação. Como exemplo, observe CreateRequest. Uma propriedade de CreateRequest é chamada Target, que é o tipo Entity. Essa é a entidade que está sendo operada atualmente pela plataforma. Para acessar os dados da entidade, você usará o nome “Destino” como a chave no conjunto de parâmetros de entrada. Também é necessário converter a instância retornada.

// The InputParameters collection contains all the data passed in the message request.
if (context.InputParameters.Contains("Target") &&
    context.InputParameters["Target"] is Entity)
{
    // Obtain the target entity from the input parameters.
    Entity entity = (Entity)context.InputParameters["Target"];

Observe que nem todas as solicitações contêm uma propriedade Target que seja do tipo Entity, portanto é necessário olhar cada solicitação ou resposta. Por exemplo, DeleteRequest tem uma propriedade Target, mas o tipo é EntityReference. O exemplo do código anterior seria alterado da seguinte forma.

// The InputParameters collection contains all the data passed in the message request.
if (context.InputParameters.Contains("Target") &&    context.InputParameters["Target"] is EntityReference)
{
    // Obtain the target entity from the input parameters.
    EntityReference entity = (EntityReference)context.InputParameters["Target"];
}

Depois de ter acesso aos dados da entidade, você pode lê-los e modificá-los. Todas as alterações de dados feitas ao contexto e realizadas pelos plug-ins registrados no estágio 10 ou 20 do pipeline são transmitidas no contexto para a operação central no estágio 30.

Importante

Nem todos os campos de um registro de entidade que são passados para um plug-in por meio do contexto podem ser alterados. Você deve verificar a propriedade dos metadados do campo IsValidForUpdate para verificar se não estiver definido para false. A tentativa de alterar o valor de um campo que não pode ser atualizado resulta em uma exceção.

Da mesma forma, a propriedade OutputParameters contém os dados que estão na mensagem de resposta, por exemplo CreateResponse, transmitidos através do pipeline de execução do evento. No entanto, apenas os plug-ins registrados síncronos e assíncronos pós-evento têm OutputParameters preenchido, pois a resposta é o resultado da operação da plataforma central. A propriedade é do tipo ParameterCollection, em que as chaves para acessar os dados da resposta são os nomes das propriedades públicas reais na resposta.

Imagens pré- e pós-entidade

PreEntityImages e PostEntityImages contêm instantâneos dos atributos da entidade principal antes (pré) e depois (pós) da operação da plataforma principal. O Microsoft Dynamics 365 popula as imagens antes e depois da entidade com base nos privilégios de segurança do usuário do sistema não representado. Somente os atributos de entidade que são definidos como um valor ou são nulo estão disponíveis nas imagens antes ou depois da entidade. Você pode especificar para que a plataforma preencha essas propriedades PreEntityImages e PostEntityImages quando você registrar o seu plug-in. O valor do alias da entidade que você especificar durante o registro do plug-in é usado como a chave para a coleção de imagens no código do seu plug-in.

Há alguns eventos em que as imagens não estão disponíveis. Por exemplo, apenas os plug-ins pós-evento registrados síncronos e assíncronos têm PostEntityImages preenchido. A operação de criação não oferece suporte a uma imagem pré-imagem e uma operação de exclusão não suporta uma pós-imagem. Além disso, somente um pequeno subconjunto de mensagens suporta pré- e pós-imagens, conforme mostrado na tabela a seguir.

Solicitação de mensagem	Propriedade	Descrição
AssignRequest	Destino	A entidade atribuída.
CreateRequest	Destino	A entidade criada.
DeleteRequest	Destino	A entidade excluída.
DeliverIncomingEmailRequest	EmailId	O ID do e-mail entregue.
DeliverPromoteEmailRequest	EmailId	O ID do e-mail entregue.
ExecuteWorkflowRequest	Destino	A entidade de fluxo de trabalho.
MergeRequest	Destino	A entidade principal, em que os dados de entidade secundária estão sendo mesclados.
MergeRequest	SubordinateId	A entidade principal que está sendo mesclada à entidade secundária.
SendEmailRequest	EmailId	ID da entidade enviada.
SetStateRequest	EntityMoniker	A entidade para a qual o estado é definido.
UpdateRequest	Destino	A entidade atualizada.

Registrar-se para pré- ou pós-imagens para acessar os valores de atributo da entidade resulta em um desempenho melhor do plug-in, em comparação com a obtenção de atributos de entidade no código do plug-in através de solicitações RetrieveRequest ou RetrieveMultipleRequest.

Segurança Observação

Uma imagem anterior passada no contexto da execução para um plug-in ou atividade do fluxo de trabalho pode conter dados que o usuário conectado não tem privilégios para acessar. Os administradores Microsoft Dynamics 365 e outros usuários com permissões avançadas podem registrar plug-ins para execução na conta de usuário "sistema" ou o código de plug-in pode fazer chamadas como um usuário "sistema" em nome do usuário conectado. Se isso acontecer, os usuários conectados podem acessar os dados aos quais a sua segurança em nível de campo não permite acesso.Para obter mais informações:Representação em plug-ins

Confira Também

Desenvolvimento de plug-in
Lidar com exceção nos plug-ins
Pipeline de execução do evento
Usar mensagens (classes de solicitação e resposta) com o método Execute
Use o Serviço da organização para ler e gravar dados ou metadados
Registrar e implantar plug-ins

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais