Use the OrganizationServiceContext class
Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
In Microsoft Dynamics 365 (online & on-premises), 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 365 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 IOrganizationService interface, see Use the Organization 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 365 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 365. 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 365 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 365 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.
Method |
Use |
|---|---|
Adds an entity to the set of entities the organization service context is tracking. The status of the entity in the context is set to Created. If the SaveChanges method is called, this record will be created or added to the server. |
|
Adds an entity to the set of entities the organization service context is tracking. The status of the entity in the context is set to Unchanged. If the SaveChanges method is called, this entity will not be sent to the server unless its status changes. |
|
Adds the results of a query to the set of entities the organization service context is tracking. |
Track related objects with the OrganizationServiceContext class
In Dynamics 365 and Dynamics 365 (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:
Method |
Use |
|---|---|
Adds the target to the context. Calls the Attach method on the target entity and then calls the AddLink method between the source entity and the target (related) entity. |
|
Adds the related entity to the context for tracking. The status of the entity in the context is set to Unchanged. |
|
Creates a relationship between the source and target entities. Adds the target to the context. The status of the target entity in the context is set to Created. |
|
Loads the related entity set for the specified relationship. Gives access to related entities by using the navigation property. Call the AddObject method on the related entity after you have accessed the entity by using a navigation property on the parent entity. |
|
Changes the state of the specified entity in the OrganizationServiceContext to Modified. |
|
Changes the state of the specified entity to be deleted in the OrganizationServiceContext. |
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.
Method |
Description |
|---|---|
Called after an entity is attached to the OrganizationServiceContext. |
|
Called after a link is attached to the OrganizationServiceContext. |
|
Called after an entity is detached from the OrganizationServiceContext. |
|
Called after a link is detached from the OrganizationServiceContext. |
|
Called immediately before a request is submitted to the Microsoft Dynamics 365 Server. |
|
Called immediately after a request is submitted to the Microsoft Dynamics 365 Server, regardless of whether an exception occurred or not. |
|
Called before any operations occur after a call to SaveChanges. |
|
Called when all of the operations for a call to SaveChanges have completed, or when there is a failure. |
See Also
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
Microsoft Dynamics 365
© 2016 Microsoft. All rights reserved. Copyright