5.12Setting Request Headers

Updated on Aug 20, 2026~9 min read

Add, modify, or remove request headers.

HTTP Declarative Requests set or remove request headers via the HeaderAttribute attribute. The corresponding HTTP declarative extractor is implemented as the HeaderDeclarativeExtractor type, which is responsible for parsing the HeaderAttribute attribute and building the request header configuration required by an HttpRequestBuilder instance.

1. Adding Request Headers

Using the HeaderAttribute attribute, you can conveniently add request headers on an interface, method, or parameter.

cs
// Applied on the interface definition, affecting all methods[Header("header1", "value1")][Header("header2", "value2")]public interface IHttpService : IHttpDeclarative{    // Applied on the method    [Header("header3", "value3")]    [Header("header4", "value4")]    [Get("https://furion.net/")]    Task<string> GetStringAsync();    // Applied on the parameter, supports the AliasAs property to specify an alias, and can be specified multiple times    [Header("header3", "value3")]    [Get("https://furion.net/")]    Task<string> GetStringAsync([Header] string header4, [Header][Header(AliasAs = "header5")] int lastHeader);    // On the parameter, a default value can be set via the Value property, and the same can be set for the age parameter, e.g. int? age = 30    [Get("https://furion.net/")]    Task<string> GetStringAsync([Header(Value = 30)] int? age);    // Supports defining an alias via [AliasAs]    [Get("https://furion.net/")]    Task<string> GetStringAsync([Header][AliasAs("header5")] int lastHeader);    // Supports configuration using a colon (:)    [Get("https://furion.net/")]    [Header("User-Agent: HttpAgent")]    Task<string> GetStringAsync();    // Supports format formatting    [Get("https://furion.net/")]    Task<string> GetStringAsync([Header(Format = "yyyyMMdd")] DateTime date);    // Frozen parameter types are ignored    [Get("https://furion.net/")]    Task<string> GetStringAsync([Header] CancellationToken cancellationToken);}

If duplicate request headers exist, they are merged, with multiple values separated by a comma followed by a space (, ). By setting the Replace = true property, you can override previous request header settings.

2. Removing Request Headers

In the HeaderAttribute attribute, specifying only the request header key without a value means removing that header. This is effective when applied on an interface or method.

cs
[Header("header1", "value1")] // Add the header1 header[Header("header2")]           // Mark header2 as to be removedpublic interface IHttpService : IHttpDeclarative{    [Header("header2", "value2")] // Add the header2 header    [Header("header3", "value3")] // Add the header3 header    [Header("header3")]           // Mark header3 as to be removed    [Get("https://furion.net/")]    Task<string> GetStringAsync();}

Before sending the HTTP request, the set of request headers marked for removal specified in the configuration will be removed. In other words, the removal operation is executed after all setting operations are called.

In the example above, although the GetStringAsync method attempts to add the header2 and header3 headers via the [Header] attribute, the subsequent [Header("header2")] and [Header("header3")] attributes specify only the request header key without a value, so these two keys are removed when the request headers are finally built. Only the header1 header is retained in the request headers.

HeaderAttribute contains the following constructors and properties:

  • Constructors:

    • new(): Effective when applied to a parameter, indicates adding a request header, with the default key being the parameter name.
    • new(name): When applied to a method or interface, if the configured string does not contain a colon (:), it indicates removing the specified request header; if it contains a colon, the first colon is used as the separator, with the key on the left and the value on the right. When applied to a parameter, it indicates adding a request header with the key being the value of the name argument.
    • new(name, value): Applies to interfaces, methods, or parameters, indicating adding a request header with the key being the value of the name argument, with lower priority than the AliasAs property.

  • Properties:

    • Name: The request header key (string type), with lower priority than the AliasAs property.
    • Value: The request header value (object type); when the attribute is applied to a parameter, it indicates the default value.
    • AliasAs: The request header key alias (string type), with higher priority than the Name property.
    • Escape: Whether to escape the request header value (bool type); the default value is false (do not escape).
    • Replace: Whether to replace existing request headers (bool type); the default value is false (append).
    • Format: The format to use (string? type), effective only when Value implements IFormattable.