Reference Data Client API
Current version: 10.1
The Reference Data Client API accesses the Reference Data Service over HTTPS. It is represented by the ReferenceDataHttpClient class, and implements the IReferenceDataClient interface.
Note
Synchronous and asynchronous versions of each method are available. For example, EnsureDefinitionType() and EnsureDefinitionTypeAsync().
All examples use a basic Definition<string,string> defintion type, but you can also create custom types.
Get the Reference Data Client API in a Sitecore context
The following example demonstrates how to retrieve a read-only and a read/write instance of the Reference Data Client API in a Sitecore context:
RequestResponse
using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Core;
namespace Documentation
{
public class RefDataClients
{
public async void AsyncExample()
{
// Read-write client
var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;
// Read-only client
var readOnlyClient = ServiceLocator.ServiceProvider.GetService(typeof(IReadOnlyReferenceDataClient)) as IReadOnlyReferenceDataClient;
}
}
}
Note
In a Sitecore context, configuration controls whether the service implementation or the HTTP client implementation is returned.
Get the Reference Data Client API in a non-Sitecore context
The following example demonstrates how to construct the ReferenceDataHttpClient in a non-Sitecore context:
RequestResponse
using System;
using Microsoft.Extensions.Logging;
using Sitecore.Xdb.Common.Web;
using Sitecore.Xdb.ReferenceData.Client;
using Sitecore.Xdb.ReferenceData.Core.Converter;
namespace TestConsoleApp
{
public class RefDataHttpClientNonSitecore
{
public async void AsyncExample()
{
var url = "https://refdata/";
var converter = new DefinitionEnvelopeJsonConverter();
// Valid certificate thumbprints must be passed in
var options = CertificateHttpClientHandlerModifierOptions.Parse(
"StoreName=My;StoreLocation=LocalMachine;FindType=FindByThumbprint;FindValue=BC6DBAC6D7E7796E5816DBA268FE2B7036F0F8D9");
// Optional timeout modifier
IHttpClientHandlerModifier[] handlers = { new CertificateHttpClientHandlerModifier(options) };
var logger = new Logger<ReferenceDataHttpClient>(new LoggerFactory());
var client = new ReferenceDataHttpClient(
converter,
new Uri(url),
handlers,
logger
);
}
}
}
Retrieve a definition
The following example demonstrates how to retrieve a definition. If you do not specify a culture, all available cultures are returned.
RequestResponse
using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Client;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;
namespace Documentation
{
public class RefDataGetDefinition
{
public async void AsyncExample()
{
var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;
var definitionType = await client.EnsureDefinitionTypeAsync("starfleet ships");
var criteria = new DefinitionCriteria("voyager", definitionType);
var definition = await client.GetDefinitionAsync<string, string>(criteria, false);
var definitionData = definition.CultureData[new CultureInfo("en-us")]; // Get language from e.g. Sitecore.Context.CurrentLanguage.CultureInfo
}
}
}
Retrieve a culture-specific definition
The following example demonstrates how to retrieve a culture-specific definition:
RequestResponse
using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Client;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;
namespace Documentation
{
public class RefDataGetDefinitionCulture
{
public async void AsyncExample()
{
var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;
// Retrieve Latest Active Definition with Danish Culture Only
var definitionType = await client.EnsureDefinitionTypeAsync("starfleet ships");
var criteria = new DefinitionCriteria("voyager", definitionType)
{
Culture = new CultureInfo("da") // Get language from e.g. Sitecore.Context.CurrentLanguage.CultureInfo
};
var definition = await client.GetDefinitionAsync<string, string>(criteria, false);
// Get Danish culture
var data = definition.CultureData[new CultureInfo("da")]; // Get language from e.g.Sitecore.Context.CurrentLanguage.CultureInfo
}
}
}
Retrieve culture-invariant definition
The following example demonstrates how to retrieve a culture invariant definition:
RequestResponse
using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Client;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;
public class RefDataGetDefinitionCultureInvariant
{
public async void AsyncExample()
{
var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;
// Retrieve Latest Active Definition Culture Invariant
var definitionType = await client.EnsureDefinitionTypeAsync("starfleet ships");
var criteria = new DefinitionCriteria("voyager", definitionType)
{
Culture = CultureInfo.InvariantCulture
};
var definition = await client.GetDefinitionAsync<string, string>(criteria, false);
var data = definition.CultureData[CultureInfo.InvariantCulture];
}
}
Culture invariant data is used when data has a culture, but that culture is not explicitly defined by the source of the data. For example, an external provider might provide a list of city names in English, but does not explicitly specify the culture of the data. In such cases, data should be stored as culture invariant.
Save a Definition
The following example demonstrates how to create and save a new definition in various cultures:
RequestResponse
using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;
namespace Documentation
{
public class RefDataSaveDefinition
{
public async void Example()
{
var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;
var definitionType = await client.EnsureDefinitionTypeAsync("country");
var definitionKey = new DefinitionKey("se", definitionType, 1);
var definition = new Definition<string, string>(definitionKey)
{
IsActive = true,
CommonData = "the common data",
CultureData = {
{ new CultureInfo("en"), "Sweden" }
}
};
// aDd another definition culture
definition.CultureData[new CultureInfo("se")] = "Sverige";
// Culture invariant data (has culture, but culture is unknown)
definition.CultureData[CultureInfo.InvariantCulture] = "Swedenland";
await client.SaveAsync(definition);
}
}
}
Save Multiple Definitions
The following example demonstrates how to save multiple definitions:
RequestResponse
using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;
using Sitecore.Xdb.ReferenceData.Core.Collections;
namespace Documentation
{
public class RefDataSaveDefinition
{
public async void Example()
{
var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;
var definitionType = await client.EnsureDefinitionTypeAsync("country");
var definitionKey = new DefinitionKey("se", definitionType, 1);
var definition = new Definition<string, string>(definitionKey)
{
IsActive = true
};
definition.CultureData[new CultureInfo("en")] = "Sweden";
definition.CultureData[new CultureInfo("se")] = "Sverige";
var definitionKey2 = new DefinitionKey("de", definitionType, 1);
var definition2 = new Definition<string, string>(definitionKey)
{
IsActive = true
};
definition.CultureData[new CultureInfo("en")] = "Germany";
definition.CultureData[new CultureInfo("se")] = "Tyskland";
var definitions = new DefinitionCollection<string, string>
{
definition,
definition2
};
await client.SaveAsync(definitions);
}
}
}
Activate a Definition
To activate a definition, set the IsActive property of the definition to true and save the definition.
RequestResponse
using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Client;
using Sitecore.Xdb.ReferenceData.Core;
using System.Globalization;
namespace Documentation
{
public class RefDataActivateDefinition
{
public async void AsyncExample()
{
var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;
var definitionType = await client.EnsureDefinitionTypeAsync("starfleet ships");
var criteria = new DefinitionCriteria("voyager", definitionType);
var definition = await client.GetDefinitionAsync<string, string>(criteria, false);
definition.IsActive = true;
await client.SaveAsync(definition);
}
}
}
Get all definitions by a specific type
The following example demonstrates how to get all definitions by a specific type and paginate the results.
RequestResponse
using Sitecore.DependencyInjection;
using Sitecore.Xdb.ReferenceData.Core;
namespace Documentation
{
public class RefDataActivateGetByType
{
public async void AsyncExample()
{
var client = ServiceLocator.ServiceProvider.GetService(typeof(IReferenceDataClient)) as IReferenceDataClient;
var definitionType = await client.EnsureDefinitionTypeAsync("starfleet ships");
// Gets the first 10 active definitions
var definitions = await client.GetDefinitionsByTypeAsync<string, string>(definitionType, true, 1, 10);
var pageOneDefinitions = definitions.Definitions;
var currentPage = definitions.PageNumber;
var currentPageSize = definitions.PageSize;
var totalDefinitions = definitions.Total; // Total number of definitions with type 'starfleet ships'
}
}
}