xConnect Client API overview

The xConnect Client API is a portable web API that allows trusted clients to create, read, update, and search contacts and interactions over HTTPS. The xConnect Client API implements the oData protocol. The following example demonstrates how to retrieve an instance of the client in a Sitecore context and add a single contact:

using System;
using System.Threading.Tasks;
using Sitecore.XConnect;

namespace Documentation
{
    public class GetContact
    {
        // Async example
        public async void ExampleAsync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    var reference = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));

                    Task<Sitecore.XConnect.Contact> contactTask = client.GetAsync<Sitecore.XConnect.Contact>(reference, new Sitecore.XConnect.ContactExpandOptions() { });

                    Contact contact = await contactTask;
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }
    }
}

The xConnect Client API is the only way to work with experience data. You cannot access the collection database or search index directly, and you should not use the ContactRepository and ContactManager classes in a non-tracking context.

Note

The xConnect Client API does not replace the tracker. However, the tracker relies on the xConnect Client API to read and write data. Refer to the web tracking documentation for more information about to track contacts during a web session.

Asynchronous and synchronous extension methods

The xConnect Client API has is asynchronous, but there are synchronous versions of most extension methods available in Sitecore.XConnect.Client.XConnectSynchronousExtensions.

Async Sync Notes
GetAsync Get  
SubmitAsync Submit Synhronous submit does not have a timeout overload.
GetBatchEnumerator GetBatchEnumeratorSync  
ToSearchResults N/A A synchronous version of this extension is not currently available.
InitializeAsync Initialize  

Methods without a synchronous extension

Do not call .Wait(), .Result, ConfigureAwait(false).GetAwaiter().GetResult(), or similar on tasks returned from the async API. If there is no synchronous extension method, use the SuspendContextLock() method around the asynchronous call:

Sitecore.XConnect.Client.XConnectSynchronousExtensions.SuspendContextLock(client.Contacts.Where(c => c.Identifiers.Any(t => t.IdentifierType == Sitecore.XConnect.ContactIdentifierType.Known)).Count);

Examples of extension methods that do not have a synchronous counterpart include:

  • .FirstOrDefault()
  • .First()
  • .Single()
  • .SingleOrDefault()
  • .Count

Anticipating exceptions

The xConnect Client API will throw an exception if one or more operations fails. Wrap usage of the xConnect Client API in a try/catch statement and catch the XdbExecutionException.

using (XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
{
        try
        {
            // GET or POST some data
        }
        catch (XdbExecutionException ex)
        {
            // Do something
        }
}

Read more about exceptions and error handling in xConnect.

Batching operations

The xConnect Client API supports batching. Batches of operations are serialized, sent to xConnect over HTTPS, and deserialized by the xConnect service layer. In the following example, the .AddContact extension method is used to add two AddContactOperation operations to the client before submitting both operations in a single batch:

Consider the following example:

var firstContact = new Contact();
client.AddContact(firstContact);

var secondContact = new Contact();
client.AddContact(secondContact);

await client.SubmitAsync();

See also: