Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

CookieHandler Class

.NET Framework 4.5

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

Namespace:  System.IdentityModel.Services
Assembly:  System.IdentityModel.Services (in System.IdentityModel.Services.dll)
public ref class CookieHandler abstract

The CookieHandler type exposes the following members.

  NameDescription
Protected methodCookieHandlerCalled from constructors in derived classes to initialize the CookieHandler class.
Top
  NameDescription
Public propertyDomainGets or sets the domain used for cookies.
Public propertyHideFromClientScriptGets or sets a value that indicates whether the cookie should be hidden from client script.
Public propertyNameGets or sets the base name for cookies written by the handler.
Public propertyPathGets or sets the virtual path for cookies written by the handler.
Public propertyPersistentSessionLifetimeThe lifetime of persistent sessions. If zero, transient sessions are always used.
Public propertyRequireSslGets or sets a value that specifies whether the cookie should be used only with SSL.
Top
  NameDescription
Public methodDelete()Deletes the cookie associated with the current request that has the default name, domain, and path.
Public methodDelete(HttpContext)Deletes the cookie associated with the current request that has the default name, domain, and path.
Public methodDelete(String)Deletes the cookie associated with the current request that has the specified name and the default domain and path.
Public methodDelete(String, HttpContext)Deletes the cookie associated with the specified request that has the specified name and the default domain and path.
Public methodDelete(String, String, String, HttpContext)Deletes the cookie associated with the specified request that has the specified name, path, and domain.
Protected methodDeleteCoreWhen overridden in a derived class, deletes the cookie associated with the specified request that has the specified name, domain, and path.
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodMatchCookiePathIf 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.
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodRead()Reads the cookie associated with the current request that has the default name.
Public methodRead(HttpContext)Reads the cookie associated with the current request that has the default name, domain, and path.
Public methodRead(String)Reads the cookie associated with the current request that has the specified name.
Public methodRead(String, HttpContext)Reads the cookie associated with the specified request that has the specified name and the default domain and path.
Protected methodReadCoreWhen overridden in a derived class, reads the cookie that has the specified name and that is associated with the specified request.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Public methodWrite(array<Byte>, Boolean, DateTime)Writes a cookie associated with the current request that has the specified value, persistence, and expiration time.
Public methodWrite(array<Byte>, String, DateTime)Writes a cookie associated with the current request that has the specified name, value, and expiration time.
Public methodWrite(array<Byte>, String, DateTime, HttpContext)Writes a cookie associated with the specified request that has the specified name, value, and expiration time.
Public methodWrite(array<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.
Protected methodWriteCoreWhen 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.
Top

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.

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>

.NET Framework

Supported in: 4.5.1, 4.5

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.