ParameterCollection
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 class | Written as |
|---|---|
| BoolParameterValue | name=true or name=false |
| DoubleParameterValue | name=10, in the number format of the current culture |
| StringParameterValue | name=value |
| StringListParameterValue | name[]=a&name[]=b, sorted |
| DoubleListParameterValue | name[]=1&name[]=2, sorted |
| JObjectParameterValue | name= followed by the JSON text |
Method Index
| Method Name | Returns | Description |
|---|---|---|
| Add | This method returns nothing. | Adds one query parameter. |
| AddQuery | This method returns nothing. | Adds a JSON query filter, URL-encoded. |
| GetSortedParametersList | The 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.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the query parameter. |
| value (required) | string | Text value, sent as given. |
| value (required) | bool | Flag value, sent as true or false. |
| value (required) | double | Number value, such as a limit. |
| key (required) | string | Name of the array parameter, without []. |
| values (required) | List<string> | Text values, sent as key[] pairs. |
| values (required) | List<double> | Number values, sent as key[] pairs. |
| value (required) | QueryParamValue | A value object, such as JObjectParameterValue. |
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.
| Name | Type | Description |
|---|---|---|
| queryObj (required) | JsonNode | Filter object, such as {"title": "Blog Post"}. |
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}");
}