xConnect Client API (C#)

xConnect Client API overview

Version:

The xConnect Client API is a portable C# library that allows trusted clients to create, read, update, and search contacts and interactions over HTTPS. The following example demonstrates how to retrieve an xConnect client in a Sitecore context and retrieve a single contact by ID:

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
                }
            }
        }
    }
}

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 is asynchronous, but there are synchronous versions of most extension methods available in the Sitecore.XConnect.Client.XConnectSynchronousExtensions extension methods class:

Asynchronous method	Synchronous method	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

If there is no synchronous version of a method, use the SuspendContextLock() method around the asynchronous call as shown in the following example:

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

Important

Do not call .Wait(), .Result, ConfigureAwait(false).GetAwaiter().GetResult(), or similar on tasks returned from the async API.

The following extension methods do not have a synchronous counterpart:

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

Batching operations

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


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

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

await client.SubmitAsync();

Confirming that a batch was saved to the xDB Collection database

After calling client.Submit()/client.SubmitAsync(), you can use the client.LastBatch property to see a list of the operations that were included in the batch. Data is available in the xDB Collection database for any operation where the value of the Status property is Succeeded. See Get operation results for more information.

Confirming that a batch was indexed

The xConnect Search Indexer updates the xDB index after changes have been saved to the xDB Collection database. See Batch indexing for more information about how to confirm that a batch has been indexed.

Anticipating exceptions

The xConnect Client API throws an exception if one or more operations fails. Wrap usage of the xConnect Client API in a try/catch statement and catch the XdbExecutionException or XdbUnavailableException as shown in the following example:

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

For more information about exceptions and error handling in xConnect, see Handling exceptions.

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