3.26Setting Query Parameters (URL Parameters)

Created on Aug 17, 2026~5 min read

Adds or modifies URL query parameters.

cs
HttpRequestBuilder.Get("https://furion.net/")    .WithQueryParameter("id", 1)  // Adds a single parameter    .WithQueryParameter("date", DateTime.Now, format: "yyyyMMdd")  // Supports format formatting    .WithQueryParameter("name", new[] { "furion", "monksoul" }) // Adds multiple values, generating: name=furion&name=monksoul    .WithQueryParameter("name", (object?)null) // Sets a null value    .WithQueryParameter("r", () => DateTimeOffset.UtcNow.ToUnixTimeSeconds()) // Sets a dynamically computed parameter (used for cache busting)    .WithQueryParameter("r", context => DateTimeOffset.UtcNow.ToUnixTimeSeconds()) // Sets a dynamically computed parameter (used for cache busting)    .WithQueryParameters(new Dictionary<string, object?> { })   // Adds multiple parameters    .WithQueryParameters(new { id = 1, name = "Furion" })   // Adds multiple parameters, generating: id=1&name=Furion    .WithQueryParameters(new { id = 1, name = "Furion" }, "user")   // Adds parameters with a prefix, generating: user.id=1&user.name=Furion    .WithQueryParameters(new Dictionary<string, object?> { { "str1", null }, {"str2", "test" } }, ignoreNullValues: true); // Ignores null values

If duplicate query parameter keys exist, they are merged into multiple key-value pairs (for example key1=value1&key1=value2). By setting the replace: true parameter, you can override previous query parameters and the original URL parameters. By default, query parameters with a null value are added to the URL; to ignore these parameters, set ignoreNullValues: true.

URL Parameter Formatter

When setting query parameters on an HTTP request, the framework passes the parameter keys and values to IUrlParameterFormatter for formatting. The default implementation, UrlParameterFormatter, generates a key=value pair for each value. However, certain types (such as DateTime) may require special handling, or you may want to change the output form of the entire key-value pair (for example, outputting multiple values in an array format such as key[0]=val1&key[1]=val2), which can be achieved through a custom formatter.

The following example shows how to override the Format method to format values of type DateTime as yyyyMMdd, while other types use the default handling:

csharp
public class CustomUrlParameterFormatter : UrlParameterFormatter{    /// <inheritdoc />    public override IEnumerable<KeyValuePair<string, string?>>? Format(UrlFormattingContext context, string key, IEnumerable<object?> values)    {        foreach (var value in values)        {            if (value is DateTime dateTime)            {                yield return new(key, dateTime.ToString("yyyyMMdd"));   // Formats                continue;            }            yield return new(key, FormatValue(context, value));        }    }}

After completing the custom formatter, you can register it as the default URL parameter formatter when configuring HttpRemoteOptions:

csharp
services.AddHttpRemote(builder => {})    .ConfigureOptions(options =>    {        options.UrlParameterFormatter = new CustomUrlParameterFormatter();    });

In this way, when building URL query parameters, if a DateTime value is encountered, the framework automatically formats it as a yyyyMMdd string, ensuring the output matches expectations.

URL Parameter Sorting

Although sorting URL query parameters is a relatively rare requirement, some systems with higher security requirements often need to verify the order of parameters. The framework provides sorting support for this purpose, sorting the final key-value pair collection:

cs
HttpRequestBuilder.Get("https://furion.net/")    .WithQueryParameters(new { name = "furion", id = 1})    .SetQueryParametersSorter(pairs => pairs.OrderBy(kv => kv.Key));

Use the .SetQueryParametersSorter() method to configure the query parameter sorting rule. This method receives a sequence of KeyValuePair<string, string?> and returns a new sorted sequence. When it is null, no sorting is applied (the original insertion order is preserved).