5.13Setting Path Parameters (Template/Configuration Parameters)

Replaces object template strings in the URL path.

HTTP Declarative Requests configure path parameters through the PathAttribute attribute and the non-frozen parameters defined on methods. The corresponding HTTP declarative extractor is the PathDeclarativeExtractor type, which is responsible for parsing these PathAttribute attributes and the non-frozen parameters defined on methods, and building the path parameter configuration required by the HttpRequestBuilder instance.

123456789101112131415161718192021222324

// Applied on the interface definition, affecting all methods[Path("path1", "value1")][Path("path2", "value2")]public interface IHttpService : IHttpDeclarative{    // Applied on the method    [Path("path3", "value3")]    [Get("https://furion.net/{path1}/{path2}/{path3}")]    Task<string> GetStringAsync();    // Non-frozen parameters defined on the method are added to the path parameters by default and can be used directly in the URL    [Get("https://furion.net/{path1}/{path2}/?id={id}&name={name}&address={address}&age={age}&name1={user.Name}&obj={obj}")]    Task<string> GetStringAsync(int id, string name, string[] address, int age, User user, object? obj);    [Get("https://furion.net/{name?}")] // A trailing "?" means the value is replaced with an empty string when the key does not exist; can be combined with the [RemoveTrailingSlash] attribute    Task<string> GetStringAsync(string name);    [Get("https://furion.net/{**path}")] // A leading "**" means the path separator "/" is not escaped    Task<string> GetStringAsync(string path);    // Frozen parameter types are ignored    [Get("https://furion.net/")]    Task<string> GetStringAsync(CancellationToken cancellationToken);}

If duplicate path parameter keys exist, the later-set key value overrides the earlier setting.

Template path syntax

In addition to directly using {key}, template paths also support accessing object properties and nested properties via ., and accessing collection elements via [index]. Additionally, when an object-typed value has no property matching the given name, the framework automatically attempts 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 whose key is "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>, Hashtable, etc.), dic.key is evaluated as dic["key"].
• {obj.dictProp.someKey[0].another}: Mixes dot and index access to drill down level by level.

All the paths above 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.

PathAttribute includes the following constructors and properties:

• Constructors:

  • new(name, value): Applies to interfaces or methods, indicating the addition of a path parameter with the value of the parameter name as the key.

• Properties:

  • Name: The path parameter key (string type).
  • Value: The path parameter value (object type).

Configuration parameters

In addition to setting path parameters through the {key} template syntax, the framework also provides configuration parameters for reading configuration information to perform replacements. Configuration parameters use the [[key]] syntax, for example:

12345

public interface IHttpService : IHttpDeclarative{    [Get("https://furion.net?id=[[id]]&name=[[name]]")]    Task<string> GetStringAsync();}

Enabling configuration parameter support

To enable configuration parameter support in the HttpRemote service, configure it with the following steps:

123456

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

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:

1234

{  "id": 1,  "name": "Furion"}

Configuration parameter keys support various format syntaxes to access values in the configuration file more flexibly:

• [[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]]: Combines fallback lookup and default value to ensure a value is always available.