EntryVariant
EntryVariant
The EntryVariant class creates, reads, updates, deletes, publishes, and unpublishes the variants of one entry.
When to Use This Class: Use this class when one entry needs different content for different audiences, for example a banner color per region.
Conceptual Role: Acts as the Content Management API (CMA) client for the /content_types/<CONTENT_TYPE_UID>/entries/<ENTRY_UID>/variants endpoint. Call the Variant method of Entry to get an instance.
Returns: EntryVariant. A handle for entry variant operations.
Instance State
The UID you pass to entry.Variant() decides which methods you can call on the instance:
- Call .Variant() without a UID to list the variants of the entry with Find or FindAsync.
- Call .Variant("<VARIANT_UID>") to work with one variant, for example Create or Publish.
- Pass a branch as the second argument, .Variant("<VARIANT_UID>", "<BRANCH_UID>"), to send every request from the instance to that branch.
If you call a method from the other group, it throws InvalidOperationException before any request leaves the SDK. Both groups use the same exception type, so read its message to tell the two cases apart. The Method Index below lists every method in each group.
IMPORTANT: Both arguments of Variant are strings, and the SDK does not check their order. A swapped pair sends the branch UID as the variant UID, and the API error names neither mistake. Pass the variant UID first, or use named arguments: .Variant(uid: "<VARIANT_UID>", branchUid: "<BRANCH_UID>").
Warning The SDK checks for an empty string as if it were no UID, so .Variant("") allows Find, and the request path then ends in /variants/. Call .Variant() with no argument when you mean the list.
Class-Level Notes
Getting an instance.
- entry.Variant() throws ArgumentException when the entry instance has no UID, and InvalidOperationException when the client has no authtoken and the stack has no management token.
- The Uid property of an instance has no public setter. Call entry.Variant() again to work with another variant.
Variant content.
- Create and Update take any object, for example an anonymous object or your own class, and send it under the entry key.
- The Content Management API (CMA) reference asks for only the fields that differ from the base entry. The other fields keep their values from the base entry. See Create entry variant.
- Before you create entry variants, link the content type to a variant group with the LinkContentTypes method of VariantGroup.
- The CMA reference notes that the entry variants feature may not be available to every organization.
Branches.
- The branchUid argument of entry.Variant() sets the branch header on every request from the instance, in place of the branch you passed to client.Stack().
- A null, empty, or white-space branchUid keeps the branch of the Stack.
Errors.
- The SDK throws ContentstackErrorException when the API returns an error status. Read StatusCode, ErrorCode, ErrorMessage, and Errors on the exception to see what the API rejected.
- A method that returns without throwing returns a ContentstackResponse with a success status. Read its body with OpenJsonObjectResponse() or OpenTResponse<T>().
Rate Limiting & Retry.
- This SDK automatically retries a request that returns 429, 500, 502, 503, or 504, with configurable delay and attempt limits.
Additional Resources Refer to Retry Mechanism to configure retries, and Content Management API Errors for the error codes the API returns.
Async methods.
- An async method runs its client-side checks when you call it, before it returns a task. An API rejection surfaces when you await the task.
Capability Matrix
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Name or list the versions of an entry variant | No | The CMA has requests for variant versions, and this SDK has no method for them. |
| Create, rename, or delete variant groups and variants | No | The VariantGroup class lists variant groups and links content types only. |
| Publish a variant without the base entry request | No | Publish sends the entry publish request, and its body names the variant. |
Method Index
List the variants of an entry. Available on entry.Variant() when you pass no UID.
| Method Name | Returns | Description |
|---|---|---|
| Find | The API response with the entry's variants. | Lists the variants of the entry. |
| FindAsync | The API response with the entry's variants. | Lists the variants asynchronously. |
Work with one variant. Available on entry.Variant("<VARIANT_UID>").
| Method Name | Returns | Description |
|---|---|---|
| Create | The API response with the created entry variant. | Creates the variant content of the entry. |
| CreateAsync | The API response with the created entry variant. | Creates the variant asynchronously. |
| Update | The API response with the updated entry variant. | Updates the variant content of the entry. |
| UpdateAsync | The API response with the updated entry variant. | Updates the variant asynchronously. |
| Fetch | The API response with the requested entry variant. | Retrieves one variant of the entry. |
| FetchAsync | The API response with the requested entry variant. | Retrieves the variant asynchronously. |
| Delete | The API response with the deletion notice. | Deletes the variant from the entry. |
| DeleteAsync | The API response with the deletion notice. | Deletes the variant asynchronously. |
| Publish | The API response with the publish notice. | Publishes the variant. |
| PublishAsync | The API response with the publish notice. | Publishes the variant asynchronously. |
| Unpublish | The API response with the unpublish notice. | Unpublishes the variant. |
| UnpublishAsync | The API response with the unpublish notice. | Unpublishes the variant asynchronously. |
Class-Level Snippet
The snippet below creates a variant of an entry, publishes it to one environment, and lists the variants of the entry.
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Entry entry = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>");
try
{
// Send only the fields that differ from the base entry.
var variantContent = new { banner_color = "Navy Blue" };
await entry.Variant("<VARIANT_UID>").CreateAsync(variantContent);
PublishUnpublishDetails details = new PublishUnpublishDetails
{
Environments = new List<string> { "<ENVIRONMENT_NAME>" },
Locales = new List<string> { "en-us" },
VariantRules = new PublishVariantRules { PublishLatestBaseConditionally = true }
};
await entry.Variant("<VARIANT_UID>").PublishAsync(details);
ContentstackResponse variants = await entry.Variant().FindAsync();
Console.WriteLine(variants.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects a request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}Methods
Each method of the EntryVariant class has its own section below, with its parameters, validation rules, behavior, and examples.
Create
Create saves variant content for the entry under the variant whose UID you passed to entry.Variant().
| Name | Type | Description |
|---|---|---|
| model (required) | object | Fields that differ from the base entry. |
| collection | ParameterCollection? | Query parameters, for example locale. |
Returns: ContentstackResponse. The API response with the created entry variant.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has no variant UID, because the request path names the variant. Call entry.Variant("<VARIANT_UID>").
- Throws ArgumentNullException (parameter dataModel) if model is null, because the request needs a body.
- Throws ContentstackErrorException when the API rejects the request, for example when you have not linked the content type to the variant's group.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one PUT request to /content_types/<CONTENT_TYPE_UID>/entries/<ENTRY_UID>/variants/<VARIANT_UID>, with model under the entry key of the body.
- Sends every public property of model and leaves out properties that are null.
- Sends the entries of collection as query parameters. The Content Management API (CMA) reference lists locale. See Create entry variant.
- Sends the same request as Update. Calling Create for a variant that the entry already has updates it.
- Returns the raw API response. The variant content sits under the entry key.
Example
Basic usage: create a variant with one changed field
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
// Send only the fields that differ from the base entry.
var variantContent = new { banner_color = "Navy Blue" };
try
{
ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant("<VARIANT_UID>").Create(variantContent);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: create a variant in one locale
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
var variantContent = new { banner_title = "Soldes d'hiver", banner_color = "Navy Blue" };
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "<LOCALE_CODE>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant("<VARIANT_UID>").Create(variantContent, collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: calling Create without a variant UID
using System;
using Contentstack.Management.Core;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant().Create(new { banner_color = "Navy Blue" });
}
catch (InvalidOperationException e)
{
// Thrown before any request because Create needs a variant UID
Console.WriteLine(e.Message);
}CreateAsync
CreateAsync saves variant content for the entry under the variant whose UID you passed to entry.Variant(), without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| model (required) | object | Fields that differ from the base entry. |
| collection | ParameterCollection? | Query parameters, for example locale. |
Returns: Task<ContentstackResponse>. The API response with the created entry variant.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has no variant UID, because the request path names the variant.
- Throws ArgumentNullException (parameter dataModel) if model is null.
- The SDK throws the exceptions above when you call CreateAsync, before it returns a task.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Behaves like Create.
Example
Basic usage: create a variant with one changed field
using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
var variantContent = new { banner_color = "Navy Blue" };
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant("<VARIANT_UID>").CreateAsync(variantContent);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: create a variant in one locale on a branch
using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
var variantContent = new { banner_color = "Navy Blue" };
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "<LOCALE_CODE>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>")
.Variant("<VARIANT_UID>", "<BRANCH_UID>")
.CreateAsync(variantContent, collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Delete
Delete deletes the variant content of the entry for the variant whose UID you passed to entry.Variant().
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Query parameters, for example locale. |
Returns: ContentstackResponse. The API response with the deletion notice.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has no variant UID, because Delete removes one variant. Call entry.Variant("<VARIANT_UID>").
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one DELETE request to /content_types/<CONTENT_TYPE_UID>/entries/<ENTRY_UID>/variants/<VARIANT_UID>, with the entries of collection as query parameters.
- The Content Management API (CMA) reference lists locale for this request. See Delete entry variant.
- Returns the raw API response.
Warning Deleting an entry variant removes the variant content you saved for this entry. Neither the SDK nor the API offers a way to restore it.
Example
Basic usage: delete a variant of an entry
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant("<VARIANT_UID>").Delete();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: delete a variant in one locale
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "<LOCALE_CODE>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant("<VARIANT_UID>").Delete(collection);
Console.WriteLine(response.StatusCode);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}DeleteAsync
DeleteAsync deletes the variant content of the entry for the variant whose UID you passed to entry.Variant(), without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Query parameters, for example locale. |
Returns: Task<ContentstackResponse>. The API response with the deletion notice.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has no variant UID, because DeleteAsync removes one variant.
- The SDK throws the exceptions above when you call DeleteAsync, before it returns a task.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Behaves like Delete.
Warning Deleting an entry variant removes the variant content you saved for this entry. Neither the SDK nor the API offers a way to restore it.
Example
Basic usage: delete a variant of an entry
using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant("<VARIANT_UID>").DeleteAsync();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: delete a variant in one locale on a branch
using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "<LOCALE_CODE>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>")
.Variant("<VARIANT_UID>", "<BRANCH_UID>")
.DeleteAsync(collection);
Console.WriteLine(response.StatusCode);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Fetch
Fetch retrieves the variant of the entry whose UID you passed to entry.Variant().
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Query parameters, for example locale. |
Returns: ContentstackResponse. The API response with the requested entry variant.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has no variant UID, because Fetch reads one variant. Call entry.Variant("<VARIANT_UID>").
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one GET request to /content_types/<CONTENT_TYPE_UID>/entries/<ENTRY_UID>/variants/<VARIANT_UID>, with the entries of collection as query parameters.
- The Content Management API (CMA) reference lists locale, include_workflow, include_publish_details, and include_rules for this request. See Get single entry variant.
- Returns the raw API response. The variant content sits under the entry key.
Example
Basic usage: fetch one variant of an entry
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant("<VARIANT_UID>").Fetch();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: fetch a variant with its workflow and publish details
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "<LOCALE_CODE>");
collection.Add("include_workflow", true);
collection.Add("include_publish_details", true);
try
{
ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant("<VARIANT_UID>").Fetch(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}FetchAsync
FetchAsync retrieves the variant of the entry whose UID you passed to entry.Variant(), without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Query parameters, for example locale. |
Returns: Task<ContentstackResponse>. The API response with the requested entry variant.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has no variant UID, because FetchAsync reads one variant.
- The SDK throws the exceptions above when you call FetchAsync, before it returns a task.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Behaves like Fetch.
Example
Basic usage: fetch one variant of an entry
using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant("<VARIANT_UID>").FetchAsync();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: fetch a variant in one locale from a branch
using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "<LOCALE_CODE>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>")
.Variant("<VARIANT_UID>", "<BRANCH_UID>")
.FetchAsync(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Find
Find lists the variants of the entry you passed to entry.Variant().
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Query parameters, for example locale or limit. |
Returns: ContentstackResponse. The API response with the entry's variants.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has a variant UID, because Find lists all variants. Call entry.Variant() with no UID.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one GET request to /content_types/<CONTENT_TYPE_UID>/entries/<ENTRY_UID>/variants, with the entries of collection as query parameters.
- The Content Management API (CMA) reference lists locale, include_workflow, include_publish_details, include_rules, skip, and limit for this request. See Get all entry variants.
- Does not page through the results for you. Without limit and skip, the API applies its own page size.
- Returns the raw API response.
Example
Basic usage: list the variants of an entry
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant().Find();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: list variants in one locale with publish details
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "<LOCALE_CODE>");
collection.Add("include_publish_details", true);
collection.Add("limit", 10);
try
{
ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant().Find(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Management token: list the variants in a branch
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient();
try
{
// A null variant UID with a branch lists the variants in that branch.
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.ContentType("<CONTENT_TYPE_UID>")
.Entry("<ENTRY_UID>")
.Variant(null, "<BRANCH_UID>")
.Find();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}FindAsync
FindAsync lists the variants of the entry you passed to entry.Variant(), without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Query parameters, for example locale or limit. |
Returns: Task<ContentstackResponse>. The API response with the entry's variants.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has a variant UID, because FindAsync lists all variants.
- The SDK throws the exceptions above when you call FindAsync, before it returns a task.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Behaves like Find.
Example
Basic usage: list the variants of an entry
using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant().FindAsync();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: read the second page of variants
using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ParameterCollection collection = new ParameterCollection();
collection.Add("skip", 10);
collection.Add("limit", 10);
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant().FindAsync(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Publish
Publish publishes the variant whose UID you passed to entry.Variant() to the environments and locales you list.
| Name | Type | Description |
|---|---|---|
| details (required) | PublishUnpublishDetails | Environments, locales, variant version, and rules. |
| locale | string? | Locale code, sent as the top-level locale key. |
| apiVersion | string? | Value of the api_version request header. |
Returns: ContentstackResponse. The API response with the publish notice.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has no variant UID, because Publish adds that UID to the request. Call entry.Variant("<VARIANT_UID>").
- Throws ArgumentNullException (parameter details) if details is null, because the request body comes from it.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one POST request to the entry publish path, /content_types/<CONTENT_TYPE_UID>/entries/<ENTRY_UID>/publish. See Publish entry variant.
- Adds this variant to details.Variants before it sends the request, unless the list already holds an item with the same UID:
- The SDK changes the details object you pass. Reusing it for another variant publishes both variants.
- The item the SDK adds has no version. To publish a specific variant version, add your own PublishVariant with Uid and Version to details.Variants.
- Builds the rest of the body like the Publish method of Entry.
- The Content Management API (CMA) reference asks for variant_rules with publish_latest_base_conditionally set to true. Set it through details.VariantRules. See the PublishVariant class.
- Sends the branch from entry.Variant() as the branch header, when you passed one.
- Returns the raw API response with a notice.
Example
Basic usage: publish a variant to one environment
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
PublishUnpublishDetails details = new PublishUnpublishDetails
{
Environments = new List<string> { "<ENVIRONMENT_NAME>" },
Locales = new List<string> { "en-us" },
VariantRules = new PublishVariantRules { PublishLatestBaseConditionally = true }
};
try
{
ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant("<VARIANT_UID>").Publish(details);
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: publish version 2 of a variant
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
PublishUnpublishDetails details = new PublishUnpublishDetails
{
Environments = new List<string> { "<ENVIRONMENT_NAME>" },
Locales = new List<string> { "en-us" },
// An item with the same UID stops the SDK from adding one without a version.
Variants = new List<PublishVariant> { new PublishVariant { Uid = "<VARIANT_UID>", Version = 2 } },
VariantRules = new PublishVariantRules { PublishLatestBaseConditionally = true }
};
try
{
ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>")
.Variant("<VARIANT_UID>")
.Publish(details, locale: "en-us", apiVersion: "3.2");
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: publish two variants with separate details objects
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Entry entry = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>");
foreach (string variantUid in new List<string> { "<VARIANT_UID>", "<SECOND_VARIANT_UID>" })
{
// Publish adds the variant to details.Variants, so build new details for each call.
PublishUnpublishDetails details = new PublishUnpublishDetails
{
Environments = new List<string> { "<ENVIRONMENT_NAME>" },
Locales = new List<string> { "en-us" }
};
try
{
entry.Variant(variantUid).Publish(details);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}
}PublishAsync
PublishAsync publishes the variant whose UID you passed to entry.Variant() to the environments and locales you list, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| details (required) | PublishUnpublishDetails | Environments, locales, variant version, and rules. |
| locale | string? | Locale code, sent as the top-level locale key. |
| apiVersion | string? | Value of the api_version request header. |
Returns: Task<ContentstackResponse>. The API response with the publish notice.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has no variant UID, because PublishAsync adds that UID to the request.
- Throws ArgumentNullException (parameter details) if details is null.
- The SDK throws the exceptions above when you call PublishAsync, before it returns a task.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Behaves like Publish, including the change it makes to details.Variants.
Example
Basic usage: publish a variant to one environment
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
PublishUnpublishDetails details = new PublishUnpublishDetails
{
Environments = new List<string> { "<ENVIRONMENT_NAME>" },
Locales = new List<string> { "en-us" },
VariantRules = new PublishVariantRules { PublishLatestBaseConditionally = true }
};
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant("<VARIANT_UID>").PublishAsync(details);
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: publish version 2 of a variant on a branch
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
PublishUnpublishDetails details = new PublishUnpublishDetails
{
Environments = new List<string> { "<ENVIRONMENT_NAME>" },
Locales = new List<string> { "en-us" },
Variants = new List<PublishVariant> { new PublishVariant { Uid = "<VARIANT_UID>", Version = 2 } },
VariantRules = new PublishVariantRules { PublishLatestBaseConditionally = true }
};
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>")
.Variant("<VARIANT_UID>", "<BRANCH_UID>")
.PublishAsync(details, "en-us", "3.2");
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Unpublish
Unpublish removes the variant whose UID you passed to entry.Variant() from the environments and locales you list.
| Name | Type | Description |
|---|---|---|
| details (required) | PublishUnpublishDetails | Environments, locales, variant version, and rules. |
| locale | string? | Locale code, sent as the top-level locale key. |
| apiVersion | string? | Value of the api_version request header. |
Returns: ContentstackResponse. The API response with the unpublish notice.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has no variant UID, because Unpublish adds that UID to the request. Call entry.Variant("<VARIANT_UID>").
- Throws ArgumentNullException (parameter details) if details is null, because the request body comes from it.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one POST request to the entry unpublish path, /content_types/<CONTENT_TYPE_UID>/entries/<ENTRY_UID>/unpublish. See Unpublish entry variant.
- Adds this variant to details.Variants the same way as the Publish method, and changes the details object you pass.
- The Content Management API (CMA) reference asks for the variant UID and version within variants. Add your own PublishVariant with Version set to send the version.
- Sends the branch from entry.Variant() as the branch header, when you passed one.
- Returns the raw API response with a notice.
Warning Unpublishing removes the variant from the delivery environments you list until you publish the variant again.
Example
Basic usage: unpublish a variant from one environment
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
PublishUnpublishDetails details = new PublishUnpublishDetails
{
Environments = new List<string> { "<ENVIRONMENT_NAME>" },
Locales = new List<string> { "en-us" },
Variants = new List<PublishVariant> { new PublishVariant { Uid = "<VARIANT_UID>", Version = 1 } }
};
try
{
ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant("<VARIANT_UID>").Unpublish(details);
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: unpublish a variant with a locale and API version
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
PublishUnpublishDetails details = new PublishUnpublishDetails
{
Environments = new List<string> { "<ENVIRONMENT_NAME>" },
Locales = new List<string> { "en-us" },
Variants = new List<PublishVariant> { new PublishVariant { Uid = "<VARIANT_UID>", Version = 1 } }
};
try
{
ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>")
.Variant("<VARIANT_UID>")
.Unpublish(details, locale: "en-us", apiVersion: "3.2");
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}UnpublishAsync
UnpublishAsync removes the variant whose UID you passed to entry.Variant() from the environments and locales you list, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| details (required) | PublishUnpublishDetails | Environments, locales, variant version, and rules. |
| locale | string? | Locale code, sent as the top-level locale key. |
| apiVersion | string? | Value of the api_version request header. |
Returns: Task<ContentstackResponse>. The API response with the unpublish notice.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has no variant UID, because UnpublishAsync adds that UID to the request.
- Throws ArgumentNullException (parameter details) if details is null.
- The SDK throws the exceptions above when you call UnpublishAsync, before it returns a task.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Behaves like Unpublish, including the change it makes to details.Variants.
Warning Unpublishing removes the variant from the delivery environments you list until you publish the variant again.
Example
Basic usage: unpublish a variant from one environment
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
PublishUnpublishDetails details = new PublishUnpublishDetails
{
Environments = new List<string> { "<ENVIRONMENT_NAME>" },
Locales = new List<string> { "en-us" },
Variants = new List<PublishVariant> { new PublishVariant { Uid = "<VARIANT_UID>", Version = 1 } }
};
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant("<VARIANT_UID>").UnpublishAsync(details);
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: unpublish a variant on a branch with a management token
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient();
PublishUnpublishDetails details = new PublishUnpublishDetails
{
Environments = new List<string> { "<ENVIRONMENT_NAME>" },
Locales = new List<string> { "en-us" },
Variants = new List<PublishVariant> { new PublishVariant { Uid = "<VARIANT_UID>", Version = 1 } }
};
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.ContentType("<CONTENT_TYPE_UID>")
.Entry("<ENTRY_UID>")
.Variant("<VARIANT_UID>", "<BRANCH_UID>")
.UnpublishAsync(details, "en-us", "3.2");
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Update
Update changes the variant content of the entry for the variant whose UID you passed to entry.Variant().
| Name | Type | Description |
|---|---|---|
| model (required) | object | Fields that differ from the base entry. |
| collection | ParameterCollection? | Query parameters, for example locale. |
Returns: ContentstackResponse. The API response with the updated entry variant.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has no variant UID, because the request path names the variant. Call entry.Variant("<VARIANT_UID>").
- Throws ArgumentNullException (parameter dataModel) if model is null, because the request needs a body.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Calls Create, so it sends the same PUT request to /content_types/<CONTENT_TYPE_UID>/entries/<ENTRY_UID>/variants/<VARIANT_UID>.
- Sends the entries of collection as query parameters. The Content Management API (CMA) reference lists locale. See Update entry variant.
- Send only the fields that differ from the base entry. The other fields keep their values from the base entry.
- Returns the raw API response. The variant content sits under the entry key.
Example
Basic usage: change one field of a variant
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
var variantContent = new { banner_color = "Crimson" };
try
{
ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant("<VARIANT_UID>").Update(variantContent);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: update a variant in one locale
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
var variantContent = new { banner_title = "Soldes de printemps" };
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "<LOCALE_CODE>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant("<VARIANT_UID>").Update(variantContent, collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}UpdateAsync
UpdateAsync changes the variant content of the entry for the variant whose UID you passed to entry.Variant(), without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| model (required) | object | Fields that differ from the base entry. |
| collection | ParameterCollection? | Query parameters, for example locale. |
Returns: Task<ContentstackResponse>. The API response with the updated entry variant.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
- Throws InvalidOperationException if the instance has no variant UID, because the request path names the variant.
- Throws ArgumentNullException (parameter dataModel) if model is null.
- The SDK throws the exceptions above when you call UpdateAsync, before it returns a task.
- Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Calls CreateAsync, so it sends the same request.
- Otherwise behaves like Update.
Example
Basic usage: change one field of a variant
using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
var variantContent = new { banner_color = "Crimson" };
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Variant("<VARIANT_UID>").UpdateAsync(variantContent);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: update a variant in one locale with a management token
using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
var variantContent = new { banner_title = "Soldes de printemps" };
ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "<LOCALE_CODE>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.ContentType("<CONTENT_TYPE_UID>")
.Entry("<ENTRY_UID>")
.Variant("<VARIANT_UID>")
.UpdateAsync(variantContent, collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}