CookieHandler Class

Reference

Definition

Namespace:: System.IdentityModel.Services

Assembly:: System.IdentityModel.Services.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Provides an abstract base class for reading, writing, and deleting session cookies on an HTTP client.

public ref class CookieHandler abstract

public abstract class CookieHandler

type CookieHandler = class

Public MustInherit Class CookieHandler

Inheritance: Object
CookieHandler

Derived: System.IdentityModel.Services.ChunkedCookieHandler

Examples

The following example configures the SAM to use a custom cookie handler of type MyNamespace.MyCustomCookieHandler.

<cookieHandler mode="Custom">  
    <customCookieHandler type="MyNamespace.MyCustomCookieHandler, MyAssembly" />  
</cookieHandler>

Remarks

The SessionAuthenticationModule (SAM) uses an instance of the CookieHandler class to read, write, and delete the cookie or cookies that contain the SessionSecurityToken on the HTTP client. The cookie (or cookies, in the case where the session token is split across several cookies) that contains the session token is known as the session cookie.

Windows Identity Foundation (WIF) ships with a cookie handler called the chunked cookie handler that is implemented by the ChunkedCookieHandler class. The chunked cookie handler splits the session token across one or more cookies according to a specified chunk size. This is to meet size limitations on individual cookies imposed by many browsers.

You can derive from CookieHandler to create your own cookie handler. When you do so, you must override the DeleteCore, ReadCore, and WriteCore methods to perform the actual work of deleting, reading, and writing the session cookie. These methods typically read the cookie from the HttpRequest.Cookies collection and write or delete cookies through the HttpResponse.Cookies collection. The HttpContext object through which you can access the request and response is provided as a parameter to each of these methods. In addition to the required methods, you can optionally override other virtual methods properties exposed by the CookieHandler class to customize the behavior of your handler.

Several properties are exposed by the CookieHandler class that specify default behavior and properties for the session cookie. The Name, Domain, and Path properties supply the base name for the cookie, the domain in which it is valid and the path under which it is stored on the client. The HideFromClientScript property specifies whether the cookie is accessible to client-side scripts. The RequireSsl property specifies whether the cookie should be transmitted only over secure (HTTPS) connections. If set, the PersistentSessionLifetime property is used to set the expiration time for persistent sessions, that is for sessions that remain valid even after the browser is closed. All of these properties have equivalent properties that are typically set on the underlying HttpCookie object (or objects) by the "core" methods of the handler. For more information see the documentation for each property.

The cookie handler that is used by the SAM can be specified in configuration through the <cookieHandler> element. The cookie handler set by this element can be modified in an event delegate for the FederatedAuthentication.FederationConfigurationCreated event or it can be set or accessed directly through the SessionAuthenticationModule.CookieHandler property.

Constructors

CookieHandler()

Called from constructors in derived classes to initialize the CookieHandler class.

Properties

Domain	Gets or sets the domain used for cookies.
HideFromClientScript	Gets or sets a value that indicates whether the cookie should be hidden from client script.
Name	Gets or sets the base name for cookies written by the handler.
Path	Gets or sets the virtual path for cookies written by the handler.
PersistentSessionLifetime	The lifetime of persistent sessions. If zero, transient sessions are always used.
RequireSsl	Gets or sets a value that specifies whether the cookie should be used only with SSL.

Methods

Delete()	Deletes the cookie associated with the current request that has the default name, domain, and path.
Delete(HttpContext)	Deletes the cookie associated with the current request that has the default name, domain, and path.
Delete(String, HttpContext)	Deletes the cookie associated with the specified request that has the specified name and the default domain and path.
Delete(String, String, String, HttpContext)	Deletes the cookie associated with the specified request that has the specified name, path, and domain.
Delete(String)	Deletes the cookie associated with the current request that has the specified name and the default domain and path.
DeleteCore(String, String, String, HttpContext)	When overridden in a derived class, deletes the cookie associated with the specified request that has the specified name, domain, and path.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetType()	Gets the Type of the current instance. (Inherited from Object)
MatchCookiePath(Uri, Uri)	If the target domain is within the cookie domain and the target path is within the cookie path, match the casing of the cookie path portion.
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
Read()	Reads the cookie associated with the current request that has the default name.
Read(HttpContext)	Reads the cookie associated with the current request that has the default name, domain, and path.
Read(String, HttpContext)	Reads the cookie associated with the specified request that has the specified name and the default domain and path.
Read(String)	Reads the cookie associated with the current request that has the specified name.
ReadCore(String, HttpContext)	When overridden in a derived class, reads the cookie that has the specified name and that is associated with the specified request.
ToString()	Returns a string that represents the current object. (Inherited from Object)
Write(Byte[], Boolean, DateTime)	Writes a cookie associated with the current request that has the specified value, persistence, and expiration time.
Write(Byte[], String, DateTime, HttpContext)	Writes a cookie associated with the specified request that has the specified name, value, and expiration time.
Write(Byte[], String, DateTime)	Writes a cookie associated with the current request that has the specified name, value, and expiration time.
Write(Byte[], String, String, String, DateTime, Boolean, Boolean, HttpContext)	Writes a cookie associated with the specified request that has the specified name, value, domain, path, expiration time, and visibility.
WriteCore(Byte[], String, String, String, DateTime, Boolean, Boolean, HttpContext)	When overridden in a derived class, writes a cookie associated with the specified request that has the specified name, value, domain, path, expiration time, persistence and visibility.

Applies to

Share via