xConnect - Using Official xConnect .NET Library
February 20, 2018 Josip Ivković

Sitecore 9 ships with the official xConnect library. Although it's still an early release, it provides all the functionality we need to create powerful xDB integration layers. It will send OData JSON requests similarly to how we manually did this in our previous post, and optimize them further  by sending a batch of requests where possible.
Setting Up the Solution
Start by creating your favourite type of .NET 4.6.2. application.
Library DLLs are located in your IIS xConnect instance bin folder.
Reference the following:

  • Sitecore.Xconnect
  • Sitecore.XConnect.Client
  • Sitecore.XConnect.Collection.Model
  • Sitecore.Xdb.Common.Web


Additional prerequisite is to install the xConnect SSL certificate. If you installed it during Sitecore 9 installation find it's thumbprint, as we will use it for TLS connection. Otherwise, install it to your system manually. It should be located at Local Computer\Personal\Certificates\<yourinstance>.xconnect_client.

Establishing the Connection
The following snippet will initiate a TLS connection. Make sure you replace the certificate thumbprint with your own:

// Valid certificate thumbprints must be passed in

CertificateWebRequestHandlerModifierOptions options = CertificateWebRequestHandlerModifierOptions.Parse("StoreName=My;StoreLocation=Local



// Optional timeout modifier

var certificateModifier = new CertificateWebRequestHandlerModifier(options);

List<IHttpClientModifier> clientModifiers = new List<IHttpClientModifier>();

var timeoutClientModifier = new TimeoutHttpClientModifier(new TimeSpan(0, 0, 20));



// This overload takes three client end points - collection, search, and configuration

var collectionClient = new CollectionWebApiClient(

new Uri("https://<yourinstance>/odata"), clientModifiers, new[] {

certificateModifier });

var searchClient = new SearchWebApiClient(

new Uri("https://<yourinstance>/odata"), clientModifiers, new[] {

certificateModifier });

var configurationClient = new ConfigurationWebApiClient(new

Uri("https://<yourinstance>/configuration"), clientModifiers, new[] {

certificateModifier });


var cfg = new XConnectClientConfiguration(

new XdbRuntimeModel(CollectionModel.Model), collectionClient, searchClient,





await cfg.InitializeAsync();


catch (XdbModelConflictException ce)


Console.WriteLine("ERROR:" + ce.Message);



Using xConnect Context
When working with xDB, all changes must be done under a valid Context. Initialize it using the following snippet:

using (var client = new XConnectClient(cfg))


// code here




Creating Contacts and Facets
If the connection is successful, we can add Contact and it's PersonalInformation Facet.

To create the new Contact we need to instantiate Contact class, and its ContactIdentifier:

Contact contact = new Contact(

new ContactIdentifier("Coria", "Test", ContactIdentifierType.Known));

After creating the entity, it must be added to the xConnect client:


Let's make an instance of the PersonalInformation Facet:

PersonalInformation personalInfoFacet = new PersonalInformation()


FirstName = "Corry",

LastName = "Corian",


Bind it to Contact on client:


contact, PersonalInformation.DefaultFacetKey, personalInfoFacet);

Last line to call is actuall submitting changes to xConnect server. Do this by submitting client object:


This sample shows how easy is to do basic interfacing with Sitecore xDB using the xConnect server and official .NET library. In our next and last post in the Developing with xConnect series, we will show you how to use xConnectPy - a library of our own making. Hopefully it will help your IOT and Embedded projects connect to Sitecore xDB more easily. If you missed it, you can check the previous post here: xConnect - Debugging with Fiddler and thefinal one here: Interfacing xConnect Using Python.

Feel free to contact us if you have any questions!

Josip Ivković
Machine Learning, Data Science, & Development