CookieHandler Class

.NET Framework (current version)
 

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)

System::Object
  System.IdentityModel.Services::CookieHandler
    System.IdentityModel.Services::ChunkedCookieHandler

public ref class CookieHandler abstract 

NameDescription
System_CAPS_protmethodCookieHandler()

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

NameDescription
System_CAPS_pubpropertyDomain

Gets or sets the domain used for cookies.

System_CAPS_pubpropertyHideFromClientScript

Gets or sets a value that indicates whether the cookie should be hidden from client script.

System_CAPS_pubpropertyName

Gets or sets the base name for cookies written by the handler.

System_CAPS_pubpropertyPath

Gets or sets the virtual path for cookies written by the handler.

System_CAPS_pubpropertyPersistentSessionLifetime

The lifetime of persistent sessions. If zero, transient sessions are always used.

System_CAPS_pubpropertyRequireSsl

Gets or sets a value that specifies whether the cookie should be used only with SSL.

NameDescription
System_CAPS_pubmethodDelete()

Deletes the cookie associated with the current request that has the default name, domain, and path.

System_CAPS_pubmethodDelete(HttpContext^)

Deletes the cookie associated with the current request that has the default name, domain, and path.

System_CAPS_pubmethodDelete(String^)

Deletes the cookie associated with the current request that has the specified name and the default domain and path.

System_CAPS_pubmethodDelete(String^, HttpContext^)

Deletes the cookie associated with the specified request that has the specified name and the default domain and path.

System_CAPS_pubmethodDelete(String^, String^, String^, HttpContext^)

Deletes the cookie associated with the specified request that has the specified name, path, and domain.

System_CAPS_protmethodDeleteCore(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.

System_CAPS_pubmethodEquals(Object^)

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_protmethodFinalize()

Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)

System_CAPS_pubmethodGetHashCode()

Serves as the default hash function. (Inherited from Object.)

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_pubmethodMatchCookiePath(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.

System_CAPS_protmethodMemberwiseClone()

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_pubmethodRead()

Reads the cookie associated with the current request that has the default name.

System_CAPS_pubmethodRead(HttpContext^)

Reads the cookie associated with the current request that has the default name, domain, and path.

System_CAPS_pubmethodRead(String^)

Reads the cookie associated with the current request that has the specified name.

System_CAPS_pubmethodRead(String^, HttpContext^)

Reads the cookie associated with the specified request that has the specified name and the default domain and path.

System_CAPS_protmethodReadCore(String^, HttpContext^)

When overridden in a derived class, reads the cookie that has the specified name and that is associated with the specified request.

System_CAPS_pubmethodToString()

Returns a string that represents the current object.(Inherited from Object.)

System_CAPS_pubmethodWrite(array<Byte>^, Boolean, DateTime)

Writes a cookie associated with the current request that has the specified value, persistence, and expiration time.

System_CAPS_pubmethodWrite(array<Byte>^, String^, DateTime)

Writes a cookie associated with the current request that has the specified name, value, and expiration time.

System_CAPS_pubmethodWrite(array<Byte>^, String^, DateTime, HttpContext^)

Writes a cookie associated with the specified request that has the specified name, value, and expiration time.

System_CAPS_pubmethodWrite(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.

System_CAPS_protmethodWriteCore(array<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.

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
Available since 4.5

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top
Show: