xConnect Client API (C#)

Batching xConnect operations

Version:

You can submit operations to xConnect individually or in batches. Batching reduces the number of HTTP connections the client has to make, allowing the client to optimize calls to the xConnect service.

The size of a batch is determined by the point at which client.SubmitAsync() / client.Submit() is called - the xConnect Client API does not impose a default
xConnect is not transactional - operations within a batch fail or succeed independently, and the batch is not rolled back if one operation fails
If an operation depends on the success of another operation, such as successfully adding a contact before setting facets, the whole chain of operations will fail
The order in which operations are written does not matter; you can call client.SetFacet() before client.AddContact().

In the following example, 200 AddContactOperation operations and 200 SetFacetOperation operations are sent to xConnect in a single batch:

using Sitecore.XConnect;
using Sitecore.XConnect.Client;
using Sitecore.XConnect.Collection.Model;

namespace Documentation
{
    public class AddContactsInBatch
    {
        // Async Example
        public async void ExampleAsync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    for (int i = 1; i <= 200; i++)
                    {
                        // Adds an AddContactOperation operation to the batch
                        var contact = new Sitecore.XConnect.Contact();

                        client.SetFacet<PersonalInformation>(contact, new PersonalInformation() { FirstName = "Sample Contact" });
                        client.AddContact(contact); // Extension found in Sitecore.XConnect
                    }

                    // Submits the batch, which contains 400 operations
                    // 200 AddContactOperation
                    // 200 SetFacetOperation
                    await client.SubmitAsync();

                }
                catch (Sitecore.XConnect.XdbExecutionException ex)
                {
                    // Manage exception
                }
            }
        }

        // Sync example
        public void ExampleSync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    for (int i = 1; i <= 200; i++)
                    {
                        // Adds an AddContactOperation operation to the batch
                        var contact = new Sitecore.XConnect.Contact();

                        client.SetFacet<PersonalInformation>(contact, new PersonalInformation() { FirstName = "Sample Contact" });
                        client.AddContact(contact); // Extension found in Sitecore.XConnect
                    }

                    // Submits the batch, which contains 400 operations
                    // 200 AddContactOperation
                    // 200 SetFacetOperation
                    client.Submit();

                }
                catch (Sitecore.XConnect.XdbExecutionException ex)
                {
                    // Manage exception
                }
            }
        }
    }
}

Note

If you are building an application that relies on batching, it is recommended that you provide a way for an administrator to configure and tune the default batch size.

If you have suggestions for improving this article, let us know!