Skip to main content

QueryParams

Namespace: RA.Utilities.Integrations.Models

The QueryParams class is a specialized utility designed to make it easier to build a collection of key-value pairs that will eventually be used to construct a URL query string.

Here's a breakdown of its purpose and design:

1. Inheritance from List<KeyValuePair<string, string>>:​

  • At its core, this class is a list of string key-value pairs. This structure is a natural fit for URL query parameters, which consist of keys and values (e.g., ?key1=value1&key2=value2).
  • By inheriting from List, it can handle duplicate keys (e.g., ?filter=A&filter=B), which is a valid and common scenario in URL query strings.

2. Convenience Add Method:​

  • It provides a convenient overload for the Add method: public void Add(string key, string value).
  • This allows you to add parameters with a simpler syntax (queryParams.Add("name", "gemini")) instead of the more verbose syntax required by the base List class (queryParams.Add(new KeyValuePair<string, string>("name", "gemini"))).

3. Convenience ToString() Method:​

Method that correctly builds and URL-encodes the query string. This would make the class a more complete and self-contained utility.

var queryParams = new QueryParams
{
    { "page", "1" },
    { "user name", "Gemini Assist" } // Key with a space
};

// The ToString() method will now produce the correctly encoded string:
// "page=1&user+name=Gemini+Assist"
string urlQuery = queryParams.ToString();

This enhancement encapsulates the formatting logic within the class itself, making it more intuitive and less error-prone for developers using it.

The use of WebUtility.UrlEncode is fundamental to making the QueryParams class reliable and correct.

What is WebUtility.UrlEncode?​

WebUtility.UrlEncode is a standard .NET method that converts a string into a URL-safe format.

URLs have a restricted set of allowed characters. Many characters, like spaces, ampersands (&), question marks (?), and equal signs (=), are "reserved" because they have special structural meaning within a URL.

When you URL-encode a string, this method takes any of these special or unsafe characters and replaces them with a percent sign (%) followed by their two-digit hexadecimal representation. For example:

  • A space ( ) becomes %20 (or sometimes +)
  • An ampersand (&) becomes %26
  • A plus sign (+) becomes %2B
  • A hash/pound sign (#) becomes %23

Why is it Important for QueryParams?​

It is absolutely critical for ensuring that the query string generated by the QueryParams.ToString() method is valid and can be correctly interpreted by the web server receiving the request.

🧠 Summary​

In short, it's a small helper class that improves developer experience by providing a clear, intent-specific type for handling URL parameters and a simpler way to add them to the collection.

WebUtility.UrlEncode is the essential step that guarantees data integrity. It ensures that the keys and values you intend to send are the same keys and values the server receives, regardless of what special characters they might contain.