1. Getting Started with xConnect

Create, retrieve, and search contact and interaction data

Version:

The xConnect Client API

The xConnect Client API allows you to create, retrieve, and search contact and interaction data. No client has direct access to the collection database or the search index. The underlying REST-ful web API implements the oData protocol and all communication happens over HTTPS.

The following example demonstrates how to get an instance of the xConnect Client API in a Sitecore context:

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

namespace Documentation
{
    public class GetFacetsMultiple
    {
        public async void Example()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    // Get, create, or search experience data here
                }
                catch (XdbExecutionException ex)
                {
                    // Handle exceptions
                }
            }
        }
    }
}

The xConnect end points are configured in the \App_Config\ConnectionStrings.config file. In a developer environment, Collection and Search share a single end point named xdb.collection.

The xConnect Client API can also be used outside of Sitecore. The following example demonstrates how to use the xConnect Client API from a console application:

using Sitecore.XConnect;
using Sitecore.XConnect.Client;
using Sitecore.XConnect.Schema;
using System;
using System.Threading.Tasks;
using Sitecore.XConnect.Client.WebApi;
using Sitecore.Xdb.Common.Web;
using Sitecore.XConnect.Collection.Model;
using System.Collections.Generic;
using Sitecore.Xdb.Common.Web;

namespace Documentation
{
    public class Program
    {
        private static void Main(string[] args)
        {
            MainAsync(args).ConfigureAwait(false).GetAwaiter().GetResult();
        }

        private static async Task MainAsync(string[] args)
        {
            CertificateHttpClientHandlerModifierOptions options =
            CertificateHttpClientHandlerModifierOptions.Parse("StoreName=My;StoreLocation=LocalMachine;FindType=FindByThumbprint;FindValue=15E6693B0AECB63DE57D991EC363CA462DC52432");

            var certificateModifier = new CertificateHttpClientHandlerModifier(options);

            List<IHttpClientModifier> clientModifiers = new List<IHttpClientModifier>();
            var timeoutClientModifier = new TimeoutHttpClientModifier(new TimeSpan(0, 0, 20));
            clientModifiers.Add(timeoutClientModifier);

            var collectionClient = new CollectionWebApiClient(new Uri("https://xconnect/odata"), clientModifiers, new[] { certificateModifier });
            var searchClient = new SearchWebApiClient(new Uri("https://xconnect/odata"), clientModifiers, new[] { certificateModifier });
            var configurationClient = new ConfigurationWebApiClient(new Uri("https://xconnect/configuration"), clientModifiers, new[] { certificateModifier });

            var cfg = new XConnectClientConfiguration(
                new XdbRuntimeModel(CollectionModel.Model), collectionClient, searchClient, configurationClient);

            try
            {
                await cfg.InitializeAsync();

            }
            catch (XdbModelConflictException ce)
            {
                Console.WriteLine("ERROR:" + ce.Message);
                return;
            }

            using (var client = new XConnectClient(cfg))
            {
            }
        }
    }
}

Extending xConnect

As a developer, you can extend xConnect in the following ways:

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