5.14Setting Cookie

Updated on Aug 20, 2026~7 min read

Adds, modifies, or removes a Cookie.

HTTP Declarative Requests set or remove a Cookie via the CookieAttribute attribute. The corresponding HTTP declarative extractor is implemented as the CookieDeclarativeExtractor type, which is responsible for parsing the CookieAttribute attribute and building the Cookie configuration required by the HttpRequestBuilder instance.

1. Adding a Cookie

Using the CookieAttribute attribute, you can conveniently add a Cookie on an interface, method, or parameter.

cs
// Applied on the interface definition, affecting all methods[Cookie("cookie1", "value1")][Cookie("cookie2", "value2")]public interface IHttpService : IHttpDeclarative{    // Applied on the method    [Cookie("cookie3", "value3")]    [Cookie("cookie4", "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    [Cookie("cookie3", "value3")]    [Get("https://furion.net/")]    Task<string> GetStringAsync([Cookie] string cookie4, [Cookie][Cookie(AliasAs = "cookie5")] int lastCookie);    // On parameters, a default value can be set via the Value property; the same applies to the age parameter, e.g. int? age = 30    [Get("https://furion.net/")]    Task<string> GetStringAsync([Cookie(Value = 30)] int? age);    // Supports [AliasAs] to define an alias    [Get("https://furion.net/")]    Task<string> GetStringAsync([Cookie][AliasAs("cookie5")] int lastCookie);    // Supports formatting via format    [Get("https://furion.net/")]    Task<string> GetStringAsync([Cookie(Format = "yyyyMMdd")] DateTime date);    // Frozen parameter types are ignored    [Get("https://furion.net/")]    Task<string> GetStringAsync([Cookie] CancellationToken cancellationToken);}

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

2. Removing a Cookie

In the CookieAttribute attribute, specifying only the Cookie key without assigning a value indicates removing that Cookie. It is effective when applied to interfaces or methods.

cs
[Cookie("cookie1", "value1")] // Add cookie1[Cookie("cookie2")]           // Mark cookie2 for removalpublic interface IHttpService : IHttpDeclarative{    [Cookie("cookie2", "value2")] // Add cookie2    [Cookie("cookie3", "value3")] // Add cookie3    [Cookie("cookie3")]           // Mark cookie3 for removal    [Get("https://furion.net/")]    Task<string> GetStringAsync();}

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

In the example above, although the GetStringAsync method tries to add cookie2 and cookie3 via the [Cookie] attribute, because the subsequent [Cookie("cookie2")] and [Cookie("cookie3")] attributes only specify the Cookie key without assigning a value, these two keys are removed when the request header Cookie is finally built. Only the cookie1 parameter remains in the request header Cookie.

CookieAttribute includes the following constructors and properties:

  • Constructors:

    • new(): Effective on parameters, indicating the addition of a Cookie with the parameter name as the default key.
    • new(name): When applied to a method or interface, indicates removing the specified Cookie; when applied to a parameter, indicates adding a Cookie with the value of the parameter name as the key.
    • new(name, value): Applies to interfaces, methods, or parameters, indicating the addition of a Cookie with the value of the parameter name as the key; has lower priority than the AliasAs property.

  • Properties:

    • Name: The Cookie key (string type), with lower priority than the AliasAs property.
    • Value: The Cookie value (object type); when the attribute applies to a parameter, it represents the default value.
    • AliasAs: The Cookie key alias (string type), with higher priority than the Name property.
    • Format: The format to use (string? type), effective only when Value implements IFormattable.