GlobalField
GlobalField
GlobalField creates, fetches, lists, updates, and deletes the global fields of a stack. A global field is a reusable field, or group of fields, that you define once and add to many content types.
When to Use This Class: Use this class when several content types share the same set of fields. An SEO group with a meta title and a meta description is a typical example.
Conceptual Role: Acts as the Content Management API (CMA) client for the /global_fields endpoint. Call stack.GlobalField() to get an instance, and describe the schema with a ContentModelling object.
Returns: GlobalField. A handle for global field operations.
Instance State
The UID you pass to stack.GlobalField() decides which methods you can call on the instance:
- Call stack.GlobalField() without a UID to work with the global field collection, for example Query or Create.
- Call stack.GlobalField("<GLOBAL_FIELD_UID>") to work with one global field, for example Fetch or Delete.
- Optionally pass an API version as the second argument, stack.GlobalField("<GLOBAL_FIELD_UID>", "<API_VERSION>"), or by name, stack.GlobalField(apiVersion: "<API_VERSION>"). The instance sends it with every request, as the Class-Level Notes below describe.
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-item method on an instance with no UID throws ArgumentException.
The Method Index below lists every method in each group.
Warning stack.GlobalField() takes two optional strings, and the first one is the UID. stack.GlobalField("<API_VERSION>") sets the UID, not the API version, and then Query and Create throw InvalidOperationException. Name the argument, as in stack.GlobalField(apiVersion: "<API_VERSION>"), when you pass only the version.
Warning The SDK checks for an empty string as if it were no UID, so stack.GlobalField("") allows Query and Create, and the SDK then sends the request to /global_fields/ with a trailing slash. Pass null, or call stack.GlobalField() with no UID, when you mean the collection.
Class-Level Notes
Authentication.
- stack.GlobalField() 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 global field request. When the Stack has a management token, the SDK sends it instead of the client's authtoken.
- Only the stack owner, administrators, and developers can create a global field.
API version.
- When you pass apiVersion to stack.GlobalField(), every request of the instance, including the Find call of Query, carries an api_version header with that value. Without it, the SDK sends no api_version header.
- The SDK sends the value you pass without checking it. Use the API version that the API expects for nested global fields, for example a global field that contains another global field.
Request body.
- Create and Update serialize the ContentModelling object under the global_field key. The SDK leaves out every property that is null.
- A nested global field is a schema entry of type GlobalFieldReference. List the nested global fields in ContentModelling.GlobalFieldRefs, as the GlobalFieldRefs page describes.
Branch scoping.
- Global field 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 Global Fields section of the Content Management API reference.
Capability Matrix
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Nest a global field inside another global field | Yes | Add a GlobalFieldReference to the schema and pass an API version to stack.GlobalField(). |
| List the content types that use a global field | Yes | Pass include_content_types set to true in the collection of Fetch. |
| Delete a global field that a content type uses | Yes | Pass force set to true in the collection of Delete. |
| Export or import a global field as a JSON file | No | The CMA has export and import requests, and this SDK has no method for them. Fetch the global field and create it in the other stack instead. |
Method Index
Work with the global field collection. Available on stack.GlobalField() when you pass no UID.
| Method Name | Returns | Description |
|---|---|---|
| Query | A new query for global fields. | Builds a query that lists global fields. |
| Create | The API response with the created global field. | Creates a global field from a schema. |
| CreateAsync | The API response with the created global field. | Creates a global field from a schema asynchronously. |
Work with one global field. Available on stack.GlobalField("<GLOBAL_FIELD_UID>").
| Method Name | Returns | Description |
|---|---|---|
| Fetch | The API response with the requested global field. | Retrieves one global field. |
| FetchAsync | The API response with the requested global field. | Retrieves one global field asynchronously. |
| Update | The API response with the updated global field. | Replaces the schema of a global field. |
| UpdateAsync | The API response with the updated global field. | Replaces the schema of a global field asynchronously. |
| Delete | The API response with the deletion notice. | Deletes a global field. |
| DeleteAsync | The API response with the deletion notice. | Deletes a global field asynchronously. |
Class-Level Snippet
The snippet below creates an SEO global field, adds it to a Blog Post content type, and fetches the global field with the content types that use it.
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Models.Fields;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Stack stack = client.Stack("<API_KEY>");
ContentModelling seo = new ContentModelling
{
Title = "SEO",
Uid = "seo",
Schema = new List<Field>
{
new TextboxField { DisplayName = "Meta Title", Uid = "meta_title", DataType = "text" },
new TextboxField { DisplayName = "Meta Description", Uid = "meta_description", DataType = "text" }
}
};
ContentModelling blogPost = new ContentModelling
{
Title = "Blog Post",
Uid = "blog_post",
Schema = new List<Field>
{
new TextboxField { DisplayName = "Title", Uid = "title", DataType = "text", Mandatory = true, Unique = true },
new GlobalFieldReference { DisplayName = "SEO", Uid = "seo", DataType = "global_field", ReferenceTo = "seo" }
}
};
ParameterCollection collection = new ParameterCollection();
collection.Add("include_content_types", true);
try
{
await stack.GlobalField().CreateAsync(seo);
await stack.ContentType().CreateAsync(blogPost);
ContentstackResponse response = await stack.GlobalField("seo").FetchAsync(collection);
Console.WriteLine(response.OpenJsonObjectResponse()["global_field"]?.ToJsonString());
}
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 GlobalField class has its own section below, with its parameters, validation rules, behavior, and examples.
Create
Create creates a global field in the stack from the schema in a ContentModelling object.
| Name | Type | Description |
|---|---|---|
| model (required) | ContentModelling | Title, UID, and schema of the new global field. |
| collection | ParameterCollection? | Adds query parameters, for example include_branch. |
Returns: ContentstackResponse. The API response with the created global field.
Validation
- Throws InvalidOperationException if the instance has a UID, because Create adds a new global field to the collection. Call stack.GlobalField() with no UID, and set the UID of the new global field in model.Uid.
- Throws ArgumentNullException (parameter dataModel) if model is null, before any request.
- The SDK does not check model. A missing title, a duplicate UID, or an invalid field reaches the API, and the SDK throws the API rejection as ContentstackErrorException. Read e.Errors for the field that the API rejected.
- 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 POST request to /global_fields with the body {"global_field": <model>}. The SDK leaves out every ContentModelling property that is null. When you pass apiVersion to stack.GlobalField(), the request also carries the api_version header.
- The Create a global field request of the Content Management API reference describes the schema, including nested global fields. Only the stack owner, administrators, and developers can create a global field.
- To nest another global field, add a GlobalFieldReference to model.Schema and list it in model.GlobalFieldRefs.
- Returns the raw API response. The new global field sits under the global_field key.
Example
Basic usage: create an SEO global field
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Models.Fields;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ContentModelling model = new ContentModelling
{
Title = "SEO",
Uid = "seo",
Schema = new List<Field>
{
new TextboxField { DisplayName = "Meta Title", Uid = "meta_title", DataType = "text" },
new TextboxField { DisplayName = "Meta Description", Uid = "meta_description", DataType = "text" }
}
};
try
{
ContentstackResponse response = client.Stack("<API_KEY>").GlobalField().Create(model);
Console.WriteLine(response.OpenJsonObjectResponse()["global_field"]?["uid"]);
}
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 nested global field with an API version and 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.Models.Fields;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
ContentModelling model = new ContentModelling
{
Title = "Page Header",
Uid = "page_header",
Description = "Heading and SEO fields shared by landing pages",
Schema = new List<Field>
{
new TextboxField { DisplayName = "Heading", Uid = "heading", DataType = "text" },
new GlobalFieldReference { DisplayName = "SEO", Uid = "seo", DataType = "global_field", ReferenceTo = "seo" }
},
GlobalFieldRefs = new List<GlobalFieldRefs>
{
new GlobalFieldRefs { Uid = "seo", OccurrenceCount = 1, IsChild = true, Paths = new List<string> { "schema.1" } }
}
};
ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);
try
{
ContentstackResponse response = client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.GlobalField(apiVersion: "<API_VERSION>")
.Create(model, collection);
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Edge case: passing only the API version positionally
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ContentModelling model = new ContentModelling { Title = "SEO", Uid = "seo" };
try
{
// The first argument is the UID, so this instance has a UID and Create throws.
client.Stack("<API_KEY>").GlobalField("<API_VERSION>").Create(model);
}
catch (InvalidOperationException e)
{
// Fires before any request. Use GlobalField(apiVersion: "<API_VERSION>") instead.
Console.WriteLine(e.Message);
}CreateAsync
CreateAsync creates a global field in the stack from the schema in a ContentModelling object, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| model (required) | ContentModelling | Title, UID, and schema of the new global field. |
| collection | ParameterCollection? | Adds query parameters, for example include_branch. |
Returns: Task<ContentstackResponse>. The API response with the created global field.
Validation
- Throws InvalidOperationException if the instance has a UID, because CreateAsync adds a new global field to the collection. Call stack.GlobalField() 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 an SEO global field
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Models.Fields;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ContentModelling model = new ContentModelling
{
Title = "SEO",
Uid = "seo",
Schema = new List<Field>
{
new TextboxField { DisplayName = "Meta Title", Uid = "meta_title", DataType = "text" },
new TextboxField { DisplayName = "Meta Description", Uid = "meta_description", DataType = "text" }
}
};
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").GlobalField().CreateAsync(model);
Console.WriteLine(response.OpenJsonObjectResponse()["global_field"]?["uid"]);
}
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 nested global field with an API version and 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.Models.Fields;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
ContentModelling model = new ContentModelling
{
Title = "Page Header",
Uid = "page_header",
Description = "Heading and SEO fields shared by landing pages",
Schema = new List<Field>
{
new TextboxField { DisplayName = "Heading", Uid = "heading", DataType = "text" },
new GlobalFieldReference { DisplayName = "SEO", Uid = "seo", DataType = "global_field", ReferenceTo = "seo" }
},
GlobalFieldRefs = new List<GlobalFieldRefs>
{
new GlobalFieldRefs { Uid = "seo", OccurrenceCount = 1, IsChild = true, Paths = new List<string> { "schema.1" } }
}
};
ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);
try
{
ContentstackResponse response = await client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.GlobalField(apiVersion: "<API_VERSION>")
.CreateAsync(model, collection);
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Delete
Delete deletes the global field whose UID you passed to stack.GlobalField().
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters, for example force. |
Returns: ContentstackResponse. The API response with the deletion notice.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because Delete removes one global field. Call stack.GlobalField("<GLOBAL_FIELD_UID>").
- The SDK does not add force for you. collection set to null sends no query parameters.
- The API rejects the request if a content type uses the global field and the request has no force set to true. The SDK throws the rejection as ContentstackErrorException.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one DELETE request to /global_fields/<GLOBAL_FIELD_UID>, with the entries of collection as query parameters. When you pass apiVersion to stack.GlobalField(), the request also carries the api_version header.
- The Delete global field request of the Content Management API reference needs force set to true to delete a global field that a content type uses.
- Returns the raw API response with a notice key.
Warning Deleting a global field removes it from the stack. The SDK offers no way to restore it.
Example
Basic usage: delete a global field that no content type uses
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").GlobalField("<GLOBAL_FIELD_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}");
}All parameters: force the deletion of a global field that content types use, with 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("force", true);
try
{
ContentstackResponse response = client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.GlobalField("<GLOBAL_FIELD_UID>", "<API_VERSION>")
.Delete(collection);
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}DeleteAsync
DeleteAsync deletes the global field whose UID you passed to stack.GlobalField(), without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters, for example force. |
Returns: Task<ContentstackResponse>. The API response with the deletion notice.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because DeleteAsync removes one global field. Call stack.GlobalField("<GLOBAL_FIELD_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 a global field removes it from the stack. The SDK offers no way to restore it.
Example
Basic usage: delete a global field that no content type uses
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").GlobalField("<GLOBAL_FIELD_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}");
}All parameters: force the deletion of a global field that content types use, with 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("force", true);
try
{
ContentstackResponse response = await client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.GlobalField("<GLOBAL_FIELD_UID>", "<API_VERSION>")
.DeleteAsync(collection);
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Fetch
Fetch retrieves the global field whose UID you passed to stack.GlobalField(), including its schema.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters, for example include_content_types. |
Returns: ContentstackResponse. The API response with the requested global field.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because Fetch reads one global field. Call stack.GlobalField("<GLOBAL_FIELD_UID>").
- The SDK does not check the UID format. A UID that names no global field 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 /global_fields/<GLOBAL_FIELD_UID>, with the entries of collection as query parameters. When you pass apiVersion to stack.GlobalField(), the request also carries the api_version header.
- The Get a single global field request of the Content Management API reference accepts these query parameters:
- version returns that version of the global field.
- include_global_field_schema adds the schema of nested global fields.
- include_content_types and include_global_fields add the content types and global fields that use this global field.
- include_branch adds the _branch key.
- Returns the raw API response. The global field sits under the global_field key. Deserialize that node into a ContentModelling object with client.SerializerOptions to read it as typed fields.
Example
Basic usage: fetch a global field 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>").GlobalField("<GLOBAL_FIELD_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 with the content types that use it, an API version, and 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_content_types", true);
collection.Add("include_global_field_schema", true);
try
{
ContentstackResponse response = client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.GlobalField("<GLOBAL_FIELD_UID>", "<API_VERSION>")
.Fetch(collection);
Console.WriteLine(response.OpenJsonObjectResponse()["global_field"]?.ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Typed result: read the schema into ContentModelling
using System;
using System.Text.Json;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Models.Fields;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").GlobalField("<GLOBAL_FIELD_UID>").Fetch();
ContentModelling? model = response.OpenJsonObjectResponse()["global_field"]?.Deserialize<ContentModelling>(client.SerializerOptions);
foreach (Field field in model?.Schema ?? new())
{
Console.WriteLine($"{field.Uid}: {field.DataType}");
}
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}FetchAsync
FetchAsync retrieves the global field whose UID you passed to stack.GlobalField(), including its schema, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters, for example include_content_types. |
Returns: Task<ContentstackResponse>. The API response with the requested global field.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because FetchAsync reads one global field. Call stack.GlobalField("<GLOBAL_FIELD_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 a global field 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>").GlobalField("<GLOBAL_FIELD_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 with the content types that use it, an API version, and 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_content_types", true);
collection.Add("include_global_field_schema", true);
try
{
ContentstackResponse response = await client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.GlobalField("<GLOBAL_FIELD_UID>", "<API_VERSION>")
.FetchAsync(collection);
Console.WriteLine(response.OpenJsonObjectResponse()["global_field"]?.ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Query
Query returns a query object that lists the global fields in the stack when you call Find or FindAsync on it.
This method takes no parameters.
Returns: Query. A new query for global fields.
Validation
- Throws InvalidOperationException if the instance has a UID, because Query lists the global field collection. Call stack.GlobalField() 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 /global_fields. The request carries the parameters from Limit, Skip, IncludeCount, and the collection argument of Find. See the Query class for those methods.
- The query keeps the API version of the instance. When you pass apiVersion to stack.GlobalField(), Find sends it as the api_version header.
- The Get all global fields request of the Content Management API reference accepts these query parameters:
- include_count adds the total number of global fields.
- include_global_field_schema adds the schema of nested global fields.
- include_content_types and include_global_fields add the content types and global fields that use each global field.
- deleted set to true returns only deleted global fields.
- include_branch adds the _branch key.
- Returns the raw API response. The global fields sit under the global_fields 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 global fields in a stack
using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").GlobalField().Query().Find();
JsonArray? globalFields = response.OpenJsonObjectResponse()["global_fields"]?.AsArray();
foreach (JsonNode? globalField in globalFields ?? new JsonArray())
{
Console.WriteLine($"{globalField?["uid"]}: {globalField?["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 with a count, the content types that use each global field, and an API version
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_content_types", true);
try
{
ContentstackResponse response = await client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.GlobalField(apiVersion: "<API_VERSION>")
.Query()
.Limit(10)
.Skip(0)
.IncludeCount()
.FindAsync(collection);
Console.WriteLine($"Total global fields: {response.OpenJsonObjectResponse()["count"]}");
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Update
Update replaces the schema of the global field whose UID you passed to stack.GlobalField().
| Name | Type | Description |
|---|---|---|
| model (required) | ContentModelling | The complete new schema of the global field. |
| collection | ParameterCollection? | Adds query parameters, for example include_branch. |
Returns: ContentstackResponse. The API response with the updated global field.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because Update changes one global field. Call stack.GlobalField("<GLOBAL_FIELD_UID>").
- Throws ArgumentNullException (parameter dataModel) if model is null, before any request.
- The SDK does not check model. An invalid schema 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 /global_fields/<GLOBAL_FIELD_UID> with the body {"global_field": <model>}. The SDK leaves out every ContentModelling property that is null. When you pass apiVersion to stack.GlobalField(), the request also carries the api_version header.
- The Update a global field request of the Content Management API reference updates the schema of the global field. Send every field you want to keep, not only the changed ones.
- Returns the raw API response. The updated global field sits under the global_field key.
Warning The schema you send replaces the stored schema, so the global field loses every field that you leave out of model.Schema. Fetch the global field first and change the fetched schema.
Example
Basic usage: add a field to an SEO global field
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Models.Fields;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ContentModelling model = new ContentModelling
{
Title = "SEO",
Uid = "seo",
Schema = new List<Field>
{
new TextboxField { DisplayName = "Meta Title", Uid = "meta_title", DataType = "text" },
new TextboxField { DisplayName = "Meta Description", Uid = "meta_description", DataType = "text" },
new TextboxField { DisplayName = "Canonical URL", Uid = "canonical_url", DataType = "text" }
}
};
try
{
ContentstackResponse response = client.Stack("<API_KEY>").GlobalField("seo").Update(model);
Console.WriteLine(response.OpenJsonObjectResponse()["global_field"]?["schema"]?.AsArray().Count);
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: update a nested global field with an API version and 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.Models.Fields;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
ContentModelling model = new ContentModelling
{
Title = "Page Header",
Uid = "page_header",
Description = "Heading and SEO fields shared by landing pages",
Schema = new List<Field>
{
new TextboxField { DisplayName = "Heading", Uid = "heading", DataType = "text" },
new GlobalFieldReference { DisplayName = "SEO", Uid = "seo", DataType = "global_field", ReferenceTo = "seo" }
},
GlobalFieldRefs = new List<GlobalFieldRefs>
{
new GlobalFieldRefs { Uid = "seo", OccurrenceCount = 1, IsChild = true, Paths = new List<string> { "schema.1" } }
}
};
ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);
try
{
ContentstackResponse response = client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.GlobalField("page_header", "<API_VERSION>")
.Update(model, collection);
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}UpdateAsync
UpdateAsync replaces the schema of the global field whose UID you passed to stack.GlobalField(), without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| model (required) | ContentModelling | The complete new schema of the global field. |
| collection | ParameterCollection? | Adds query parameters, for example include_branch. |
Returns: Task<ContentstackResponse>. The API response with the updated global field.
Validation
- Throws ArgumentException (parameter uid) if the instance has no UID or an empty string, because UpdateAsync changes one global field. Call stack.GlobalField("<GLOBAL_FIELD_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.
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.
- Otherwise behaves like Update.
Example
Basic usage: add a field to an SEO global field
using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Models.Fields;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ContentModelling model = new ContentModelling
{
Title = "SEO",
Uid = "seo",
Schema = new List<Field>
{
new TextboxField { DisplayName = "Meta Title", Uid = "meta_title", DataType = "text" },
new TextboxField { DisplayName = "Meta Description", Uid = "meta_description", DataType = "text" },
new TextboxField { DisplayName = "Canonical URL", Uid = "canonical_url", DataType = "text" }
}
};
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").GlobalField("seo").UpdateAsync(model);
Console.WriteLine(response.OpenJsonObjectResponse()["global_field"]?["schema"]?.AsArray().Count);
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: update a nested global field with an API version and 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.Models.Fields;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient();
ContentModelling model = new ContentModelling
{
Title = "Page Header",
Uid = "page_header",
Description = "Heading and SEO fields shared by landing pages",
Schema = new List<Field>
{
new TextboxField { DisplayName = "Heading", Uid = "heading", DataType = "text" },
new GlobalFieldReference { DisplayName = "SEO", Uid = "seo", DataType = "global_field", ReferenceTo = "seo" }
},
GlobalFieldRefs = new List<GlobalFieldRefs>
{
new GlobalFieldRefs { Uid = "seo", OccurrenceCount = 1, IsChild = true, Paths = new List<string> { "schema.1" } }
}
};
ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);
try
{
ContentstackResponse response = await client
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
.GlobalField("page_header", "<API_VERSION>")
.UpdateAsync(model, collection);
Console.WriteLine(response.OpenJsonObjectResponse()["notice"]);
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}