Branch
Branch
The Branch class creates, fetches, lists, and deletes the branches of a stack.
When to Use This Class: Use this class when your code creates or removes an isolated copy of stack content, for example a branch for a test run.
Conceptual Role: Acts as the Content Management API (CMA) client for the /stacks/branches endpoint. Call stack.Branch() to get an instance.
Returns: Branch. An object for branch operations.
Instance State
The UID you pass to stack.Branch() decides which methods you can call on the instance:
- Call stack.Branch() without a UID to work with the branch collection, for example Create or Query.
- Call stack.Branch("<BRANCH_UID>") to work with one branch, for example Fetch or Delete.
If you call a method from the other group, it throws before any request leaves the SDK. A collection method on an instance that has a UID throws InvalidOperationException, and a single-branch method on an instance with no UID throws ArgumentException. The Method Index below lists every method in each group.
Warning The SDK treats an empty string as no UID for its checks, but still adds it to the request path. stack.Branch("") allows Create and Query, which then send their requests to /stacks/branches/ with a trailing slash. Call stack.Branch() with no argument when you mean the collection.
Warning Set the branch UID only through stack.Branch("<BRANCH_UID>"). The instance also has a settable Uid property, but the SDK builds the request path when you call stack.Branch(). Setting Uid later changes which methods the SDK allows without changing which branch the request targets.
Class-Level Notes
Authentication.
- stack.Branch() throws InvalidOperationException when the client has no authtoken and the stack has no management token.
- The CMA reference accepts only an authtoken for Create and Delete. When the stack has a management token, the SDK sends it instead of the authtoken. Create the stack without a management token before you call Create or Delete.
The branch UID comes from the instance.
- Every method sends its request to /stacks/branches or /stacks/branches/<BRANCH_UID>, using the UID you passed to stack.Branch().
- The branchUid argument of client.Stack() adds a branch header to every request from that stack. Branch methods act on the UID in the request path, so the header does not change which branch they fetch or delete.
The API creates a branch in the background.
- Create returns as soon as the API accepts the request. The API then copies the source branch content into the new branch.
- Until the copy finishes, Fetch and Delete on the new branch fail with 422. Retry those calls with a delay in your own code. The CreateAsync page shows a retry loop.
Capability Matrix
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Rename or update a branch | No | The CMA reference lists no update request. Update and UpdateAsync exist through inheritance. Create a new branch instead. |
| Select the environments a new branch clones | Yes (version 1.2.0 or later) | Set BranchModel.PublishConfig to a BranchPublishConfigModel that lists environment names. See the Create method. |
| Compare or merge branches | No | The SDK has no method for the CMA compare and merge requests. |
| Create, update, or delete a branch alias | No | BranchModel.Alias lists the aliases of a fetched branch, and nothing in this SDK changes them. |
| Delete a branch that another branch uses as its source | No | Delete the child branches first. |
Method Index
Work with the branch collection. Available on stack.Branch() when you pass no UID.
| Method Name | Returns | Description |
|---|---|---|
| Query | A new query for branches. | Builds a query that lists branches. |
| Create | The API response with the created branch. | Creates a branch from a source branch. |
| CreateAsync | The API response with the created branch. | Creates a branch from a source branch asynchronously. |
Work with one branch. Available on stack.Branch("<BRANCH_UID>").
| Method Name | Returns | Description |
|---|---|---|
| Fetch | The API response with the requested branch. | Retrieves one branch. |
| FetchAsync | The API response with the requested branch. | Retrieves one branch asynchronously. |
| Delete | The API response with the deletion notice. | Deletes a branch and all its content. |
| DeleteAsync | The API response with the deletion notice. | Deletes a branch and all its content asynchronously. |
| Update | The API response for the update request. | Sends a PUT request that the CMA reference does not document. |
| UpdateAsync | The API response for the update request. | Sends a PUT request that the CMA reference does not document, asynchronously. |
Class-Level Snippet
This snippet creates a branch from main, counts the branches in the stack, and deletes an older branch.
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Stack stack = client.Stack("<API_KEY>");
try
{
// Branch UIDs are lowercase, use "_" between words, and have at most 15 characters.
BranchModel model = new BranchModel() { Uid = "<BRANCH_UID>", Source = "main" };
await stack.Branch().CreateAsync(model);
ContentstackResponse list = await stack.Branch().Query().IncludeCount().FindAsync();
JsonObject branches = list.OpenJsonObjectResponse();
Console.WriteLine($"Branches in the stack: {branches["count"]}");
// The API deletes a branch only when the request carries force=true.
ParameterCollection force = new ParameterCollection();
force.Add("force", true);
await stack.Branch("<OLD_BRANCH_UID>").DeleteAsync(force);
}
catch (ContentstackErrorException e)
{
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}Methods
Each method of the Branch class has its own section below, with its parameters, validation rules, behavior, and examples.
Create
Create creates a branch from the source branch you name, and can limit which environments the new branch clones.
| Name | Type | Description |
|---|---|---|
| model (required) | BranchModel | Sets the new branch UID, its source branch, and the environments to clone. |
| collection | ParameterCollection? | Adds query parameters to the request. |
Returns: ContentstackResponse. The API response with the created branch.
Note BranchModel.PublishConfig requires version 1.2.0 or later of the .NET Management SDK.
Validation
- Throws InvalidOperationException if the instance has a UID, because Create posts to the branch collection. Call stack.Branch() with no UID.
- Throws ArgumentNullException (parameter dataModel) if model is null, because the SDK builds the request body from it.
- The SDK does not check the properties of model. The API validates them.
- The SDK sends PublishConfig.Environments unchanged, without checking the names or the list length.
- Throws ContentstackErrorException when the API rejects the request, for example a duplicate UID, an unknown source branch, or an environment name that does not exist in the stack.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one POST request to /stacks/branches, with model serialized under a branch key. See Create a branch in the Content Management API (CMA) reference.
- Leaves every null property of model out of the request body.
- Reads Uid, Source, and PublishConfig from model. The API sets CreatedBy, UpdatedBy, CreatedAt, UpdatedAt, and Alias, so leave them unset.
- PublishConfig.Environments decides which environments the API clones into the new branch, in one of the following three ways:
- A list of environment names, not UIDs, clones only those environments.
- An empty list clones no environments.
- When you leave PublishConfig unset, the SDK leaves publish_config out of the request, and the API clones all environments.
- The CMA reference allows only stack owners, admins, and developers to create a branch.
- The CMA reference accepts only an authtoken for this request. When the stack has a management token, the SDK sends it instead of the authtoken, so create the stack without one.
- Returns as soon as the API accepts the request. The API then copies the source branch content into the new branch, and Fetch and Delete on the new branch fail with 422 until the copy finishes.
- Adds the entries of collection to the query string. null or an empty collection adds none.
- Returns the raw API response. The new branch sits under the branch key.
Limitations
- Does not wait for the branch to be ready. Retry the Fetch method with a delay until it succeeds.
Example
Basic usage: create a branch from main
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>");
// Branch UIDs are lowercase, use "_" between words, and have at most 15 characters.
BranchModel model = new BranchModel()
{
Uid = "<BRANCH_UID>",
Source = "main"
};
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Branch().Create(model);
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 branch with a query parameter collection
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
// Branch UIDs are lowercase, use "_" between words, and have at most 15 characters.
BranchModel model = new BranchModel()
{
Uid = "<BRANCH_UID>",
Source = "main"
};
// The CMA reference lists no query parameters for this request. Add any parameter the API accepts.
ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Branch().Create(model, collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Clone selected environments: create a branch with only development and staging
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>");
// List the environments by name, not by UID
BranchModel model = new BranchModel()
{
Uid = "<BRANCH_UID>",
Source = "main",
PublishConfig = new BranchPublishConfigModel()
{
Environments = new List<string> { "development", "staging" }
}
};
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Branch().Create(model);
Console.WriteLine(response.OpenJsonObjectResponse()["branch"]?.ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: create a branch that clones no environments
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>");
// An empty list clones no environments. Leaving PublishConfig unset clones all of them.
BranchModel model = new BranchModel()
{
Uid = "<BRANCH_UID>",
Source = "main",
PublishConfig = new BranchPublishConfigModel() { Environments = new List<string>() }
};
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Branch().Create(model);
Console.WriteLine(response.OpenJsonObjectResponse()["branch"]?.ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: calling Create on an instance that has a UID
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>");
// Branch UIDs are lowercase, use "_" between words, and have at most 15 characters.
BranchModel model = new BranchModel()
{
Uid = "<BRANCH_UID>",
Source = "main"
};
try
{
// Create adds a new branch, so call it on Branch() with no UID.
client.Stack("<API_KEY>").Branch("<BRANCH_UID>").Create(model);
}
catch (InvalidOperationException e)
{
// Fires before any request, because the instance has a UID
Console.WriteLine(e.Message);
}CreateAsync
CreateAsync creates a branch from the source branch you name, and can limit which environments the new branch clones, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| model (required) | BranchModel | Sets the new branch UID, its source branch, and the environments to clone. |
| collection | ParameterCollection? | Adds query parameters to the request. |
Returns: Task<ContentstackResponse>. The API response with the created branch.
Note BranchModel.PublishConfig requires version 1.2.0 or later of the .NET Management SDK.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token, because the request needs credentials.
- Throws InvalidOperationException if the instance has a UID, because CreateAsync posts to the branch collection. Call stack.Branch() with no UID.
- Throws ArgumentNullException (parameter dataModel) if model is null, because the SDK builds the request body from it.
- The SDK does not check the properties of model. The API validates them.
- The SDK sends PublishConfig.Environments unchanged, without checking the names or the list length.
- The SDK throws the client-side exceptions above when you call CreateAsync, before it returns a task. An API rejection surfaces when you await the task.
- Throws ContentstackErrorException when the API rejects the request, for example a duplicate UID, an unknown source branch, or an environment name that does not exist in the stack.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Completes the task when the API responds.
- Otherwise behaves like Create.
Example
Basic usage: create a branch from main
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>");
// Branch UIDs are lowercase, use "_" between words, and have at most 15 characters.
BranchModel model = new BranchModel()
{
Uid = "<BRANCH_UID>",
Source = "main"
};
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Branch().CreateAsync(model);
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 branch with a query parameter collection
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
// Branch UIDs are lowercase, use "_" between words, and have at most 15 characters.
BranchModel model = new BranchModel()
{
Uid = "<BRANCH_UID>",
Source = "main"
};
// The CMA reference lists no query parameters for this request. Add any parameter the API accepts.
ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Branch().CreateAsync(model, collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: wait until the new branch is ready
using System;
using System.Collections.Generic;
using System.Net;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Stack stack = client.Stack("<API_KEY>");
// Branch UIDs are lowercase, use "_" between words, and have at most 15 characters.
BranchModel model = new BranchModel()
{
Uid = "<BRANCH_UID>",
Source = "main"
};
try
{
await stack.Branch().CreateAsync(model);
// The API copies content in the background and returns 422 until the copy finishes.
for (int attempt = 1; attempt <= 10; attempt++)
{
try
{
await stack.Branch("<BRANCH_UID>").FetchAsync();
Console.WriteLine("The branch is ready.");
break;
}
catch (ContentstackErrorException e) when (e.StatusCode == (HttpStatusCode)422 && attempt < 10)
{
await Task.Delay(TimeSpan.FromSeconds(2));
}
}
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Delete
Delete deletes one branch, together with all its content and the aliases that point to it.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters. Pass force set to true to confirm the deletion. |
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, because the request needs credentials.
- Throws ArgumentException (parameter uid) if the instance has no UID, because Delete removes one branch. Call stack.Branch("<BRANCH_UID>").
- The SDK does not add force=true for you. The Content Management API (CMA) reference marks force as required to confirm the deletion.
- The CMA reference states that the API rejects the request, even with force=true, if another branch uses this branch as its source. Delete the child branches first.
- The API rejects the request with 422 if you created the branch moments ago, because the API still copies content into it. Retry with a delay until the call succeeds.
- 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 /stacks/branches/<BRANCH_UID>. See Delete a branch in the CMA reference.
- Deletes the content of the branch and every alias that points to it, as the CMA reference states.
- The CMA reference accepts only an authtoken for this request. When the stack has a management token, the SDK sends it instead of the authtoken, so create the stack without one.
- Adds the entries of collection to the query string. null or an empty collection adds none.
- Returns the raw API response.
Warning Deleting a branch removes the branch, all its content, and the aliases that point to it. The SDK and the API offer no way to restore them.
Example
Basic usage: delete a branch
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
// The API deletes a branch only when the request carries force=true.
ParameterCollection collection = new ParameterCollection();
collection.Add("force", true);
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Branch("<BRANCH_UID>").Delete(collection);
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: confirm the deletion and add another query parameter
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
// The API deletes a branch only when the request carries force=true.
ParameterCollection collection = new ParameterCollection();
collection.Add("force", true);
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Branch("<BRANCH_UID>").Delete(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}DeleteAsync
DeleteAsync deletes one branch, together with all its content and the aliases that point to it, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters. Pass force set to true to confirm the deletion. |
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, because the request needs credentials.
- Throws ArgumentException (parameter uid) if the instance has no UID, because DeleteAsync removes one branch. Call stack.Branch("<BRANCH_UID>").
- The SDK does not add force=true for you. The Content Management API (CMA) reference marks force as required to confirm the deletion.
- The CMA reference states that the API rejects the request, even with force=true, if another branch uses this branch as its source. Delete the child branches first.
- The API rejects the request with 422 if you created the branch moments ago, because the API still copies content into it. Retry with a delay until the call succeeds.
- The SDK throws the client-side exceptions above when you call DeleteAsync, before it returns a task. An API rejection surfaces when you await the task.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Completes the task when the API responds.
- Otherwise behaves like Delete.
Warning Deleting a branch removes the branch, all its content, and the aliases that point to it. The SDK and the API offer no way to restore them.
Example
Basic usage: delete a branch
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
// The API deletes a branch only when the request carries force=true.
ParameterCollection collection = new ParameterCollection();
collection.Add("force", true);
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Branch("<BRANCH_UID>").DeleteAsync(collection);
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: confirm the deletion and add another query parameter
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
// The API deletes a branch only when the request carries force=true.
ParameterCollection collection = new ParameterCollection();
collection.Add("force", true);
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Branch("<BRANCH_UID>").DeleteAsync(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Fetch
Fetch retrieves the details of one branch, including its source branch and aliases.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters to the request. |
Returns: ContentstackResponse. The API response with the requested branch.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token, because the request needs credentials.
- Throws ArgumentException (parameter uid) if the instance has no UID, because Fetch reads one branch. Call stack.Branch("<BRANCH_UID>").
- The API rejects the request with 422 if you created the branch moments ago, because the API still copies content into it. Retry with a delay until the call succeeds.
- 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 /stacks/branches/<BRANCH_UID>. See Get a single branch in the Content Management API (CMA) reference.
- Adds the entries of collection to the query string. null or an empty collection adds none.
- Returns the raw API response. The branch sits under the branch key and holds the fields that BranchModel describes.
Example
Basic usage: fetch a branch by UID
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>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Branch("<BRANCH_UID>").Fetch();
Console.WriteLine(response.OpenJsonObjectResponse()["branch"]?["source"]);
}
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 branch with a query parameter collection
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
// The CMA reference lists no query parameters for this request. Add any parameter the API accepts.
ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Branch("<BRANCH_UID>").Fetch(collection);
Console.WriteLine(response.OpenJsonObjectResponse()["branch"]?["source"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Authentication: use a management token instead of an authtoken
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient();
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Branch("<BRANCH_UID>").Fetch();
Console.WriteLine(response.OpenJsonObjectResponse()["branch"]?["source"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: read the response into BranchModel
using System;
using System.Collections.Generic;
using System.Text.Json;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Branch("<BRANCH_UID>").Fetch();
// The branch sits under the "branch" key, so deserialize that node, not the whole body.
BranchModel? branch = response.OpenJsonObjectResponse()["branch"]?.Deserialize<BranchModel>();
Console.WriteLine($"{branch?.Uid} was created from {branch?.Source} at {branch?.CreatedAt}");
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}FetchAsync
FetchAsync retrieves the details of one branch, including its source branch and aliases, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters to the request. |
Returns: Task<ContentstackResponse>. The API response with the requested branch.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token, because the request needs credentials.
- Throws ArgumentException (parameter uid) if the instance has no UID, because FetchAsync reads one branch. Call stack.Branch("<BRANCH_UID>").
- The API rejects the request with 422 if you created the branch moments ago, because the API still copies content into it. Retry with a delay until the call succeeds.
- The SDK throws the client-side exceptions above when you call FetchAsync, before it returns a task. An API rejection surfaces when you await the task.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Completes the task when the API responds.
- Otherwise behaves like Fetch.
Example
Basic usage: fetch a branch by UID
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>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Branch("<BRANCH_UID>").FetchAsync();
Console.WriteLine(response.OpenJsonObjectResponse()["branch"]?["source"]);
}
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 branch with a query parameter collection
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
// The CMA reference lists no query parameters for this request. Add any parameter the API accepts.
ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Branch("<BRANCH_UID>").FetchAsync(collection);
Console.WriteLine(response.OpenJsonObjectResponse()["branch"]?["source"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Query
Query returns a query object that lists the branches of the stack when you call Find or FindAsync on it.
This method takes no parameters. Chain Limit, Skip, and IncludeCount on the query object, then call Find or FindAsync to send the request.
Returns: Query. A new query for branches.
Validation
- Throws InvalidOperationException if the instance has a UID, because Query lists the branch collection. Call stack.Branch() with no UID.
- Query sends no request. Errors that do occur come from the Find or FindAsync call that follows, not from Query.
- Find and FindAsync throw InvalidOperationException if the client has no authtoken and the stack has no management token, and ContentstackErrorException when the API rejects the request.
- Limit, Skip, and IncludeCount each add a query parameter to a dictionary that rejects duplicate keys. The SDK throws ArgumentException before any request in the following two cases:
- You chain the same method twice.
- The collection you pass to Find repeats a key that a chained method already set.
- A query object keeps its parameters after Find runs. A second Find call with a collection that repeats a key throws ArgumentException. Build a new query for each request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Find and FindAsync send one GET request to /stacks/branches, with every parameter you set in the query string. See Get all branches in the Content Management API (CMA) reference.
- Returns the raw API response. The branches sit under the branches key, and count holds the total when you call IncludeCount.
- Does not page through the results. Without Limit and Skip, the API applies its own page size. To read the next page, build a new query with a higher Skip value.
- The query object has the five methods below. See the Query class for details.
| Method | Returns | Description |
|---|---|---|
| Limit(double value) | Query | Sets the number of branches per page. |
| Skip(double value) | Query | Sets the number of branches to skip. |
| IncludeCount() | Query | Adds the total count to the response. |
| Find(ParameterCollection? collection = null) | ContentstackResponse | Sends the request. |
| FindAsync(ParameterCollection? collection = null) | Task<ContentstackResponse> | Sends the request without blocking the calling thread. |
Example
Basic usage: list the branches of a stack
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>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Branch().Query().Find();
Console.WriteLine(response.OpenJsonObjectResponse()["branches"]?.ToJsonString());
}
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 with a total count
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>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Branch()
.Query()
.Limit(10)
.Skip(0)
.IncludeCount()
.FindAsync();
Console.WriteLine($"Total: {response.OpenJsonObjectResponse()["count"]}");
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: setting a query parameter twice
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Query query = client.Stack("<API_KEY>").Branch().Query().Limit(5);
ParameterCollection collection = new ParameterCollection();
collection.Add("limit", 10);
try
{
// Limit(5) already set "limit", so adding it again fails.
query.Find(collection);
}
catch (ArgumentException e)
{
// Fires before any request, when a query parameter is set twice
Console.WriteLine(e.Message);
}Update
Update comes from the shared base class and sends a PUT request for one branch. The Content Management API (CMA) reference lists no request to update a branch.
| Name | Type | Description |
|---|---|---|
| model (required) | BranchModel | Sets the branch fields to send. |
| collection | ParameterCollection? | Adds query parameters to the request. |
Returns: ContentstackResponse. The API response for the update request.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID, because Update changes one branch. Call stack.Branch("<BRANCH_UID>").
- Throws ArgumentNullException (parameter dataModel) if model is null, because the SDK builds the request body 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 PUT request to /stacks/branches/<BRANCH_UID>, with model serialized under a branch key.
- Leaves every null property of model out of the request body.
- Branch inherits Update from the base class without changing it.
- The CMA reference lists no request to update or rename a branch. It lists get, create, delete, compare, and merge requests only.
- Adds the entries of collection to the query string. null or an empty collection adds none.
- Returns the raw API response.
Limitations
- Does not rename a branch or change its source through a documented API request. Create a new branch with the Create method instead.
Example
Basic usage: send an update request for a branch
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>");
BranchModel model = new BranchModel() { Source = "main" };
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Branch("<BRANCH_UID>").Update(model);
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: send an update request with a query parameter collection
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
BranchModel model = new BranchModel() { Source = "main" };
// The CMA reference lists no query parameters for this request. Add any parameter the API accepts.
ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").Branch("<BRANCH_UID>").Update(model, collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}UpdateAsync
UpdateAsync comes from the shared base class and sends a PUT request for one branch. The Content Management API (CMA) reference lists no request to update a branch, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| model (required) | BranchModel | Sets the branch fields to send. |
| collection | ParameterCollection? | Adds query parameters to the request. |
Returns: Task<ContentstackResponse>. The API response for the update request.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token, because the request needs credentials.
- Throws ArgumentException (parameter uid) if the instance has no UID, because UpdateAsync changes one branch. Call stack.Branch("<BRANCH_UID>").
- Throws ArgumentNullException (parameter dataModel) if model is null, because the SDK builds the request body from it.
- The SDK throws the client-side exceptions above when you call UpdateAsync, before it returns a task. An API rejection surfaces when you await the task.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Completes the task when the API responds.
- Otherwise behaves like Update.
Example
Basic usage: send an update request for a branch
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>");
BranchModel model = new BranchModel() { Source = "main" };
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Branch("<BRANCH_UID>").UpdateAsync(model);
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: send an update request with a query parameter collection
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
BranchModel model = new BranchModel() { Source = "main" };
// The CMA reference lists no query parameters for this request. Add any parameter the API accepts.
ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").Branch("<BRANCH_UID>").UpdateAsync(model, collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}