Extension
Extension
Extension uploads, creates, fetches, lists, updates, and deletes the extensions of a stack. An extension is a custom field, a custom widget, a dashboard widget, a JSON Rich Text Editor (RTE) plugin, or an asset sidebar extension.
When to Use This Class: Use this class when your code installs or maintains legacy experience extensions. For example, a stack setup script uploads the HTML file of a custom field, or registers a widget that a third party hosts.
Conceptual Role: Acts as the Content Management API (CMA) client for the /extensions endpoint. Call stack.Extension() to get an instance.
Returns: Extension. A handle for extension operations.
Instance State
The UID you pass to stack.Extension() decides which methods you can call on the instance:
- Call stack.Extension() without a UID to work with the extension collection, for example Query or Upload.
- Call stack.Extension("<EXTENSION_UID>") to work with one extension, for example Fetch or Delete.
If you call a method from the other group, it throws InvalidOperationException before any request leaves the SDK. Unlike most classes of this SDK, Extension throws InvalidOperationException in both cases, also when a single-item method runs on an instance with no UID.
The Method Index below lists every method in each group.
Warning The SDK checks for an empty string as if it were no UID, so stack.Extension("") allows Query, Upload, and Create, and the SDK then sends the request to /extensions/ with a trailing slash. Pass null, or call stack.Extension() with no argument, when you mean the collection.
Class-Level Notes
Authentication.
- stack.Extension() throws InvalidOperationException when the client has no authtoken and the Stack has no management token, and when the Stack has no API key.
- The CMA accepts an authtoken, a management token, or an Open Authorization (OAuth) token for every extension request. When the Stack has a management token, the SDK sends it instead of the client's authtoken.
Two ways to add an extension.
- Upload and UploadAsync send an HTML file as a multipart form. Build the request with CustomFieldModel, CustomWidgetModel, or DashboardWidgetModel. Contentstack then hosts the file.
- Create and CreateAsync send an ExtensionModel as JSON under the extension key. Set Src for an extension that another server hosts, or Srcdoc for source code that Contentstack hosts.
Branch scoping.
- Extension requests accept a branch header. Create the Stack with client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>", "<BRANCH_UID>") to send every request of this class to that branch.
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.
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 For more information on retry settings, refer to the ContentstackClientOptions documentation. For the request shapes, refer to the Extensions section of the Content Management API reference.
Capability Matrix
| Capability | Supported | Notes / Alternative |
|---|---|---|
| List only one kind of extension | Yes | Pass a query such as {"type":"field"} in the collection of the query's Find. See Query. |
| Set enable or default_width on a dashboard widget that another server hosts | No | ExtensionModel has no property for them. Upload the widget file with DashboardWidgetModel instead. |
| Set the width or blur effect of an asset sidebar extension | No | ExtensionModel has no property for them. Manage asset sidebar extensions through the CMA directly. |
| Send query parameters with an update | No | Update takes no collection, and UpdateAsync does not send the one you pass. |
| Replace the HTML file of an uploaded extension | No | Update sends JSON only. Send new source code in ExtensionModel.Srcdoc, or delete the extension and upload the new file. |
Method Index
Work with the extension collection. Available on stack.Extension() when you pass no UID.
| Method Name | Returns | Description |
|---|---|---|
| Query | A new query for extensions. | Builds a query that lists extensions. |
| Upload | The API response with the uploaded extension. | Uploads the HTML file of an extension. |
| UploadAsync | The API response with the uploaded extension. | Uploads the HTML file of an extension asynchronously. |
| Create | The API response with the created extension. | Creates an extension from a source URL or source code. |
| CreateAsync | The API response with the created extension. | Creates an extension from a source URL or source code asynchronously. |
Work with one extension. Available on stack.Extension("<EXTENSION_UID>").
| Method Name | Returns | Description |
|---|---|---|
| Fetch | The API response with the requested extension. | Retrieves one extension. |
| FetchAsync | The API response with the requested extension. | Retrieves one extension asynchronously. |
| Update | The API response with the updated extension. | Replaces the settings of an extension. |
| UpdateAsync | The API response with the updated extension. | Replaces the settings of an extension asynchronously. |
| Delete | The API response with the deletion notice. | Deletes an extension. |
| DeleteAsync | The API response with the deletion notice. | Deletes an extension asynchronously. |
Class-Level Snippet
The snippet below uploads a custom field from an HTML file, creates a widget that another server hosts, and lists the custom fields of the stack.
using System;
using System.Collections.Generic;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Models.CustomExtension;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Stack stack = client.Stack("<API_KEY>");
try
{
CustomFieldModel colorPicker = new CustomFieldModel("<FILE_PATH>", "text/html", "Color Picker", "text");
await stack.Extension().UploadAsync(colorPicker);
ExtensionModel widget = new ExtensionModel
{
Title = "SEO Checker",
Type = "widget",
Src = "https://example.com/seo-widget.html",
Scope = new ExtensionScope { ContentTypes = new List<string> { "$all" } }
};
await stack.Extension().CreateAsync(widget);
ParameterCollection collection = new ParameterCollection();
collection.AddQuery(new JsonObject { ["type"] = "field" });
ContentstackResponse list = await stack.Extension().Query().FindAsync(collection);
Console.WriteLine(list.OpenJsonObjectResponse()["extensions"]?.AsArray().Count);
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}Methods
Each method of the Extension class has its own section below, with its parameters, validation rules, behavior, and examples.
Create
Create creates an extension in the stack from an ExtensionModel, with either a source URL that another server hosts or source code that Contentstack hosts.
| Name | Type | Description |
|---|---|---|
| model (required) | ExtensionModel | Title, type, source, and settings of the new extension. |
Returns: ContentstackResponse. The API response with the created extension.
Validation
- Throws InvalidOperationException if the instance has a UID, because Create adds a new extension to the collection. Call stack.Extension() with no UID.
- Throws ArgumentNullException (parameter dataModel) if model is null, before any request.
- The SDK does not check model. A missing title, an unknown type, or a missing source reaches the API, and the SDK throws the API rejection as ContentstackErrorException.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one POST request to /extensions with the body {"extension": <model>}. The SDK leaves out every ExtensionModel property that is null, and always sends multiple.
- model.Type sets the kind of extension: field, widget, dashboard, rte_plugin, or asset_sidebar_widget. Set Src for an extension that another server hosts, or Srcdoc for source code.
- The Create a custom field with source URL and Create widget with source URL requests of the Content Management API reference describe the body. The other kinds of extension use the same request with their own fields.
- Returns the raw API response. The new extension sits under the extension key.
Limitations
- Does not set enable or default_width on a dashboard widget, or the width and blur effect of an asset sidebar extension, because ExtensionModel has no property for them. Upload a dashboard widget file with the Upload method instead.
Example
Basic usage: create a custom field from a source URL
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ExtensionModel model = new ExtensionModel
{
Title = "Color Picker",
Type = "field",
DataType = "text",
Src = "https://example.com/color-picker.html"
};
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Extension().Create(model);
Console.WriteLine(response.OpenJsonObjectResponse()["extension"]?["uid"]);
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All properties: create a widget from source code with a management token
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient();
ExtensionModel model = new ExtensionModel
{
Title = "SEO Checker",
Type = "widget",
Tags = new List<string> { "seo", "content" },
Srcdoc = "<html><body><p>SEO checks</p></body></html>",
Config = "{\"minimumWords\": 300}",
Multiple = false,
Scope = new ExtensionScope { ContentTypes = new List<string> { "blog_post" } }
};
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Extension().Create(model);
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}CreateAsync
CreateAsync creates an extension in the stack from an ExtensionModel, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| model (required) | ExtensionModel | Title, type, source, and settings of the new extension. |
Returns: Task<ContentstackResponse>. The API response with the created extension.
Validation
- Throws InvalidOperationException if the instance has a UID, because CreateAsync adds a new extension to the collection. Call stack.Extension() with no UID.
- Throws ArgumentNullException (parameter dataModel) if model is null.
- The SDK throws the exceptions above when you call CreateAsync, before it returns a task. An API rejection surfaces when you await the task, as ContentstackErrorException.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends the same POST request as Create, on a task that you await.
- Otherwise behaves like Create.
Example
Basic usage: create a custom field from a source URL
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ExtensionModel model = new ExtensionModel
{
Title = "Color Picker",
Type = "field",
DataType = "text",
Src = "https://example.com/color-picker.html"
};
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Extension().CreateAsync(model);
Console.WriteLine(response.OpenJsonObjectResponse()["extension"]?["uid"]);
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}JSON RTE plugin: create a plugin from a source URL with a management token
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient();
ExtensionModel model = new ExtensionModel
{
Title = "Word Count",
Type = "rte_plugin",
Src = "https://example.com/word-count-plugin.js",
Multiple = false
};
try
{
ContentstackResponse response = await client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.Extension()
.CreateAsync(model);
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Delete
Delete deletes the extension whose UID you passed to stack.Extension().
This method takes no parameters.
Returns: ContentstackResponse. The API response with the deletion notice.
Validation
- Throws InvalidOperationException if the instance has no UID or an empty string, because Delete removes one extension. Call stack.Extension("<EXTENSION_UID>").
- The SDK does not check the UID format. A UID that names no extension reaches the API, and the SDK throws the API rejection as ContentstackErrorException.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one DELETE request to /extensions/<EXTENSION_UID> with no query parameters.
- The Delete custom field, Delete a widget, and Delete the Dashboard Widget requests of the Content Management API reference use this path for each kind of extension.
- Returns the raw API response with a notice key.
Warning Deleting an extension is irreversible. The SDK and the API offer no way to restore it.
Example
Basic usage: delete an extension
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Extension("<EXTENSION_UID>").Delete();
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}");
}Management token: delete an extension on a branch
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient();
try
{
ContentstackResponse response = client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>", "<BRANCH_UID>")
.Extension("<EXTENSION_UID>")
.Delete();
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}DeleteAsync
DeleteAsync deletes the extension whose UID you passed to stack.Extension(), without blocking the calling thread.
This method takes no parameters.
Returns: Task<ContentstackResponse>. The API response with the deletion notice.
Validation
- Throws InvalidOperationException if the instance has no UID or an empty string, because DeleteAsync removes one extension. Call stack.Extension("<EXTENSION_UID>").
- The SDK throws the exception above when you call DeleteAsync, before it returns a task.
- An API rejection surfaces when you await the task, as ContentstackErrorException.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends the same DELETE request as Delete, on a task that you await.
- Otherwise behaves like Delete.
Warning Deleting an extension is irreversible. The SDK and the API offer no way to restore it.
Example
Basic usage: delete an extension
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Extension("<EXTENSION_UID>").DeleteAsync();
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}");
}Management token: delete an extension with a management token
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient();
try
{
ContentstackResponse response = await client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.Extension("<EXTENSION_UID>")
.DeleteAsync();
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Fetch
Fetch retrieves the extension whose UID you passed to stack.Extension().
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters, for example include_branch. |
Returns: ContentstackResponse. The API response with the requested extension.
Validation
- Throws InvalidOperationException if the instance has no UID or an empty string, because Fetch reads one extension. Call stack.Extension("<EXTENSION_UID>").
- The SDK does not check the UID format. A UID that names no extension reaches the API, and the SDK throws the API rejection as ContentstackErrorException.
- collection set to null sends no query parameters.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one GET request to /extensions/<EXTENSION_UID>, with the entries of collection as query parameters.
- The Get a single custom field request of the Content Management API reference describes the request. The same path returns every kind of extension. include_branch set to true adds the _branch key to the response.
- Returns the raw API response. The extension sits under the extension key.
Example
Basic usage: fetch an extension by UID
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Extension("<EXTENSION_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 an extension with its branch, using a management token
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);
try
{
ContentstackResponse response = client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.Extension("<EXTENSION_UID>")
.Fetch(collection);
Console.WriteLine(response.OpenJsonObjectResponse()["extension"]?["_branch"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: calling Fetch on an instance with no UID
using System;
using Contentstack.Management.Core;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
client.Stack("<API_KEY>").Extension().Fetch();
}
catch (InvalidOperationException e)
{
// Fires before any request, because the instance has no extension UID
Console.WriteLine(e.Message);
}FetchAsync
FetchAsync retrieves the extension whose UID you passed to stack.Extension(), without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters, for example include_branch. |
Returns: Task<ContentstackResponse>. The API response with the requested extension.
Validation
- Throws InvalidOperationException if the instance has no UID or an empty string, because FetchAsync reads one extension. Call stack.Extension("<EXTENSION_UID>").
- The SDK throws the exception above when you call FetchAsync, before it returns a task.
- An API rejection surfaces when you await the task, as ContentstackErrorException.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends the same GET request as Fetch, on a task that you await.
- Otherwise behaves like Fetch.
Example
Basic usage: fetch an extension by UID
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Extension("<EXTENSION_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 an extension with its branch, using a management token
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);
try
{
ContentstackResponse response = await client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.Extension("<EXTENSION_UID>")
.FetchAsync(collection);
Console.WriteLine(response.OpenJsonObjectResponse()["extension"]?["_branch"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Query
Query returns a query object that lists the extensions in the stack when you call Find or FindAsync on it.
This method takes no parameters.
Returns: Query. A new query for extensions.
Validation
- Throws InvalidOperationException if the instance has a UID, because Query lists the extension collection. Call stack.Extension() with no UID.
- Query sends no request. Errors that do occur come from the Find or FindAsync call that follows, not from Query. The SDK throws an API rejection as ContentstackErrorException.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Find and FindAsync send one GET request to /extensions. The request carries the parameters from Limit, Skip, IncludeCount, and the collection argument of Find. See the Query class for those methods.
- The Content Management API reference lists each kind of extension with a query parameter that names its type, for example in the Get all custom fields request. Pass the filter with ParameterCollection.AddQuery. The list below gives the type values:
- {"type":"field"} for custom fields
- {"type":"widget"} for custom widgets
- {"type":"dashboard"} for dashboard widgets
- {"type":"rte_plugin"} for JSON RTE plugins
- {"type":"asset_sidebar_widget"} for asset sidebar extensions
- The Get widgets of a content type request takes a scope parameter with a content type UID instead. Add it with collection.Add("scope", "<CONTENT_TYPE_UID>").
- Returns the raw API response. The extensions sit under the extensions key, and count holds the total when you call IncludeCount.
- Does not page through the results for you. Without Limit and Skip, the API applies its own page size.
Example
Basic usage: list the custom fields in a stack
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ParameterCollection collection = new ParameterCollection();
collection.AddQuery(new JsonObject { ["type"] = "field" });
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Extension().Query().Find(collection);
JsonArray? extensions = response.OpenJsonObjectResponse()["extensions"]?.AsArray();
foreach (JsonNode? extension in extensions ?? new JsonArray())
{
Console.WriteLine($"{extension?["uid"]}: {extension?["title"]}");
}
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}Paging: read one page of enabled dashboard widgets with a count, using a management token
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
ParameterCollection collection = new ParameterCollection();
collection.AddQuery(new JsonObject { ["type"] = "dashboard", ["enable"] = true });
try
{
ContentstackResponse response = await client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.Extension()
.Query()
.Limit(10)
.Skip(0)
.IncludeCount()
.FindAsync(collection);
Console.WriteLine($"Dashboard widgets: {response.OpenJsonObjectResponse()["count"]}");
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Filter: list the widgets of one content type
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("scope", "<CONTENT_TYPE_UID>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Extension().Query().Find(collection);
Console.WriteLine(response.OpenJsonObjectResponse()["extensions"]?.AsArray().Count);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Update
Update replaces the settings of the extension whose UID you passed to stack.Extension().
| Name | Type | Description |
|---|---|---|
| model (required) | ExtensionModel | The new title, type, source, and settings. |
Returns: ContentstackResponse. The API response with the updated extension.
Validation
- Throws InvalidOperationException if the instance has no UID or an empty string, because Update changes one extension. Call stack.Extension("<EXTENSION_UID>").
- Throws ArgumentNullException (parameter dataModel) if model is null, before any request.
- The SDK does not check model. An invalid value reaches the API, and the SDK throws the API rejection as ContentstackErrorException.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one PUT request to /extensions/<EXTENSION_UID> with the body {"extension": <model>}. The SDK leaves out every ExtensionModel property that is null, and always sends multiple.
- The Update a custom field and Update a widget requests of the Content Management API reference describe the body.
- Update takes no collection, so the request carries no query parameters.
- Returns the raw API response. The updated extension sits under the extension key.
Example
Basic usage: point a custom field at a new source URL
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ExtensionModel model = new ExtensionModel
{
Title = "Color Picker",
Type = "field",
DataType = "text",
Src = "https://example.com/color-picker-v2.html"
};
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Extension("<EXTENSION_UID>").Update(model);
Console.WriteLine(response.OpenJsonObjectResponse()["extension"]?["src"]);
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}Management token: change the scope of a widget
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient();
ExtensionModel model = new ExtensionModel
{
Title = "SEO Checker",
Type = "widget",
Src = "https://example.com/seo-widget.html",
Scope = new ExtensionScope { ContentTypes = new List<string> { "blog_post", "landing_page" } }
};
try
{
ContentstackResponse response = client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.Extension("<EXTENSION_UID>")
.Update(model);
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}UpdateAsync
UpdateAsync replaces the settings of the extension whose UID you passed to stack.Extension(), without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| model (required) | ExtensionModel | The new title, type, source, and settings. |
| collection | ParameterCollection? | Accepted for compatibility. The SDK does not send it. |
Returns: Task<ContentstackResponse>. The API response with the updated extension.
Validation
- Throws InvalidOperationException if the instance has no UID or an empty string, because UpdateAsync changes one extension. Call stack.Extension("<EXTENSION_UID>").
- Throws ArgumentNullException (parameter dataModel) if model is null.
- The SDK throws the exceptions above when you call UpdateAsync, before it returns a task. An API rejection surfaces when you await the task, as ContentstackErrorException.
- collection raises no error for any value, because the SDK does not read it.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends the same PUT request as Update, on a task that you await.
- UpdateAsync accepts a collection, but the SDK does not add its entries to the request. The request carries no query parameters, the same as Update.
- Otherwise behaves like Update.
Example
Basic usage: point a custom field at a new source URL
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ExtensionModel model = new ExtensionModel
{
Title = "Color Picker",
Type = "field",
DataType = "text",
Src = "https://example.com/color-picker-v2.html"
};
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Extension("<EXTENSION_UID>").UpdateAsync(model);
Console.WriteLine(response.OpenJsonObjectResponse()["extension"]?["src"]);
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: pass a collection with a management token
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
ExtensionModel model = new ExtensionModel { Title = "Color Picker", Type = "field", DataType = "text", Src = "https://example.com/color-picker-v2.html" };
// The SDK accepts this collection but does not send it with the request.
ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);
try
{
ContentstackResponse response = await client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.Extension("<EXTENSION_UID>")
.UpdateAsync(model, collection);
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Upload
Upload uploads the HTML file of a custom field, a custom widget, or a dashboard widget to the stack, and Contentstack hosts the file.
| Name | Type | Description |
|---|---|---|
| model (required) | IExtensionInterface | The file and settings of the extension to upload. |
Returns: ContentstackResponse. The API response with the uploaded extension.
Validation
- Throws InvalidOperationException if the instance has a UID, because Upload adds a new extension to the collection. Call stack.Extension() with no UID.
- Throws ArgumentNullException (parameter uploadInterface) if model is null, before any request.
- The SDK does not check the file content or the extension type. An invalid file reaches the API, and the SDK throws the API rejection as ContentstackErrorException.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- model takes any class that implements IExtensionInterface. The SDK ships three of them, listed below, and each one fixes the extension[type] form field:
- CustomFieldModel sends field.
- CustomWidgetModel sends widget.
- DashboardWidgetModel sends dashboard.
- IExtensionInterface extends IUploadInterface. It requires the Title, Tags, and ContentType properties and a GetHttpContent() method. Upload calls GetHttpContent() and sends what it returns as the request body.
- Sends one POST request to /extensions with a multipart/form-data body. The file goes in the extension[upload] form field, with the MIME type from the model's ContentType property.
- The Upload a custom field, Upload a widget, and Upload Dashboard Widget requests of the Content Management API reference describe the form fields.
- Returns the raw API response. The new extension sits under the extension key.
Known issue A CustomWidgetModel scope does not reach the API, because the SDK sends it as a form part with no field name. To limit a widget to some content types, create it with the Create method and set ExtensionModel.Scope.
Example
Basic usage: upload a custom field from an HTML file
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models.CustomExtension;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
CustomFieldModel model = new CustomFieldModel("<FILE_PATH>", "text/html", "Color Picker", "text");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Extension().Upload(model);
Console.WriteLine(response.OpenJsonObjectResponse()["extension"]?["uid"]);
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}Widget: upload a custom widget with a management token
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models.CustomExtension;
ContentstackClient client = new ContentstackClient();
CustomWidgetModel model = new CustomWidgetModel("<FILE_PATH>", "text/html", "SEO Checker", "seo");
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Extension().Upload(model);
Console.WriteLine(response.OpenJsonObjectResponse()["extension"]?["type"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Dashboard: upload an enabled dashboard widget at full width
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models.CustomExtension;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
DashboardWidgetModel model = new DashboardWidgetModel("<FILE_PATH>", "text/html", "Publishing Stats", true, "full");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Extension().Upload(model);
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}UploadAsync
UploadAsync uploads the HTML file of a custom field, a custom widget, or a dashboard widget to the stack, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| model (required) | IExtensionInterface | The file and settings of the extension to upload. |
Returns: Task<ContentstackResponse>. The API response with the uploaded extension.
Validation
- Throws InvalidOperationException if the instance has a UID, because UploadAsync adds a new extension to the collection. Call stack.Extension() with no UID.
- Throws ArgumentNullException (parameter uploadInterface) if model is null.
- The SDK throws the exceptions above when you call UploadAsync, before it returns a task. An API rejection surfaces when you await the task, as ContentstackErrorException.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends the same POST request as Upload, on a task that you await.
- Otherwise behaves like Upload.
Example
Basic usage: upload a custom field from an HTML file
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models.CustomExtension;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
CustomFieldModel model = new CustomFieldModel("<FILE_PATH>", "text/html", "Color Picker", "text");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Extension().UploadAsync(model);
Console.WriteLine(response.OpenJsonObjectResponse()["extension"]?["uid"]);
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}Dashboard: upload a dashboard widget from bytes with a management token
using System;
using System.IO;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models.CustomExtension;
ContentstackClient client = new ContentstackClient();
byte[] html = File.ReadAllBytes("<FILE_PATH>");
DashboardWidgetModel model = new DashboardWidgetModel(html, "text/html", "Publishing Stats", true, "half", "reports");
try
{
ContentstackResponse response = await client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.Extension()
.UploadAsync(model);
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}