.NET Utils SDK Variant Utility
The Variant Utility reads variant alias data from CDA entry responses and formats it for application use. Use this utility when working with variant-aware entries that include publish_details.variants.
It helps you:
- Extract variant aliases per entry
- Generate the data-csvariants attribute for frontend rendering
Use cases
Use this utility when:
- You fetch entries with variant headers (for example, x-cs-variant-uid)
- You need alias values for personalization or targeting
- You want to render variant data in HTML using data-csvariants
Method index
| Method | Description |
| GetVariantAliases(JObject, string) | Returns variant aliases for a single entry. |
| GetVariantAliases(JArray, string) | Returns variant aliases for multiple entries. |
| GetVariantMetadataTags(JObject, string) | Builds the HTML attribute payload for a single entry. |
| GetVariantMetadataTags(JArray, string) | Builds the HTML attribute payload for multiple entries. |
Class-level Example
This example shows how to:
- Read a Content Delivery API-style entry as JObject
- Extract variant aliases with Utils.GetVariantAliases
- Generate the data-csvariants HTML attribute payload with Utils.GetVariantMetadataTags
using System;
using Contentstack.Utils;
using Newtonsoft.Json.Linq;
public class VariantUtilsExample
{
private const string ContentTypeUid = "<CONTENT_TYPE_UID>";
/// <summary>
/// Normalize entry JSON by unwrapping a top-level "entry" object when present.
/// </summary>
private static JObject UnwrapEntryJson(JObject response)
{
return response["entry"] as JObject ?? response;
}
public static void Main()
{
// Example: entry JSON returned by your Delivery SDK or Content Delivery API call.
JObject response = JObject.Parse(@"
{
""entry"": {
""uid"": ""blt8f9e7c1234567890"",
""publish_details"": {
""variants"": {
""v1"": { ""alias"": ""cs_personalize_0_0"" },
""v2"": { ""alias"": ""cs_personalize_0_3"" }
}
}
}
}");
JObject entryJson = UnwrapEntryJson(response);
try
{
// 1. Extract variant aliases
JObject variantInfo = Utils.GetVariantAliases(entryJson, ContentTypeUid);
string entryUid = variantInfo["entry_uid"]?.ToString() ?? string.Empty;
JArray aliases = variantInfo["variants"] as JArray ?? new JArray();
Console.WriteLine($"Entry UID: {entryUid}");
Console.WriteLine("Aliases:");
foreach (JToken alias in aliases)
{
Console.WriteLine($"- {alias}");
}
// 2. Build the data-csvariants payload
JObject attr = Utils.GetVariantMetadataTags(entryJson, ContentTypeUid);
string dataCsvariants = attr["data-csvariants"]?.ToString() ?? "[]";
Console.WriteLine($"data-csvariants: {dataCsvariants}");
// Optional: parse the JSON string if you want to inspect it in code
JArray parsed = JArray.Parse(dataCsvariants);
Console.WriteLine($"Serialized payload count: {parsed.Count}");
}
catch (ArgumentException ex)
{
// Thrown when contentTypeUid is null/empty,
// or when the entry is null / missing uid.
Console.WriteLine($"Variant utility error: {ex.Message}");
}
}
}GetVariantAliases (Single Entry)
The GetVariantAliases(JObject, string) retrieves each variant’s alias from publish_details.variants on the CDA entry JSON and returns one result as a JObject.
Parameters
| Name | Type | Required | Description |
| entry | JObject | Yes | CDA entry used to read publish_details.variants |
| contentTypeUid | string | Yes | Content type UID for the entry. Returned as contenttype_uid in the result |
Returns
| Value | Description |
| JObject | For single-entry input. Contains entry_uid, contenttype_uid, and variants |
Validation
Throws ArgumentException if:
- entry is null
- entry.uid is missing
- contentTypeUid is null or empty
Behavior
- If the payload contains a nested entry object, the method reads from that object.
Example
The following example retrieves variant aliases for a single entry:
// Initialize the utility and process a single entry
var variantUtils = new VariantUtility();
JObject entry = GetEntryFromJson(); // Method to fetch your CDA entry
string contentTypeUid = "product";
try {
JObject result = variantUtils.GetVariantAliases(entry, contentTypeUid);
// Access aliases from the result object
var aliases = result["variants"];
} catch (ArgumentException ex) {
Console.WriteLine($"Validation Error: {ex.Message}");
}GetVariantAliases (Multiple Entries)
The Utils.GetVariantAliases(JArray, string) retrieves variant aliases for each CDA entry in a JArray and returns one result object per valid entry as a JArray.
Parameters
| Name | Type | Required | Description |
| entries | JArray | No | CDA entries to process. Returns an empty array if null. Skips entries with invalid UIDs. |
| contentTypeUid | string | Yes | Content type UID applied to all entries. Returned as contenttype_uid in each result object. |
Returns
| Value | Description |
| JArray | Each element has the same shape as the single-entry JObject result (entry_uid, contenttype_uid, variants). |
Validation
- Throws ArgumentException if contentTypeUid is null or empty.
Behavior
- Skips invalid entries and processes only entries with a valid UID.
Example
The following example retrieves variant aliases for multiple entries:
// Initialize the utility and process multiple entries
var variantUtils = new VariantUtility();
JArray entries = GetEntriesFromListResponse(); // Method to fetch your CDA entries list
string contentTypeUid = "product";
try {
JArray results = variantUtils.GetVariantAliases(entries, contentTypeUid);
foreach (var result in results) {
Console.WriteLine($"Entry: {result["entry_uid"]}, Aliases: {result["variants"]}");
}
} catch (ArgumentException ex) {
Console.WriteLine($"Validation Error: {ex.Message}");
}The GetVariantMetadataTags(JObject, string) method builds a JObject for HTML integration. The data-csvariants property is a string containing a serialized JSON array of variant details.
Parameters
| Name | Type | Required | Description |
| entry | JObject | No | CDA entry. Defines the entry to serialize. Returns data-csvariants as "[]" if null. |
| contentTypeUid | string | Yes (if entry provided) | Content type UID for the entry. Required whenever entry is not null. |
Returns
| Value | Description |
| JObject | Contains data-csvariants as a string (serialized JSON array). Each element represents { entry_uid, contenttype_uid, variants }. |
Note The data-csvariants value is a serialized JSON array where each element follows the shape { entry_uid, contenttype_uid, variants }. Exact formatting depends on Newtonsoft.Json serialization.
Validation
- Throws ArgumentException if entry is provided, and contentTypeUid is null or empty.
Behavior
- Processes a single entry via the array path (same pipeline as the JArray overload with one element).
- Returns { "data-csvariants": "[]" } if entry is null. It does not throw an error.
Note The data-csvariants is returned as raw JSON text. In standard Razor or Blazor attribute binding, output is HTML-encoded automatically. If you inject this value into raw HTML or bypass framework encoding, encode it for an HTML attribute before rendering.
Example
The following example builds the attribute for a single entry:
// Initialize the utility and generate metadata tags
var variantUtils = new VariantUtility();
JObject entry = GetEntryFromJson();
string contentTypeUid = "product";
try {
JObject attributeMap = variantUtils.GetVariantMetadataTags(entry, contentTypeUid);
string jsonString = attributeMap["data-csvariants"].ToString();
// Output: "[{\"entry_uid\":\"...\",\"contenttype_uid\":\"...\",\"variants\":[...]}]"
} catch (ArgumentException ex) {
Console.WriteLine(ex.Message);
}The GetVariantMetadataTags(JArray, string) method builds a JObject whose data-csvariants string serializes variant details for multiple entries.
Parameters (JArray overload)
| Name | Type | Required | Description |
| entries | JArray | No | CDA entries. Returns { "data-csvariants": "[]" } if null. |
| contentTypeUid | string | Yes (if entries provided) | Shared content type UID for the entries. Required whenever entries are not null. |
Returns
| Value | Description |
| JObject | Contains data-csvariants as a string (serialized JSON array). Each element represents { entry_uid, contenttype_uid, variants }. |
Validation
- Throws ArgumentException if entries are provided, and contentTypeUid is null or empty.
Behavior
- Calls GetVariantAliases and serializes the result into data-csvariants.
- Returns { "data-csvariants": "[]" } if entries is null. It does not throw an error.
Note The data-csvariants is returned as raw JSON text. In standard Razor or Blazor attribute binding, output is HTML-encoded automatically. If you inject this value into raw HTML or bypass framework encoding, encode it for an HTML attribute before rendering.
Example
The following example builds the attribute for multiple entries:
// Initialize the utility and generate metadata tags for multiple entries
var variantUtils = new VariantUtility();
JArray entries = GetEntriesFromListResponse();
string contentTypeUid = "product";
try {
JObject attributeMap = variantUtils.GetVariantMetadataTags(entries, contentTypeUid);
string jsonString = attributeMap["data-csvariants"].ToString();
// Output: "[{\"entry_uid\":\"...\"},{\"entry_uid\":\"...\"}]"
} catch (ArgumentException ex) {
Console.WriteLine(ex.Message);
}Deprecated Methods
The following methods are deprecated and will be removed in a future release:
- GetDataCsvariantsAttribute(JObject, string)
- GetDataCsvariantsAttribute(JArray, string)
Note Use GetVariantMetadataTags instead. These methods internally delegate to GetVariantMetadataTags and return the same result, ensuring backward compatibility.