Usar a classe OrganizationServiceContext

 

Publicado: janeiro de 2017

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

No Microsoft Dynamics 365 (online e local), você pode usar a classe de OrganizationServiceProxy para acessar os serviços Web. Como alternativa, você pode usar o OrganizationServiceContext gerado pela ferramenta de geração de código para obter acesso à funcionalidade adicional. A classe de OrganizationServiceContext permite que você acompanhe alterações, gerencie identidades e relacionamentos e dá acesso ao provedor LINQ da Microsoft Dynamics 365. Esta classe também contém um método OrganizationServiceContext.SaveChanges usado para enviar as alterações feitas nos dados que o contexto está acompanhando. Esta classe é baseada no mesmo conceito da classe DataServiceContext nos WCF (Windows Communication Foundation) Serviços de Dados.

Para gerar esta classe, forneça um valor para o parâmetro de /serviceContextName quando você pode gerenciar tipos associados precocemente. A ferramenta de geração de código usa esse nome como o nome da classe gerada. Para obter mais informações sobre como usar a ferramenta de geração de código, consulte Criar classes de entidade associadas precocemente com a ferramenta de geração de código (CrmSvcUtil.exe). Você pode usar o contexto de serviço da organização ao desenvolver aplicativos, plug-ins e atividades de fluxo de trabalho.

Neste tópico

Como usar a classe de OrganizationServiceContext

Acompanhe alterações com a classe de OrganizationServiceContext

Acompanhar objetos relacionados à classe de OrganizationServiceContext

Salvar alterações com a classe OrganizationServiceContext

Use métodos virtuais quando o contexto for alterado

Como usar a classe de OrganizationServiceContext

Para instanciar a classe de contexto, você deve passar para o construtor de classe um objeto que implemente a interfaceIOrganizationService. Uma opção é passar uma instância da classe OrganizationServiceProxy. Para obter mais informações sobre a interface IOrganizationService, consulte Use o Serviço da organização para ler e gravar dados ou metadados.

O seguinte exemplo de código mostra como criar uma nova instância da classe de contexto. Neste exemplo, a classe de contexto foi nomeada AdventureWorksCycleServiceContext ao especificar o nome usando o parâmetro /serviceContextName na ferramenta de geração de código:

//For early bound types to work correctly, they have to be enabled on the proxy.
_serviceProxy.EnableProxyTypes();
AdventureWorksCycleServiceContext context = new AdventureWorksCycleServiceContext(_serviceProxy);

Depois de criar o objeto de contexto de serviço da organização, você pode começar a acompanhar as entidades criar, modificar ou excluir. Por exemplo, o exemplo de código a seguir mostra como criar instanciar um novo contato e depois salvá-lo em um servidor de Microsoft Dynamics 365 usando o objeto de contexto de serviço.

//  Create a new contact record;
AdventureWorksCycleServiceContext context = new AdventureWorksCycleServiceContext (_serviceProxy);
Contact contact = new Contact() 
 {
   FirstName = "Pamela",
   LastName = "Brown",
   Address1_Line1 = "123 Easy St.",
   Address1_City = "Atlanta",
   Address1_StateOrProvince = "GA",
   Address1_PostalCode = "32254",
   Telephone1 = "425-555-5678"   };
context.AddObject(contact);
context.SaveChanges();

Há vários pontos para observar no exemplo de código anterior. Primeiro, depois que um novo contato é instanciado, você passa esse objeto de contato para o método OrganizationServiceContext. o método deAddObject para que o contexto possa começar a acompanhar o objeto. O segundo ponto para observar é que o novo objeto é salvo no servidor usando o métodoOrganizationServiceContextSaveChanges.

O contexto de serviço da organização deve acompanhar todas as entidades ou relacionamento que você desejar enviar a Microsoft Dynamics 365. Por exemplo, você poderia recuperar um registro com uma consulta LINQ e o contexto acompanharia aquela entidade ou você poderia usar o método OrganizationServiceContext.Attach para fazer com que o contexto comece a acompanhar a entidade. Você pode trabalhar com dados em um aplicativo de cliente e criar novas entidades, criar entidades relacionadas e modificar entidades existentes, mas você deve solicitar o método SaveChanges em entidades acompanhadas para confirmar as alterações no servidor do Microsoft Dynamics 365.

Acompanhe alterações com a classe de OrganizationServiceContext

Para determinar como uma entidade é acompanhada pelo contexto, você pode verificar a propriedade de EntityState na instância de entidade. Você deve notificar o contexto de serviço da organização para acompanhar uma entidade de Microsoft Dynamics 365 solicitando vários métodos ou usando uma consulta LINQ. Todas as entidades retornadas de uma pesquisa .NET LINQ (Language-Integrated Query) são acompanhadas pelo contexto de serviço.

Você pode adicionar objetos ao contexto de serviço solicitando um dos seguintes métodos no OrganizationServiceContext.

Método	Usar
AddObject	Adicionar uma entidade para o conjunto de entidades que o contexto de serviço da organização está acompanhando. O status da entidade no contexto está definido como Created. Se o método de SaveChanges for solicitado, este registro será criado ou adicionado ao servidor.
Attach	Adicionar uma entidade para o conjunto de entidades que o contexto de serviço da organização está acompanhando. O status da entidade no contexto está definido como Unchanged. Se o método de SaveChanges for solicitado, essa entidade não será enviada ao servidor a menos que o status seja alterado.
CreateQuery	Adicionar os resultados de uma consulta para o conjunto de entidades que o contexto de serviço da organização está acompanhando.

Acompanhar objetos relacionados à classe de OrganizationServiceContext

Em Dynamics 365 e Dynamics 365 (online), o contexto de serviço da organização permite criar e atualizar os relacionamentos entre entidades. As propriedades de navegação geradas pela ferramenta CrmSvcUtil e localizadas nas classes associadas precocemente permitem acessar e modificar propriedades e relacionamentos de entidades relacionadas. O contexto de serviço da organização deve acompanhar a entidade relacionada para que a entidade relacionada esteja disponível para ser atualizada no servidor.

Use os seguintes métodos no OrganizationServiceContext para trabalhar com entidades relacionadas e adicione a entidade ao contexto do serviço:

Método	Usar
AddRelatedObject	Adicione o destino ao contexto. Solicite o método Attach na entidade de destino e depois solicite o método AddLink entre a entidade de origem e a entidade de destino (relacionada).
AttachLink	Adicionar a entidade relacionada ao contexto para acompanhamento. O status da entidade no contexto está definido como Unchanged.
AddLink	Criar um relacionamento entre entidades de origem e de destino. Adicione o destino ao contexto. O status da entidade de destino no contexto está definido como Created.
LoadProperty	Carregar o conjunto da a entidade relacionada para relacionamentos especificados. Dar acesso às entidades relacionadas usando a propriedade de navegação. Solicitar o método AddObject na entidade relacionada após acessar a entidade usando uma propriedade de navegação na entidade primária.
UpdateObject	Alterar o estado da entidade especificada no OrganizationServiceContext para Alterado.
DeleteObject	Alterar o estado da entidade especificada a ser excluída no OrganizationServiceContext.

Carregar entidades relacionadas usando propriedades de navegação

Entidades relacionadas a entidades que você recuperou usando LINQ serão nulas até que você use o LoadProperty para recuperá-las. O exemplo de código a seguir mostra como acessar os registros de tarefa associados a um determinado registro de contato.

Contact pam = context.ContactSet.Where(c => c.FirstName == "Pamela").FirstOrDefault();
if (pam != null)
{
// pam.Contact_Tasks is null until you use LoadProperty
    context.LoadProperty(pam, "Contact_Tasks");
    Task firstTask = pam.Contact_Tasks.FirstOrDefault();
}

Salvar alterações com a classe OrganizationServiceContext

O contexto de serviço da organização mantém um gráfico das entidades que está acompanhando. A ordem em que o contexto de serviço da organização processa as alterações de entidade e as envia ao servidor é importante. Atualizações na entidade primária são processadas e então as entidades relacionadas são processadas. Se um valor for definido na entidade primária pela entidade relacionada, esse valor é usado ao atualizar dados no servidor.

Se ocorrer um erro quando informações de entidade estiverem sendo salva, um novo tipo de exceção que contenha o SaveChangesResult é lançado pelo método OrganizationServiceContext.SaveChanges, independentemente do valor do parâmetro de SaveChangesOptions que é passado no método.

Use métodos virtuais quando o contexto for alterado

Às vezes, pode ser necessário realizar ações com base nas alterações no OrganizationServiceContext. Para facilitar isso, os métodos virtuais são fornecidos para que você possa interceptar ou ser notificado sobre uma operação. Para tirar proveito desses métodos, é preciso derivar-se de OrganizationServiceContext ou alterar o contexto de serviço da organização gerado. A tabela a seguir lista os métodos virtuais.

Método	Descrição
OnBeginEntityTracking	Solicitada depois de uma entidade, é anexada ao OrganizationServiceContext.
OnBeginLinkTracking	Solicitada depois de um link, é anexada ao OrganizationServiceContext.
OnEndEntityTracking	Solicitada depois de uma entidade, é desanexada do OrganizationServiceContext.
OnEndLinkTracking	Solicitada depois de um link, é desanexada do OrganizationServiceContext.
OnExecuting	Solicitada imediatamente após uma solicitação é enviada ao Servidor do Microsoft Dynamics 365.
OnExecute	Solicitada imediatamente após uma solicitação é enviada ao Servidor do Microsoft Dynamics 365, não importando se uma exceção ocorreu ou não.
OnSavingChanges	Solicitada antes de quaisquer operações, acontece após uma solicitação para SaveChanges.
OnSaveChanges	Solicitada quando todas as operações de uma solicitação para SaveChanges forem completas ou quando houver uma falha.

Confira Também

IOrganizationService
OrganizationServiceContext
Use classes de entidade de limite antecipado no código
Exemplo: Consultas de LINQ complexas
Criar classes de entidade associadas precocemente com a ferramenta de geração de código (CrmSvcUtil.exe)
Usar as classes de entidade associadas precocemente para criar, atualizar e excluir

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais