Environment

View as Markdown

Environment

Environment represents the publishing environments of a stack. A publishing environment is a deployment server or delivery destination that you publish entries and assets to.

When to Use This Class: Use this class when your code sets up or changes where content publishes, for example a new staging environment.

Conceptual Role: Acts as the Content Management API client for the /environments endpoint. Call stack.Environment() to get an instance.

Returns: Environment. A handle for environment operations.

Instance State

The name you pass to stack.Environment() decides which methods you can call:

  • Call stack.Environment() without a name to work with the collection, for example Query or Create.
  • Call stack.Environment("<ENVIRONMENT_NAME>") to work with one environment, for example Fetch or Delete.

A method from the other group throws before any request leaves the SDK. Query, Create, and CreateAsync throw InvalidOperationException on an instance with a name. The other methods throw ArgumentException on an instance without one. The Method Index below lists every method in each group.

Warning The SDK checks an empty string as if it were no name, but adds it to the path. stack.Environment("") allows Query and Create, and those requests go to /environments/ with a trailing slash. Pass null, or call stack.Environment() with no argument, when you mean the collection.

Warning Set the name only through stack.Environment("<ENVIRONMENT_NAME>"). The instance has a settable Uid property, but the SDK builds the request path when you call stack.Environment(). Setting Uid later changes which methods the SDK allows without changing which environment the request targets.

Class-Level Notes

Credentials.

  • stack.Environment() throws InvalidOperationException when the client has no authtoken and the stack has no management token.
  • Fetch, FetchAsync, Delete, DeleteAsync, CreateAsync, and UpdateAsync run the same check again before the request. The synchronous Create and Update do not repeat it.
  • The Content Management API reference accepts a management token or an authtoken for every environment request. Pass a management token as the second argument of client.Stack().

The environment name is the identifier.

  • The Content Management API identifies an environment by its name in the request path, /environments/<ENVIRONMENT_NAME>. Pass the name to stack.Environment().

Request bodies.

  • Create and Update send an EnvironmentModel inside an environment key. A property you leave null stays out of the body.
  • EnvironmentModel.DeployContent defaults to true, and the SDK always sends it. Set it on every Update to the value the environment keeps.

Query parameters.

  • Every method except Query takes an optional ParameterCollection. The SDK adds each entry to the query string of the request.

Rate Limiting & Retry.

  • This SDK automatically retries on 429 with configurable delay and attempt limits.

Additional Resource For more information on retry settings, refer to the ContentstackClientOptions documentation.

Properties

PropertyTypeAccessDefaultDescription
Uidstring?Read/writeThe argument of stack.Environment()The name the instance targets. Setting it later does not change the request path.

Method Index

The groups below follow the Instance State split.

Work with the collection. Available on stack.Environment() with no name.

Method NameReturnsDescription
QueryA new query for environments.Builds a query that lists environments.
CreateThe API response with the created environment.Adds an environment to the stack.
CreateAsyncThe API response with the created environment.Adds an environment asynchronously.

Work with one environment. Available on stack.Environment("<ENVIRONMENT_NAME>").

Method NameReturnsDescription
FetchThe API response with the requested environment.Gets the details of the environment.
FetchAsyncThe API response with the requested environment.Gets the details asynchronously.
UpdateThe API response with the updated environment.Changes the details of the environment.
UpdateAsyncThe API response with the updated environment.Changes the details asynchronously.
DeleteThe API response with the deletion notice.Removes the environment from the stack.
DeleteAsyncThe API response with the deletion notice.Removes the environment asynchronously.

Class-Level Snippet

The snippet below adds a staging environment with a management token, fetches it by name, and lists every environment of the 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();
Stack stack = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>");

EnvironmentModel model = new EnvironmentModel()
{
    Name = "staging",
    Urls = new List<LocalesUrl>() { new LocalesUrl() { Locale = "en-us", Url = "https://staging.example.com" } }
};

try
{
    ContentstackResponse created = stack.Environment().Create(model);
    Console.WriteLine(created.OpenJsonObjectResponse().ToJsonString());

    ContentstackResponse fetched = stack.Environment("staging").Fetch();
    Console.WriteLine(fetched.OpenJsonObjectResponse().ToJsonString());

    ContentstackResponse all = stack.Environment().Query().Find();
    Console.WriteLine(all.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Methods

Each method of the Environment class has its own section below, with its parameters, validation rules, behavior, and examples.

Create

Create adds an environment to the stack.

NameTypeDescription
model (required)EnvironmentModel

Name, servers, and URLs of the new environment.

Default: Not applicable
collectionParameterCollection?

Query parameters to add to the request.

Default: null

Returns: ContentstackResponse. The API response with the created environment.

Validation

  • Throws InvalidOperationException if the instance has a name, because Create adds a new environment to the collection. Call stack.Environment() with no argument.
  • Throws ArgumentNullException if model is null, because the request body holds the model.
  • 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 /environments request with the body {"environment": {...}}. See Add an environment in the Content Management API reference.
  • Serializes Name, Servers, Urls, and DeployContent as name, servers, urls, and deploy_content. A property you leave null stays out of the body.
  • DeployContent is a bool with the default true, so the SDK always sends deploy_content.
  • The Content Management API reference asks for the environment name and its URLs, each one a language code and the URL of the server, in the body.
  • Adds each entry of collection to the query string.
  • Returns the raw API response with the created environment. To work with it, call stack.Environment("<ENVIRONMENT_NAME>") with its name.

Example

Basic usage: add an 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>");

EnvironmentModel model = new EnvironmentModel()
{
    Name = "production",
    Urls = new List<LocalesUrl>() { new LocalesUrl() { Locale = "en-us", Url = "https://www.example.com" } }
};

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Environment().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: add an environment with every model property and a query parameter, using a management token

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();

EnvironmentModel model = new EnvironmentModel()
{
    Name = "staging",
    Servers = new List<Server>() { new Server() { Name = "staging-server" } },
    Urls = new List<LocalesUrl>()
    {
        new LocalesUrl() { Locale = "en-us", Url = "https://staging.example.com" },
        new LocalesUrl() { Locale = "fr-fr", Url = "https://staging.example.com/fr" }
    },
    DeployContent = false
};

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Environment().Create(model, collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

CreateAsync

CreateAsync adds an environment to the stack, without blocking the calling thread.

NameTypeDescription
model (required)EnvironmentModel

Name, servers, and URLs of the new environment.

Default: Not applicable
collectionParameterCollection?

Query parameters to add to the request.

Default: null

Returns: Task<ContentstackResponse>. The API response with the created environment.

Validation

  • Throws InvalidOperationException if the instance has a name, because Create adds a new environment to the collection. Call stack.Environment() with no argument.
  • Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
  • Throws ArgumentNullException if model is null, because the request body holds the model.
  • Throws ContentstackErrorException when the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Returns a task. The client-side checks above run when you call CreateAsync, before it returns the task. An API rejection surfaces when you await the task.
  • Runs the credential check again before the request. The synchronous Create relies on the check that stack.Environment() ran.
  • Otherwise behaves like Create.

Example

Basic usage: add an 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>");

EnvironmentModel model = new EnvironmentModel()
{
    Name = "production",
    Urls = new List<LocalesUrl>() { new LocalesUrl() { Locale = "en-us", Url = "https://www.example.com" } }
};

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Environment().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: add an environment with every model property and a 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>");

EnvironmentModel model = new EnvironmentModel()
{
    Name = "staging",
    Servers = new List<Server>() { new Server() { Name = "staging-server" } },
    Urls = new List<LocalesUrl>()
    {
        new LocalesUrl() { Locale = "en-us", Url = "https://staging.example.com" },
        new LocalesUrl() { Locale = "fr-fr", Url = "https://staging.example.com/fr" }
    },
    DeployContent = false
};

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Environment().CreateAsync(model, collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Delete

Delete removes the environment whose name you passed to stack.Environment() from the stack.

NameTypeDescription
collectionParameterCollection?

Query parameters to add to the request.

Default: null

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 ArgumentException if the instance has no name, because Delete acts on one environment. Call stack.Environment("<ENVIRONMENT_NAME>").
  • 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 /environments/<ENVIRONMENT_NAME> request. See Delete environment in the Content Management API reference.
  • Adds each entry of collection to the query string.
  • Returns the raw API response with the deletion notice.

Example

Warning Delete removes the publishing environment from the stack. After that, you can no longer publish entries or assets to it.

Basic usage: delete an environment

using System;
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>").Environment("<ENVIRONMENT_NAME>").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 with a query parameter, using 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();

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Environment("<ENVIRONMENT_NAME>").Delete(collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

DeleteAsync

DeleteAsync removes the environment whose name you passed to stack.Environment() from the stack, without blocking the calling thread.

NameTypeDescription
collectionParameterCollection?

Query parameters to add to the request.

Default: null

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 ArgumentException if the instance has no name, because Delete acts on one environment. Call stack.Environment("<ENVIRONMENT_NAME>").
  • Throws ContentstackErrorException when the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Returns a task. The client-side checks above run when you call DeleteAsync, before it returns the task. An API rejection surfaces when you await the task.
  • Otherwise behaves like Delete.

Example

Warning Delete removes the publishing environment from the stack. After that, you can no longer publish entries or assets to it.

Basic usage: delete an environment

using System;
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>").Environment("<ENVIRONMENT_NAME>").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 with a query parameter

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("<AUTHTOKEN>");

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Environment("<ENVIRONMENT_NAME>").DeleteAsync(collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Fetch

Fetch gets the details of the environment whose name you passed to stack.Environment().

NameTypeDescription
collectionParameterCollection?

Query parameters to add to the request.

Default: null

Returns: ContentstackResponse. The API response with the requested environment.

Validation

  • Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
  • Throws ArgumentException if the instance has no name, because Fetch acts on one environment. Call stack.Environment("<ENVIRONMENT_NAME>").
  • 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 /environments/<ENVIRONMENT_NAME> request. See Get a single environment in the Content Management API reference.
  • Adds each entry of collection to the query string.
  • Returns the raw API response with the environment. Read the body with OpenJsonObjectResponse().

Example

Basic usage: fetch an environment

using System;
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>").Environment("<ENVIRONMENT_NAME>").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 with a query parameter, using 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();

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Environment("<ENVIRONMENT_NAME>").Fetch(collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Edge case: fetch on an instance with no name

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Environment().Fetch();
}
catch (ArgumentException e)
{
    // Thrown because stack.Environment() received no name
    Console.WriteLine(e.Message);
}

FetchAsync

FetchAsync gets the details of the environment whose name you passed to stack.Environment(), without blocking the calling thread.

NameTypeDescription
collectionParameterCollection?

Query parameters to add to the request.

Default: null

Returns: Task<ContentstackResponse>. The API response with the requested environment.

Validation

  • Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
  • Throws ArgumentException if the instance has no name, because Fetch acts on one environment. Call stack.Environment("<ENVIRONMENT_NAME>").
  • Throws ContentstackErrorException when the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Returns a task. The client-side checks above run when you call FetchAsync, before it returns the task. An API rejection surfaces when you await the task.
  • Otherwise behaves like Fetch.

Example

Basic usage: fetch an environment

using System;
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>").Environment("<ENVIRONMENT_NAME>").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 with a query parameter

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("<AUTHTOKEN>");

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Environment("<ENVIRONMENT_NAME>").FetchAsync(collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Query

Query creates a query that lists the environments of the stack.

This method takes no parameters.

Returns: Query. A new query for environments.

Validation

  • Throws InvalidOperationException if the instance has a name, because Query works with the whole collection. Call stack.Environment() with no argument.
  • Errors from the API come from the Find or FindAsync call that follows, not from Query.

Behavior

  • Sends no request. Find or FindAsync on the returned query sends one GET /environments request. See Get all environments in the Content Management API reference.
  • The Content Management API reference lists include_count, asc, and desc for this request. Chain IncludeCount for the count, and pass asc or desc in the ParameterCollection you give to Find.
  • The query keeps every value you add. Create a new query with stack.Environment().Query() for a different request.

Example

Basic usage: list all environments

using System;
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>").Environment().Query().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}");
}

List environments with a count and extra query parameters, using 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();

ParameterCollection collection = new ParameterCollection();
collection.Add("asc", "<FIELD_UID>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Environment().Query().IncludeCount().Find(collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Update

Update changes the details of the environment whose name you passed to stack.Environment().

NameTypeDescription
model (required)EnvironmentModel

New details of the environment.

Default: Not applicable
collectionParameterCollection?

Query parameters to add to the request.

Default: null

Returns: ContentstackResponse. The API response with the updated environment.

Validation

  • Throws ArgumentException if the instance has no name, because Update acts on one environment. Call stack.Environment("<ENVIRONMENT_NAME>").
  • Throws ArgumentNullException if model is null, because the request body holds the model.
  • 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 /environments/<ENVIRONMENT_NAME> request with the body {"environment": {...}}. See Update environment in the Content Management API reference.
  • Serializes Name, Servers, Urls, and DeployContent as name, servers, urls, and deploy_content. A property you leave null stays out of the body.
  • DeployContent is a bool with the default true, so every update sends deploy_content. Set it to the value the environment keeps, including false.
  • The Content Management API reference lets you change the environment name and its URLs. After a rename, this object still targets the old name. Call stack.Environment("<NEW_NAME>") for later requests.
  • Adds each entry of collection to the query string.

Example

Basic usage: update an 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>");

EnvironmentModel model = new EnvironmentModel()
{
    Name = "<ENVIRONMENT_NAME>",
    Urls = new List<LocalesUrl>() { new LocalesUrl() { Locale = "en-us", Url = "https://www.example.org" } }
};

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").Environment("<ENVIRONMENT_NAME>").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: update with every model property and a 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();

EnvironmentModel model = new EnvironmentModel()
{
    Name = "production-eu",
    Servers = new List<Server>() { new Server() { Name = "eu-server" } },
    Urls = new List<LocalesUrl>() { new LocalesUrl() { Locale = "en-us", Url = "https://eu.example.com" } },
    DeployContent = false
};

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Environment("<ENVIRONMENT_NAME>").Update(model, collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

UpdateAsync

UpdateAsync changes the details of the environment whose name you passed to stack.Environment(), without blocking the calling thread.

NameTypeDescription
model (required)EnvironmentModel

New details of the environment.

Default: Not applicable
collectionParameterCollection?

Query parameters to add to the request.

Default: null

Returns: Task<ContentstackResponse>. The API response with the updated environment.

Validation

  • Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
  • Throws ArgumentException if the instance has no name, because Update acts on one environment. Call stack.Environment("<ENVIRONMENT_NAME>").
  • Throws ArgumentNullException if model is null, because the request body holds the model.
  • Throws ContentstackErrorException when the API rejects the request.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Returns a task. The client-side checks above run when you call UpdateAsync, before it returns the task. An API rejection surfaces when you await the task.
  • Runs the credential check again before the request. The synchronous Update relies on the check that stack.Environment() ran.
  • Otherwise behaves like Update.

Example

Basic usage: update an 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>");

EnvironmentModel model = new EnvironmentModel()
{
    Name = "<ENVIRONMENT_NAME>",
    Urls = new List<LocalesUrl>() { new LocalesUrl() { Locale = "en-us", Url = "https://www.example.org" } }
};

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Environment("<ENVIRONMENT_NAME>").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: update with every model property and a 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>");

EnvironmentModel model = new EnvironmentModel()
{
    Name = "production-eu",
    Servers = new List<Server>() { new Server() { Name = "eu-server" } },
    Urls = new List<LocalesUrl>() { new LocalesUrl() { Locale = "en-us", Url = "https://eu.example.com" } },
    DeployContent = false
};

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Environment("<ENVIRONMENT_NAME>").UpdateAsync(model, collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}