Global Fields

Fetch reads one global field by its UID.

Returns: Task<JsonObject>. The requested global field as a JSON object.

Validation

• Throws ArgumentException before the request if param holds a key that the instance already sends, because the SDK adds each query parameter once. The instance always sends environment, and sends include_branch or include_global_field_schema after the matching modifier.
• Throws GlobalFieldException if the request fails, for example for an unknown global field UID.
• Throws GlobalFieldException if the response has no global_field object, for example when the instance holds no UID.

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

Behavior

• Calls GET /global_fields/{global_field_uid} (Get a single global field) and makes one HTTP request per call.
• Returns the global_field object of the response as a JsonObject. There is no generic overload, so read the fields from the object or deserialize it yourself.
• Sends the environment, the values from IncludeBranch and IncludeGlobalFieldSchema, and every entry of param.
• param applies to this call only. The SDK does not store it on the instance.
• Sends the client headers and the headers from SetHeader. A header set on the instance replaces a client header of the same name.

Example

Basic usage: read a global field

using System;
using System.Text.Json.Nodes;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    JsonObject globalField = await client.GlobalField("<GLOBAL_FIELD_UID>").Fetch();
    Console.WriteLine($"{globalField["uid"]}: {globalField["title"]}");
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

All parameters: send extra query parameters

using System;
using System.Collections.Generic;
using System.Text.Json.Nodes;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    Dictionary<string, object> param = new Dictionary<string, object>
    {
        { "include_global_field_schema", "true" },
        { "include_branch", "true" }
    };

    JsonObject globalField = await client.GlobalField("<GLOBAL_FIELD_UID>").Fetch(param);
    Console.WriteLine($"{globalField["title"]} on branch {globalField["_branch"]}");
}
catch (ContentstackException e)
{
    Console.WriteLine(e.Message);
}

IncludeBranch adds the _branch key, the UID of the branch that holds the global field, to the response.

Returns: GlobalField. The same global field, for chaining.

Validation

• Throws ArgumentException if the instance already holds include_branch, because the SDK adds each query parameter once. This happens when you call IncludeBranch twice on one instance.
• Fetch also throws ArgumentException if its param dictionary repeats include_branch.
• An invalid value surfaces as a ContentstackException (or a subclass) when Fetch sends the request.

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

Behavior

• Client-side only. IncludeBranch stores include_branch and makes no request.
• Fetch sends the value, and the API adds the _branch top-level key to the response (Get a single global field).
• Does not choose the branch. The Branch option on ContentstackOptions sets the branch the SDK reads from.

Example

Basic usage: read a global field with its branch

using System;
using System.Text.Json.Nodes;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    JsonObject globalField = await client.GlobalField("<GLOBAL_FIELD_UID>")
        .IncludeBranch()
        .Fetch();
    Console.WriteLine($"{globalField["uid"]} is on branch {globalField["_branch"]}");
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

IncludeGlobalFieldSchema adds the schema of the global field to the response.

Returns: GlobalField. The same global field, for chaining.

Validation

• Throws ArgumentException if the instance already holds include_global_field_schema, because the SDK adds each query parameter once. This happens when you call IncludeGlobalFieldSchema twice on one instance.
• Fetch also throws ArgumentException if its param dictionary repeats include_global_field_schema.
• An invalid value surfaces as a ContentstackException (or a subclass) when Fetch sends the request.

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

Behavior

• Client-side only. IncludeGlobalFieldSchema stores include_global_field_schema and makes no request.
• Fetch sends the value, and the API adds the schema of the global field to the response (Get a single global field).

Example

Basic usage: read a global field with its schema

using System;
using System.Text.Json.Nodes;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

try
{
    JsonObject globalField = await client.GlobalField("<GLOBAL_FIELD_UID>")
        .IncludeGlobalFieldSchema()
        .Fetch();
    JsonArray schema = globalField["schema"]?.AsArray() ?? new JsonArray();
    Console.WriteLine($"{globalField["title"]} has {schema.Count} fields");
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

RemoveHeader removes a header that SetHeader set on this global field instance.

Returns: void. This method returns nothing.

Validation

• Throws ArgumentNullException if key is null, because the SDK looks the header up by name.
• A key that the instance does not hold changes nothing and does not throw.

Behavior

• Client-side only. RemoveHeader makes no request.
• Removes only the headers set with SetHeader on this instance. The client headers, for example api_key and access_token, stay on every request.
• After the removal, a client header of the same name applies again to this instance.

Example

Basic usage: remove a header before the next request

using System;
using System.Text.Json.Nodes;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

GlobalField globalField = client.GlobalField("<GLOBAL_FIELD_UID>");
globalField.SetHeader("branch", "<BRANCH>");

// Read from the branch set on the client again
globalField.RemoveHeader("branch");

try
{
    JsonObject result = await globalField.Fetch();
    Console.WriteLine(result["title"]);
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}

SetHeader sets a request header on this global field instance.

Returns: void. This method returns nothing.

Validation

• There is no client-side validation of the header name or value.
• A null key or value changes nothing. SetHeader ignores the call and does not throw.

Behavior

• Client-side only. SetHeader stores the header and makes no request. A second call with the same key replaces the first value.
• Fetch on this instance sends the header. Other instances and the client keep their own headers.
• A header set here replaces a client header of the same name for this instance, for example the branch header that the Branch option sets.
• Use the RemoveHeader method to remove the header again.

Example

Basic usage: read a global field from another branch

using System;
using System.Text.Json.Nodes;
using Contentstack.Core;
using Contentstack.Core.Internals;
using Contentstack.Core.Models;

ContentstackClient client = new ContentstackClient("<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>");

GlobalField globalField = client.GlobalField("<GLOBAL_FIELD_UID>");

// The branch header on this instance replaces the branch set on the client
globalField.SetHeader("branch", "<BRANCH>");

try
{
    JsonObject result = await globalField.Fetch();
    Console.WriteLine(result["title"]);
}
catch (ContentstackException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.Message}");
}