RetrieveEntityChangesRequest Class

Definition

public ref class RetrieveEntityChangesRequest sealed : Microsoft::Xrm::Sdk::OrganizationRequest

[System.Runtime.Serialization.DataContract(Namespace="http://schemas.microsoft.com/xrm/2011/Contracts")]
public sealed class RetrieveEntityChangesRequest : Microsoft.Xrm.Sdk.OrganizationRequest

[<System.Runtime.Serialization.DataContract(Namespace="http://schemas.microsoft.com/xrm/2011/Contracts")>]
type RetrieveEntityChangesRequest = class
    inherit OrganizationRequest

Public NotInheritable Class RetrieveEntityChangesRequest
Inherits OrganizationRequest

Inheritance

Object

OrganizationRequest

RetrieveEntityChangesRequest

Attributes

DataContractAttribute

Examples

The following example shows how to use this message. For this sample to work correctly, you must be connected to the server to get an IOrganizationService interface instance.

The RetrieveEntityChangesExample method demonstrates using this message. For a complete sample, see Sample: Synchronize data with external systems using change tracking on GitHub.

/// <summary>
/// Demonstrates use of RetrieveEntityChanges
/// </summary>
/// <param name="service">Authenticated IOrganizationService instance</param>
static void RetrieveEntityChangesExample(IOrganizationService service)
{
    // Create an account record:
    var account = new Entity("account") { 
        Attributes =
        {
            {"name","Test account" },
            {"numberofemployees", 10 }
        }
    };

    Guid accountId = service.Create(account);

    // First retrieval of account records
    RetrieveEntityChangesRequest request = new()
    {
        EntityName = "account",
        Columns = new ColumnSet("name", "numberofemployees"),
        PageInfo = new PagingInfo()
        {
            Count = 5000,
            PageNumber = 1,
            ReturnTotalRecordCount = false
        }
    };

    //send the first request
    var response = (RetrieveEntityChangesResponse)service.Execute(request);

    // Capture the timestamp from the response
    string timeStamp = response.EntityChanges.DataToken;

    //Output the changes
    Console.WriteLine("Results of first request:");
    OutputChanges(response.EntityChanges.Changes);

    // Update the request with previous response timestamp
    request.DataVersion = timeStamp;

    //Delete the account record to cause a change.
    service.Delete("account", accountId);

    // Send the request again
    response = (RetrieveEntityChangesResponse)service.Execute(request);

    //Output the changes from the second request
    Console.WriteLine("Results of second request:");
    OutputChanges(response.EntityChanges.Changes);

    // Writes the first 5 changes to the console
    void OutputChanges(BusinessEntityChangesCollection changes)
    {
        if (changes.Count > 0)
        {
            // Only output the first 5 records
            foreach (var change in changes.Take(5))
            {
                switch (change.Type)
                {
                    case ChangeType.NewOrUpdated:

                        Entity newOrUpdated = ((NewOrUpdatedItem)change).NewOrUpdatedEntity;

                        Console.WriteLine($"\tNew or updated ID:{newOrUpdated.Id}");
                        Console.WriteLine($"\t\tname:{newOrUpdated.GetAttributeValue<string>("name")}");
                        Console.WriteLine($"\t\tnumberofemployees:{newOrUpdated.GetAttributeValue<int>("numberofemployees")}");
                        Console.WriteLine();
                        break;

                    case ChangeType.RemoveOrDeleted:

                        EntityReference removeOrDeleted = ((RemovedOrDeletedItem)change).RemovedItem;

                        Console.WriteLine($"\tRemove or Deleted ID:{removeOrDeleted.Id}");
                        Console.WriteLine();
                        break;
                }
            }
        }
        else
        {
            Console.WriteLine("No changes since previous request");
        }
    }
}

Remarks

Usage

Pass an instance of this class to the Execute(OrganizationRequest) method, which returns an instance of RetrieveEntityChangesResponse.

Privileges and Access Rights

To perform this action, the caller must have organization level read access to the table. If the user has limited read access, the system throws a privilege check error.

Notes for Callers

This message only works with tables that have EntityMetadata.ChangeTrackingEnabled property set to true.

The first time you use this message, all records for the table is returned and that data can be used to populate the external storage. The RetrieveEntityChangesResponse.EntityChanges returns a BusinessEntityChanges that includes a DataToken property that is a version number to use with the next use of the RetrieveEntityChanges message so that only data for those changes that occurred since that version will be returned.

Learn to use change tracking to synchronize data with external systems

Sample code on GitHub

Synchronize data with external systems using change tracking

Constructors

Properties

Applies to