3.28Setting Path Parameters (Template/Configuration Parameters)

Created on Aug 17, 2026~9 min read

Replaces object template strings in the URL path.

cs
HttpRequestBuilder.Get("https://furion.net?id={id}&name={name}")    .WithPathParameter("id", 1)  // Adds a single parameter; {id} will be replaced with 1    .WithPathParameter("name", new[] { "furion", "monksoul" }) // Adds a single parameter; {name} will be replaced with furion,monksoul    .WithPathParameters(new Dictionary<string, object?> { })   // Adds multiple path parameters    .WithPathParameters(new { id = 1, name = "Furion" })   // Adds multiple path parameters; {id} and {name} are replaced with 1 and Furion respectively    .WithPathParameters(new { id = 1, name = "Furion" }, "user")   // Adds parameters with a prefix; {user.id} and {user.name} are replaced with 1 and Furion respectivelyHttpRequestBuilder.Get("https://furion.net/{id}/{name?}")   // A trailing "?" means it is replaced with an empty string when the key does not exist    .WithPathParameter(new { id = 1 });HttpRequestBuilder.Get("https://furion.net/{**path}")   // A leading "**" means the path separator "/" is not escaped    .WithPathParameter(new { path = "files/images/photo.jpg" });

If a path parameter key is duplicated, the later key-value setting overrides the previous one.

Template Path Syntax

In addition to directly using {key}, template paths support accessing an object's properties and nested properties via ., and accessing elements in a collection via [index]. Furthermore, when a property of an object type is not found as a same-named property, the framework automatically tries to treat it as a dictionary and retrieves the value using the path identifier as the key (equivalent to dict["key"]).

  • {key}: Directly replaces the corresponding value.
  • {key.property}: Accesses the property property of the key object, or when key is a dictionary, accesses the value with the key "property".
  • {key.property.nested}: Multi-level property/key access.
  • {list[0]}: Accesses the element at index 0 in the list collection (arrays, List<T>, etc.).
  • {user.names[1]}: First accesses the names property of the user object, then takes the element at index 1.
  • {dic.key}: When dic is a dictionary (including Dictionary<string, T> and Hashtable, etc.), dic.key is resolved as dic["key"].
  • {obj.dictProp.someKey[0].another}: Mixes dot and index notation to drill down level by level.

All of the above paths support appending ? at the end to indicate that the value is replaced with an empty string when it does not exist, and adding a ** prefix to indicate that the path separator / is not escaped.

Configuration Parameters

In addition to setting path parameters via the {key} template syntax, the framework also provides configuration parameters for reading configuration information and performing replacement. Configuration parameters use the [[key]] syntax, for example:

cs
HttpRequestBuilder.Get("https://furion.net?id=[[id]]&name=[[name]]");

Enabling Configuration Parameter Support

To enable configuration parameter support in the HttpRemote service, configure it as follows:

cs
services.AddHttpRemote(builder => {})    .ConfigureOptions(options =>    {        // Sets the provider source used to replace the configuration template parameters in the URL        options.Configuration = builder.Configuration;  // When using the Furion framework, you can directly set App.Configuration    });

Using Configuration Parameters

Configuration parameters are read from your configuration file and replaced into the URL. For example, your configuration file might look like this:

appsettings.json
{  "id": 1,  "name": "Furion"}

Configuration parameter keys support multiple format syntaxes for more flexible access to values in the configuration file:

  • [[key]]: Directly accesses the value corresponding to key.
  • [[key:sub]]: Accesses the value of the sub sub-item under key.
  • [[key:sub:nest]]: Accesses the value of the nest sub-item within the sub sub-item under key.
  • Fallback value lookup:
    • [[notfound | bak]]: If notfound does not exist, looks up bak.
    • [[notfound | bak | other]]: If neither notfound nor bak exists, looks up other.
    • [[notfound | bak:sub | other:sub:nest]]: Supports deeper fallback lookups.
  • Default values:
    • [[notfound || default]]: If notfound does not exist, uses default as the value.
    • [[notfound | bak | other || default value]]: Combines fallback lookup and default values to ensure a value is always available.