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

The GetVariantAliases(JsonObject, string) retrieves each variant’s alias from publish_details.variants on the CDA entry JSON and returns one result as a JsonObject.

Throws ArgumentException if:

• entry is null
• entry.uid is missing
• contentTypeUid is null or empty

• If the payload contains a nested entry object, the method reads from that object.

The following example retrieves variant aliases for a single entry:

// Initialize the utility and process a single entry
var variantUtils = new VariantUtility();
JsonObject entry = GetEntryFromJson(); // Method to fetch your CDA entry
string contentTypeUid = "product";

try {
    JsonObject result = variantUtils.GetVariantAliases(entry, contentTypeUid);
    // Access aliases from the result object
    var aliases = result["variants"];
} catch (ArgumentException ex) {
    Console.WriteLine($"Validation Error: {ex.Message}");
}

The Utils.GetVariantAliases(JsonArray, string) retrieves variant aliases for each CDA entry in a JsonArray and returns one result object per valid entry as a JsonArray.

• Throws ArgumentException if contentTypeUid is null or empty.

• Skips invalid entries and processes only entries with a valid UID.

The following example retrieves variant aliases for multiple entries:

// Initialize the utility and process multiple entries
var variantUtils = new VariantUtility();
JsonArray entries = GetEntriesFromListResponse(); // Method to fetch your CDA entries list
string contentTypeUid = "product";

try {
    JsonArray 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(JsonObject, string) method builds a JsonObject for HTML integration. The data-csvariants property is a string containing a serialized JSON array of variant details.

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 System.Text.Json serialization.

• Throws ArgumentException if entry is provided, and contentTypeUid is null or empty.

• Processes a single entry via the array path (same pipeline as the JsonArray 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.

The following example builds the attribute for a single entry:

// Initialize the utility and generate metadata tags
var variantUtils = new VariantUtility();
JsonObject entry = GetEntryFromJson();
string contentTypeUid = "product";

try {
    JsonObject 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(JsonArray, string) method builds a JsonObject whose data-csvariants string serializes variant details for multiple entries.

• Throws ArgumentException if entries are provided, and contentTypeUid is null or empty.

• 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.

The following example builds the attribute for multiple entries:

// Initialize the utility and generate metadata tags for multiple entries
var variantUtils = new VariantUtility();
JsonArray entries = GetEntriesFromListResponse();
string contentTypeUid = "product";

try {
    JsonObject attributeMap = variantUtils.GetVariantMetadataTags(entries, contentTypeUid);
    string jsonString = attributeMap["data-csvariants"].ToString();
    // Output: "[{\"entry_uid\":\"...\"},{\"entry_uid\":\"...\"}]"
} catch (ArgumentException ex) {
    Console.WriteLine(ex.Message);
}

The following methods are deprecated and will be removed in a future release:

• GetDataCsvariantsAttribute(JsonObject, string)
• GetDataCsvariantsAttribute(JsonArray, string)

Note Use GetVariantMetadataTags instead. These methods internally delegate to GetVariantMetadataTags and return the same result, ensuring backward compatibility.