RetrieveEntityChangesRequest Class

Definition

Namespace:

Microsoft.Xrm.Sdk.Messages

Assembly:

Microsoft.Xrm.Sdk.dll

Package:

Microsoft.PowerPlatform.Dataverse.Client v1.1.22

Contains data that is needed to retrieve the changes for an record.

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

RetrieveEntityChangesRequest()

Initializes a new instance of the RetrieveEntityChangesRequest class.

Properties

Columns	Gets or sets the columns to retrieve.
DataVersion	Gets or sets the data version.
EntityName	Gets or sets the table logical name.
ExtensionData	Gets or sets the structure that contains extra data. Optional. (Inherited from OrganizationRequest)
GetGlobalMetadataVersion	Gets or sets a boolean value that specifies whether metadata version is to be returned. Optional.
Item[String]	Gets or sets the indexer for the Parameters collection. (Inherited from OrganizationRequest)
PageInfo	Gets or sets the paging information.
Parameters	Gets or sets the collection of parameters for the request. Required, but is supplied by derived classes. (Inherited from OrganizationRequest)
RequestId	Gets or sets the ID of the request. Optional. (Inherited from OrganizationRequest)
RequestName	Gets or sets the name of the request. Required, but is supplied by derived classes. (Inherited from OrganizationRequest)