ParameterCollection

View as Markdown

ParameterCollection

ParameterCollection holds the query parameters that one request sends, in the Contentstack.Management.Core.Queryable namespace.

When to Use This Class: Use this class to send a query parameter that a method has no argument for, such as include_count, locale, or a query filter. Pass it through the collection or parameters argument of a request method.

Conceptual Role: Acts as a sorted dictionary of parameter names and typed values. The SDK turns it into the query string of the request.

Returns: ParameterCollection. An empty set of query parameters.

Class-Level Notes

It is a dictionary.

  • ParameterCollection extends SortedDictionary<string, QueryParamValue> and keeps its keys in ordinal order. Create it with new ParameterCollection(), which takes no arguments.
  • The dictionary members work as usual: Remove, ContainsKey, Count, the indexer, and foreach.
  • One key holds one value. Adding a key a second time throws ArgumentException. Use the indexer to replace a value, for example collection["limit"] = new DoubleParameterValue(10).

How the SDK writes the query string.

  • GetSortedParametersList turns each entry into one or more name=value pairs, and the SDK joins them with & in key order.
  • The SDK does not URL-encode the names or values, except for AddQuery. Encode a value that holds &, =, #, or + with Uri.EscapeDataString before you add it.
  • A request method keeps no reference to the collection after it returns, except Query, which copies the entries into its own collection.

Value types. Each Add overload wraps the value in one of the classes below, and you can add an instance of any of them directly.

Value classWritten as
BoolParameterValuename=true or name=false
DoubleParameterValuename=10, in the number format of the current culture
StringParameterValuename=value
StringListParameterValuename[]=a&name[]=b, sorted
DoubleListParameterValuename[]=1&name[]=2, sorted
JObjectParameterValuename= followed by the JSON text

Method Index

Method NameReturnsDescription
AddThis method returns nothing.Adds one query parameter.
AddQueryThis method returns nothing.Adds a JSON query filter, URL-encoded.
GetSortedParametersListThe query parameters as name and value pairs.Lists the pairs the SDK writes into the query string.

Class-Level Snippet

This snippet lists the entries of a content type in one locale, with a count and a JSON filter on the title.

using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

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

ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "<LOCALE_CODE>");
collection.Add("include_count", true);
collection.AddQuery(new JsonObject { ["title"] = "Blog Post" });

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry().Query().Find(collection);
    Console.WriteLine(response.OpenJsonObjectResponse()["count"]);
}
catch (ContentstackErrorException e)
{
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Methods

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

Add

Add adds one query parameter to the collection, wrapping the value in the matching value class.

NameTypeDescription
key (required)string

Name of the query parameter.

Default: Not applicable
value (required)string

Text value, sent as given.

Default: Not applicable
value (required)bool

Flag value, sent as true or false.

Default: Not applicable
value (required)double

Number value, such as a limit.

Default: Not applicable
key (required)string

Name of the array parameter, without [].

Default: Not applicable
values (required)List<string>

Text values, sent as key[] pairs.

Default: Not applicable
values (required)List<double>

Number values, sent as key[] pairs.

Default: Not applicable
value (required)QueryParamValue

A value object, such as JObjectParameterValue.

Default: Not applicable

Returns: void. This method returns nothing.

Overloads

  • Add(string key, string value)
  • Add(string key, bool value)
  • Add(string key, double value)
  • Add(string key, List<string> values)
  • Add(string key, List<double> values)
  • Add(string key, QueryParamValue value)

Validation

  • Throws ArgumentException if the collection already has key, because each key holds one value. Use the indexer to replace a value.
  • Throws ArgumentNullException if key is null.
  • Add accepts a null string or a null list without an error. The SDK leaves a null string out of the query string, and a null list throws NullReferenceException when the SDK writes the query string.
  • Errors from the API come from the request method you pass the collection to, not from Add.

Behavior

  • Client-side only. Add stores the value and sends no request.
  • The Add(string key, QueryParamValue value) overload comes from SortedDictionary. Use it to add a JObjectParameterValue, which has no typed overload.
  • The SDK writes a number with the number format of the current culture, so 1.5 becomes 1,5 under a culture such as de-DE. Add a fractional number as a string formatted with CultureInfo.InvariantCulture when your app runs under such a culture.
  • The SDK writes a list as one key[]=value pair per item and sorts the list you passed, so its order changes.

Example

Basic usage: add a text and a flag parameter

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

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

ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "<LOCALE_CODE>");
collection.Add("include_count", true);

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry().Query().Find(collection);
    Console.WriteLine(response.OpenJsonObjectResponse()["count"]);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: every overload

using System;
using System.Collections.Generic;
using System.Text.Json.Nodes;
using Contentstack.Management.Core.Queryable;

ParameterCollection collection = new ParameterCollection();
collection.Add("locale", "<LOCALE_CODE>");
collection.Add("include_count", true);
collection.Add("limit", 10);
collection.Add("only[BASE]", new List<string> { "title", "url" });
collection.Add("version", new List<double> { 1, 2 });
collection.Add("query", new JObjectParameterValue(new JsonObject { ["title"] = "Blog Post" }));

foreach (KeyValuePair<string, string> pair in collection.GetSortedParametersList())
{
    Console.WriteLine($"{pair.Key}={pair.Value}");
}

Edge case: adding a key twice

using System;
using Contentstack.Management.Core.Queryable;

ParameterCollection collection = new ParameterCollection();
collection.Add("limit", 10);

try
{
    collection.Add("limit", 20);
}
catch (ArgumentException e)
{
    // Fires at once, because "limit" already has a value
    Console.WriteLine(e.Message);
}

// Replace a value through the indexer instead.
collection["limit"] = new DoubleParameterValue(20);

AddQuery

AddQuery adds a JSON filter to the collection as the URL-encoded query parameter.

NameTypeDescription
queryObj (required)JsonNode

Filter object, such as {"title": "Blog Post"}.

Default: Not applicable

Returns: void. This method returns nothing.

Validation

  • Throws ArgumentException if the collection already has a query key, because each key holds one value. Put every condition in one filter object.
  • Throws NullReferenceException if queryObj is null.
  • AddQuery does not check the filter. A filter the API does not accept fails on the request method you pass the collection to, with ContentstackErrorException.

Behavior

  • Client-side only. AddQuery stores the value and sends no request.
  • Serializes queryObj to JSON text, URL-encodes it with Uri.EscapeDataString, and stores it under the key query as a StringParameterValue.
  • Use AddQuery rather than Add("query", ...) for a filter, because the SDK encodes no other value.
  • See the query operators in the Content Management API reference for the filter syntax of each request.

Example

Basic usage: list entries that match a title

using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

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

ParameterCollection collection = new ParameterCollection();
collection.AddQuery(new JsonObject { ["title"] = "Blog Post" });

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry().Query().Find(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}");
}

Edge case: combine conditions in one filter

using System;
using System.Text.Json.Nodes;
using Contentstack.Management.Core.Queryable;

ParameterCollection collection = new ParameterCollection();

// A second AddQuery call throws, so put every condition in one object.
collection.AddQuery(new JsonObject
{
    ["$and"] = new JsonArray(
        new JsonObject { ["title"] = "Blog Post" },
        new JsonObject { ["author"] = new JsonObject { ["$exists"] = true } })
});

Console.WriteLine(collection.GetSortedParametersList()[0].Value);

GetSortedParametersList

GetSortedParametersList returns the name and value pairs that the SDK writes into the query string, in key order.

This method takes no parameters.

Returns: List. The query parameters as name and value pairs.

Validation

  • Throws ContentstackException if an entry holds a value class the SDK does not support, such as a QueryParamValue subclass of your own.
  • Throws NullReferenceException if a list entry holds a null list, or a JObjectParameterValue holds a null node.

Behavior

  • Client-side only. GetSortedParametersList sends no request. The SDK calls it when it builds the URL of a request.
  • Returns a List<KeyValuePair<string, string>> with one pair per scalar entry, and one pair per item for a list entry, with [] added to the name.
  • Sorts the items of each list entry, and sorts the list you passed in place.

Writes a bool as true or false. Writes a double in the current culture's number format. Writes a list of numbers in the invariant format. Writes a JsonNode as JSON text.

Example

Basic usage: preview the query string

using System;
using System.Collections.Generic;
using Contentstack.Management.Core.Queryable;

ParameterCollection collection = new ParameterCollection();
collection.Add("include_count", true);
collection.Add("limit", 10);
collection.Add("only[BASE]", new List<string> { "url", "title" });

List<KeyValuePair<string, string>> pairs = collection.GetSortedParametersList();
foreach (KeyValuePair<string, string> pair in pairs)
{
    // Prints include_count=true, limit=10, only[BASE][]=title, only[BASE][]=url
    Console.WriteLine($"{pair.Key}={pair.Value}");
}