System.Net.CookieContainer Class

Summary

Provides a container for a collection of CookieCollection objects.

C# Syntax:

[Serializable] public class CookieContainer

A CookieContainer is a data structure that provides storage for instances of the Cookie class, and which is accessed in a database-like manner. The CookieContainer has a capacity limit which is set when the container is created, or changed by a property.

An instance of the Cookie class is added to the container based on its originating URI. It is added to an internal CookieCollection associated with the URI. A Cookie is retrieved from the container based on the URI as a CookieCollection, or as a string which can be used to submit HTTP WebRequests.

The CookieContainer has three properties that govern the volume of the content of the container: CookieContainer.Capacity, CookieContainer.MaxCookieSize, and CookieContainer.PerDomainCapacity. These values have the default settings of 300, 4096, and 20 respectively. When a Cookie is added to the container, these properties are used to determine whether a Cookie already contained in the CookieContainer should be discarded to make room for the new one. The CookieContainer keeps track of each addition to ensure that neither the CookieContainer.Capacity nor the CookieContainer.PerDomainCapacity limits are exceeded. If one or both are exceeded, then Cookie instances held by the CookieContainer are removed. First, any expired Cookie is removed. If further capacity must be recaptured, then the least-recently-used CookieCollection is purged.

System.Net Namespace | Cookie | CookieCollection | CookieContainer | CookieException | ICollection

System.Net.CookieContainer Member List:

Public Constructors

ctor #1	Overloaded: .ctor() Default constructor. This constructor is called by derived class constructors to initialize state in this type. Initializes a new instance of the CookieContainer class.
ctor #2	Overloaded: .ctor(int capacity) Initializes a new instance of the CookieContainer class with a specified value for the number of Cookie instances the container can hold.
ctor #3	Overloaded: .ctor(int capacity, int perDomainCapacity, int maxCookieSize) Initializes a new instance of the CookieContainer class with specific properties.

Public Fields

DefaultCookieLengthLimit	Represents the default maximum size, in bytes, of the Cookie instances the CookieContainer can hold. This field is constant.
DefaultCookieLimit	Represents the default maximum number of Cookie instances the CookieContainer can hold. This field is constant.
DefaultPerDomainCookieLimit	Represents the default maximum number of Cookie instances the CookieContainer can reference per domain. This field is constant.

Public Properties

Capacity	Read-write Gets and sets the number of Cookie instances a CookieContainer can hold.
Count	Read-only Gets the number of Cookie instances a CookieContainer currently holds.
MaxCookieSize	Read-write Represents the maximum allowed length of a Cookie.
PerDomainCapacity	Read-write Gets and sets the number of Cookie instances a CookieContainer can hold per domain.

Public Methods

Add	Overloaded: Add(Cookie cookie) Adds a Cookie to a CookieContainer. This method uses the domain from the Cookie to determine which domain collection to associate the Cookie with.
Add	Overloaded: Add(CookieCollection cookies) Adds the contents of a CookieCollection to the CookieContainer.
Add	Overloaded: Add(Uri uri, Cookie cookie) Adds a Cookie to the CookieContainer for a particular URI.
Add	Overloaded: Add(Uri uri, CookieCollection cookies) Adds the contents of a CookieCollection to the CookieContainer for a particular URI.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
GetCookieHeader	Gets the HTTP cookie header containing the HTTP cookies representing the Cookie instances associated with a specific URI.
GetCookies	Gets A CookieCollection containing the Cookie instances associated with a specific URI.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
SetCookies	Adds Cookie instances for one or more cookies from an HTTP cookie header to the CookieContainer for a specific URI.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.

Protected Methods

Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

• System.Object
• System.Net.CookieContainer

System.Net.CookieContainer Member Details

Summary

Initializes a new instance of the CookieContainer class.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

C# Syntax:

public CookieContainer();

The default constructor initializes all fields to their default values. CookieContainer.DefaultCookieLimit is used to initialize CookieContainer.Capacity, CookieContainer.DefaultCookieLengthLimit is used for CookieContainer.MaxCookieSize, and CookieContainer.DefaultPerDomainCookieLimit is used for CookieContainer.PerDomainCapacity.

Return to top

Summary

Initializes a new instance of the CookieContainer class with a specified value for the number of Cookie instances the container can hold.

C# Syntax:

public CookieContainer(    int capacity );

capacity

The number of Cookie instances the CookieContainer can hold.

Exceptions

Exception Type	Condition
ArgumentException	capacity is less than or equal to zero

CookieContainer.PerDomainCapacity is initialized to 20, and CookieContainer.MaxCookieSize is initialized to 4096.

Return to top

Summary

Initializes a new instance of the CookieContainer class with specific properties.

C# Syntax:

public CookieContainer(    int capacity,    int perDomainCapacity,    int maxCookieSize );

capacity

The number of Cookie instances the CookieContainer can hold.

perDomainCapacity

The number of Cookie instances per domain.

maxCookieSize

The maximum size in bytes for any single Cookie in a CookieContainer.

Exceptions

Exception Type	Condition
ArgumentException	perDomainCapacity is not equal to Int32.MaxValue and (perDomainCapacity is less than or equal to zero or perDomainCapacity is greater than capacity)
ArgumentException	maxCookieSize is less than or equal to zero

The parameters specify values for CookieContainer.Capacity, CookieContainer.MaxCookieSize, and CookieContainer.PerDomainCapacity.

Return to top

Summary

Represents the default maximum size, in bytes, of the Cookie instances the CookieContainer can hold. This field is constant.

C# Syntax:

public const int DefaultCookieLengthLimit;

The default maximum Cookie size is 4096.

Return to top

Summary

Represents the default maximum number of Cookie instances the CookieContainer can hold. This field is constant.

C# Syntax:

public const int DefaultCookieLimit;

The default maximum number of Cookie instances is 300.

Return to top

Summary

Represents the default maximum number of Cookie instances the CookieContainer can reference per domain. This field is constant.

C# Syntax:

public const int DefaultPerDomainCookieLimit;

The default maximum number of Cookie instances per domain is 20.

Return to top

Summary

Gets and sets the number of Cookie instances a CookieContainer can hold.

C# Syntax:

public int Capacity {get; set;}

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	Capacity is less than or equal to zero or (value is less than CookieContainer.PerDomainCapacity and CookieContainer.PerDomainCapacity is not equal to Int32.MaxValue).

If CookieContainer.Count equals or exceeds CookieContainer.Capacity, one or more Cookie instances are removed from the container. Enough instances are removed to bring CookieContainer.Count below CookieContainer.Capacity as follows: if there are expired Cookie instances in scope they are cleaned up. If not, then the least recently used CookieCollection is found and removed from the container.

CookieContainer.Capacity must be greater than or equal to CookieContainer.PerDomainCapacity. If you set CookieContainer.PerDomainCapacity and the current CookieContainer.Count of Cookie instances is less than the new value, the excess is removed from the container. Enough instances are removed to bring CookieContainer.Count below CookieContainer.Capacity as follows: if there are expired Cookie instances in scope they are cleaned up. If not, or if there are still more than the new value of CookieContainer.PerDomainCapacity, then the least recently used CookieCollection is found and removed from the container.

Return to top

Summary

Gets the number of Cookie instances a CookieContainer currently holds.

C# Syntax:

public int Count {get;}

The default value of this property is CookieContainer.DefaultCookieLimit. If CookieContainer.Count equals or exceeds CookieContainer.Capacity, one or more Cookie instances are removed from the container. Enough instances are removed to bring CookieContainer.Count below CookieContainer.Capacity as follows: if there are expired Cookie instances in scope they are cleaned up. If not, then the least recently used CookieCollection is found and removed from the container.

Return to top

Summary

Represents the maximum allowed length of a Cookie.

C# Syntax:

public int MaxCookieSize {get; set;}

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	MaxCookieSize is less than or equal to zero

If the new value of CookieContainer.MaxCookieSize is less than the current value, any Cookie with length exceeding the new value will be truncated.

Return to top

Summary

Gets and sets the number of Cookie instances a CookieContainer can hold per domain.

C# Syntax:

public int PerDomainCapacity {get; set;}

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	PerDomainCapacity is less than or equal to zero or (PerDomainCapacity is greater than the maximum allowable number of cookies instances, 300, and is not equal to Int32.MaxValue)

If the new CookieContainer.PerDomainCapacity value is less than the current value, and if any of the domain collections contain more Cookie instances than the new value, the collections are pruned to fit. This uses the same basic rules as described in the CookieContainer.Capacity property. However, this does the clean-up only on the collection for this domain.

Return to top

Summary

Adds a Cookie to a CookieContainer. This method uses the domain from the Cookie to determine which domain collection to associate the Cookie with.

C# Syntax:

public void Add(    Cookie cookie );

cookie

The Cookie to be added to the CookieContainer.

Exceptions

Exception Type	Condition
ArgumentNullException	cookie is null
ArgumentException	domain for cookie is null
CookieException	cookie is larger than maxCookieSize

If the CookieContainer.Count property equals or exceeds the CookieContainer.Capacity property, one or more Cookie instances are removed from the container before adding the cookie parameter. Enough Cookie instances are removed to bring CookieContainer.Count below CookieContainer.Capacity as follows: if there are expired instances in given scope they are cleaned up. If not, then the least recently used CookieCollection is found and removed from the container.

Return to top

Summary

Adds the contents of a CookieCollection to the CookieContainer.

C# Syntax:

public void Add(    CookieCollection cookies );

cookies

The CookieCollection to be added to the CookieContainer.

Exceptions

Exception Type	Condition
ArgumentNullException	cookies is null

If the CookieContainer.Count property equals the CookieContainer.Capacity property, one or more Cookie instances are removed from the container before adding the contents of the cookies parameter. Enough Cookie instances are removed to make room for cookies as follows: if there are expired instances they are cleaned up. If not, or if more room is needed, then the least recently used CookieCollection is found and removed from the container.

Return to top

Summary

Adds a Cookie to the CookieContainer for a particular URI.

C# Syntax:

public void Add(    Uri uri,    Cookie cookie );

uri

The URI of the Cookie to be added to the CookieContainer.

cookie

The Cookie to be added to the CookieContainer.

Exceptions

Exception Type	Condition
ArgumentNullException	uri is null
ArgumentNullException	cookie is null

If you add a Cookie instance for just one specific host, don't set the Cookie.Domain property of the Cookie instance. This is set automatically, based on the URI.

If your URI corresponds to your local domain and sends to all the hosts on the local domain, set the Cookie Cookie.Domain property equal to ".local". Otherwise, make sure it matches the host name used in the URI.

If the Cookie Cookie.Version is Netscape, the Cookie.Path property of the Cookie, if not set explicitly, is derived from the URI and is the complete path from the URI, including the page name.

If the CookieContainer.Count property equals the CookieContainer.Capacity property, one or more Cookie instances are removed from the container before adding the cookie parameter. Enough Cookie instances are removed to bring CookieContainer.Count below CookieContainer.Capacity as follows: if there are expired instances in scope they are cleaned up. If not, then the least recently used CookieCollection is found and removed from the container.

Return to top

Summary

Adds the contents of a CookieCollection to the CookieContainer for a particular URI.

C# Syntax:

public void Add(    Uri uri,    CookieCollection cookies );

uri

The URI of the CookieCollection to be added to the CookieContainer.

cookies

The CookieCollection to be added to the CookieContainer.

Exceptions

Exception Type	Condition
ArgumentNullException	uri is null
ArgumentNullException	cookies is null

If you add a Cookie instance for just one specific host, don't set the Cookie.Domain property of the Cookie instance. This is set automatically, based on the URI.

If your URI corresponds to your local domain and sends to all the hosts on the local domain, set the Cookie Cookie.Domain property equal to ".local". Otherwise, make sure it matches the host name used in the URI.

If CookieContainer.Count equals CookieContainer.Capacity, one or more Cookie instances is removed from the container before adding the cookie parameter. Enough Cookie instances are removed to bring CookieContainer.Count below CookieContainer.Capacity as follows: if there are expired instances in scope they are cleaned up. If not, then the least recently used CookieCollection is found and removed from the container.

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.Finalize

C# Syntax:

~CookieContainer();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Gets the HTTP cookie header containing the HTTP cookies representing the Cookie instances associated with a specific URI.

C# Syntax:

public string GetCookieHeader(    Uri uri );

uri

The URI of the Cookie instances desired.

Return Value:

An HTTP cookie header, with strings representing Cookie instances delimited by semicolons.

Exceptions

Exception Type	Condition
ArgumentNullException	uri is null

CookieContainer.GetCookieHeader returns a string that holds the HTTP cookie header for the Cookie instances specified by uri. The HTTP header is built by adding a string representation of each Cookie associated with uri. Note the exact format of the string depends on the RFC the Cookie conforms to. The strings for all the Cookie instances associated with uri are combined and delimited by semicolons.

This string is not in the correct format for use as the second parameter of the CookieContainer.SetCookies method.

Return to top

Summary

Gets A CookieCollection containing the Cookie instances associated with a specific URI.

C# Syntax:

public CookieCollection GetCookies(    Uri uri );

uri

The URI of the Cookie instances desired.

Return Value:

A CookieCollection containing the Cookie instances associated with a specific URI.

Exceptions

Exception Type	Condition
ArgumentNullException	uri is null

A new instance of a CookieCollection is created. Then the Cookie instances in the internal collection associated with the specified URI are read out and added to the new CookieCollection.

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Adds Cookie instances for one or more cookies from an HTTP cookie header to the CookieContainer for a specific URI.

C# Syntax:

public void SetCookies(    Uri uri,    string cookieHeader );

uri

The URI of the CookieCollection.

cookieHeader

The contents of an HTTP set-cookie header as returned by a HTTP server, with Cookie instances delimited by commas.

Exceptions

Exception Type	Condition
ArgumentNullException	uri is null
ArgumentNullException	cookieHeader is null

CookieContainer.SetCookies pulls all the HTTP cookies out of the HTTP cookie header, builds a Cookie for each one, and then adds each Cookie to the internal CookieCollection associated with the URI. The HTTP cookies in the cookieHeader string must be delimited by commas.

Return to top

Inherited
See base class member description: System.Object.ToString

C# Syntax:

public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Top of page