Reduce potential data loss using optimistic concurrency

 

Updated: November 29, 2016

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

On a multi-threaded and multi-user system like Microsoft Dynamics 365, operations and data changes often happen in parallel. A problem arises when two or more update or delete operations on the same piece of data happen at the same time. This situation could potentially result in data loss. Provided in this SDK release is the ability for your applications to detect whether an entity record has changed on the server in the time between when your application retrieved the record and when it tries to update or delete that record.

Optimistic concurrency is supported on all out-of-box entities enabled for offline sync and all custom entities. You can determine if an entity supports optimistic concurrency by retrieving the entity’s metadata through an SDK call, or by viewing the metadata using the Metadata Browser, and check if the attribute IsOptimisticConcurrencyEnabled is set to true. For custom entities, this property is set to true by default. To view the entity metadata for your organization, install the Metadata Browser solution described in Browse the metadata for your organization. You can also view the metadata for an uncustomized organization in the Excel file called EntityMetadata.xlsx included in the top-level folder of the SDK download.

You can enable optimistic concurrency checking behavior when executing an UpdateRequest by setting the ConcurrencyBehavior property of the request to IfRowVersionMatches. Similarly, for a DeleteRequest, you would set the ConcurrencyBehavior property.

When using the organization service context to make data changes, set ConcurrencyBehavior on the OrganizationServiceContext object. This value will be passed through to all of the UpdateRequest and DeleteRequest messages used by the OrganizationServiceContext when SaveChanges is called.

Optimistic concurrency behavior can only be set through an SDK call. There is presently no setting for it in a form of the Web application.

After retrieving an entity record, access the RowVersion attribute to obtain the current version of that record. In the entity object you use as the Target in the UpdateRequest, set the RowVersion property to the same value from the retrieved record and execute the request. Similarly, in the entity reference object you use as the Target in the DeleteRequest, set the RowVersion property to the same row version value from the retrieved record and execute the request.

If the entity passed to the UpdateRequest contains related entities, the same behavior is applied to all update operations using the row versions supplied with each individual entity.

When the request is received by the platform, a comparison of the current entity record row version and the row version in the request is performed. If the row versions match and ConcurrencyBehavior is set to IfRowVersionMatches, the operation succeeds. Otherwise, a fault exception is returned.

There are several error conditions that can be returned in a FaultException<OrganizationServiceFault> from the Web service call when using optimistic concurrency.

  • ConcurrencyVersionMismatch (code=-2147088254)

    When a row version is provided and the IfVersionMatches behavior is indicated, if the existing record’s version does not match the row version provided in the request, a fault is returned.

  • ConcurrencyVersionNotProvided (code= -2147088253

    When the IfVersionMatches behavior is indicated, and no value for row version is provided, a fault is returned.

  • OptimisticConcurrencyNotEnabled (code=-2147088243)

    When the IfVersionMatches behavior is indicated on an update to an entity, and where optimistic concurrency isn’t enabled, a fault is returned.

You can check the Code property of the returned fault to determine if the fault is related to optimistic concurrency. The codes for the error conditions that were shown previously were obtained from the ErrorCodes.cs helper code.

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright

Show: