Use the OrganizationServiceContext class

Applies To: Dynamics CRM 2013

In Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online, you can use the OrganizationServiceProxy class to access the Web services. Alternatively, you can use the OrganizationServiceContext generated by the code generation tool to gain access to additional functionality. The OrganizationServiceContext class lets you track changes, manage identities and relationships, and gives you access to the Microsoft Dynamics CRM LINQ provider. This class also contains a OrganizationServiceContext.SaveChanges method that you use to submit the changes to data that the context is tracking. This class is based on the same concept as the DataServiceContext class in Windows Communication Foundation (WCF) Data Services.

To generate this class, provide a value for the /serviceContextName parameter when you generate early bound types. The code generation tool uses this name as the name of the generated class. For more information about how to use the code generation tool, see Create early bound entity classes with the code generation tool (CrmSvcUtil.exe). You can use the organization service context when you develop applications, plug-ins, and workflow activities.

In This Topic

How to use the OrganizationServiceContext class

Track changes with the OrganizationServiceContext class

Track related objects with the OrganizationServiceContext class

Save changes with the OrganizationServiceContext class

Use virtual methods when the context is changed

How to use the OrganizationServiceContext class

To instantiate the context class, you must pass the class constructor an object that implements the IOrganizationService interface. One option is to pass an instance of the OrganizationServiceProxy class. For more information about the T:Microsoft.Xrm.Sdk.IorganizationService interface, see Use the IOrganizationService web service to read and write data or metadata.

The following code example shows how to create a new instance of the context class. In this example, the context class was named AdventureWorksCycleServiceContext by specifying the name using the /serviceContextName parameter on the code generation tool:

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

After you create the organization service context object, you can begin to track create, modify, or delete entities. For example, the following code example shows how to instantiate a new contact, and then save it to a Microsoft Dynamics CRM server by using the service context object.

//  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();

There are several points to note in the previous code example. First, after a new contact is instantiated, you pass that contact object to the OrganizationServiceContext.AddObject method so the context can begin tracking the object. The second point to note is that the new object is saved to the server by using the OrganizationServiceContext.SaveChanges method.

The organization service context must track any entity or relationship that you want to submit to Microsoft Dynamics CRM. For example, you could retrieve a record with a LINQ query and the context would track that entity or you could use the OrganizationServiceContext.Attach method to cause the context to begin tracking the entity. You can work with data in a client application and create new entities, create related entities, and modify existing entities, but you must call the SaveChanges method on tracked entities to commit changes to the Microsoft Dynamics CRM server.

Track changes with the OrganizationServiceContext class

To determine how an entity is tracked by the context, you can check the EntityState property on the entity instance. You must notify the organization service context to track an entity from Microsoft Dynamics CRM by calling various methods or by using a LINQ query. All entities returned from a .NET Language-Integrated Query (LINQ) query are tracked by the service context.

You can add objects to the service context by calling one of the following methods in OrganizationServiceContext.

Track related objects with the OrganizationServiceContext class

In CRM and CRM Online, the organization service context lets you create and update relationships between entities. The navigation properties generated by the CrmSvcUtil tool and located in the early-bound classes let you access and change related entity properties and relationships. The organization service context must be tracking the related entity for the related entity to be available to be updated on the server.

Use the following methods in OrganizationServiceContext to work with related entities and to add the entity to the service context:

Load related entities using navigation properties

Related entities for entities you have retrieved using LINQ will be null until you use LoadProperty to retrieve them. The following code sample shows how to access Task records associated with a specific Contact record.

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

Save changes with the OrganizationServiceContext class

The organization service context holds a graph of the entities it is tracking. The order in which the organization service context processes entity changes and submits them to the server is important. Updates to primary entity are processed, and then related entities are processed. If a value is set on the primary entity by the related entity, that value is used when updating data on the server.

If an error occurs when entity information is being saved, a new exception type that contains the SaveChangesResult is thrown by the OrganizationServiceContext.SaveChanges method, regardless of the value of the SaveChangesOptions parameter that is passed into the method.

Use virtual methods when the context is changed

Sometimes it may be necessary to take actions based on changes in the OrganizationServiceContext. To facilitate this, virtual methods are provided to allow you to intercept or be notified of an operation. To take advantage of these methods, you either have to derive from OrganizationServiceContext or change the generated organization service context.The following table lists the virtual methods.

See Also

T:Microsoft.Xrm.Sdk.IorganizationService
OrganizationServiceContext
Use the early bound entity classes in code
Sample: Complex LINQ queries
Create early bound entity classes with the code generation tool (CrmSvcUtil.exe)
Use the early-bound entity classes for create, update, and delete