5.23Setting HttpRequestMessage Properties

Updated on Aug 20, 2026~7 min read

In certain scenarios, we may need to add extra properties to the HttpRequestMessage request rather than going through request headers.

HTTP Declarative Requests set HttpRequestMessage request properties through the PropertyAttribute attribute. The corresponding HTTP declarative extractor is implemented as the PropertyDeclarativeExtractor type, which is responsible for parsing the PropertyAttribute attribute and building the HttpRequestMessage request property configuration required for an HttpRequestBuilder instance.

Using the PropertyAttribute attribute, you can conveniently add HttpRequestMessage request properties on interfaces, methods, or parameters.

cs
// Applied at the interface level, affects all methods[Property("property1", "value1")][Property("property2", "value2")][Property("property0")] // Value is nullpublic interface IHttpService : IHttpDeclarative{    // Applied at the method level    [Property("property3", "value3")]    [Property("property4", "value4")]    [Get("https://furion.net/")]    Task<string> GetStringAsync();    // Applied at the parameter level; the AliasAs property can specify an alias, and multiple attributes are allowed    [Property("property3", "value3")]    [Get("https://furion.net/")]    Task<string> GetStringAsync([Property] string property4, [Property][Property(AliasAs = "property5")] int lastProperty);    // At the parameter level, you can set a default value through the Value property; similarly for the age parameter, e.g., int? age = 30    [Get("https://furion.net/")]    Task<string> GetStringAsync([Property(Value = 30)] int? age);    // [AliasAs] is supported to define an alias    [Get("https://furion.net/")]    Task<string> GetStringAsync([Property][AliasAs("property5")] int lastProperty);    // Add object content; when AsItem is false, the object is parsed and traversed, and its properties are set as individual HttpRequestMessage request property items    [Get("https://furion.net/")]    Task<string> GetStringAsync([Property(AsItem = false)] object obj);    // Frozen parameter types are ignored    [Get("https://furion.net/")]    Task<string> GetStringAsync([Property] CancellationToken cancellationToken);}

These properties are added to the Options property of the HttpRequestMessage object (reference documentation). To retrieve these values, you can do the following:

cs
httpRequestMessage.Options.TryGetValue(new HttpRequestOptionsKey<string>("key1"), out var value);

If a property key is duplicated, the value set later overrides the earlier setting.

PropertyAttribute contains the following constructors and properties:

  • Constructors:

    • new(): Effective when applied to parameters; adds an HttpRequestMessage request property with the parameter name as the default key.
    • new(name): When applied to methods or interfaces, adds an HttpRequestMessage request property operation with a value of null; when applied to parameters, adds an HttpRequestMessage request property with the key being the value of the name parameter.
    • new(name, value): Applies to interfaces, methods, or parameters; adds an HttpRequestMessage request property with the key being the value of the name parameter, with lower priority than the AliasAs property.

  • Properties:

    • Name: The HttpRequestMessage request property key (type string), with lower priority than the AliasAs property.
    • Value: The value of the HttpRequestMessage request property (type object); when the attribute is applied to a parameter, it represents the default value.
    • AliasAs: The alias of the HttpRequestMessage request property key (type string), with higher priority than the Name property.
    • AsItem: Indicates whether to treat the value as a single item of the HttpRequestMessage request property (type bool), defaulting to true (as an item), and only takes effect when the parameter is an object type. When false (not as an item), the object is parsed and traversed, and its properties are set as individual HttpRequestMessage request property items.