The HttpResponse Object
The HttpResponse Object
In ASP.NET, the HTTP response information is encapsulated in the HttpResponse class. An instance of the class is created when the HTTP pipeline is set up to serve the request. The instance is then linked to the HttpContext object associated with the request and exposed via the Response property. The HttpResponse class defines methods and properties to manipulate the text that will be sent to the browser. Although user-defined ASP.NET code never needs to use the HttpResponse constructor, looking at it is still useful to get the gist of the class:
public HttpResponse(TextWriter writer);
As you can see, the constructor takes a writer object, which will then be used to accumulate the response text. All calls made to Response.Write (and similar output methods) are resolved in terms of internal calls to the specified writer object.
Properties of the HttpResponse Class
All properties of the class are grouped and described in Table 12-10. You set a few of these properties to configure key fields on the HTTP response packet, such as content type, character set, page expiration, and status code.
| Property | Description |
|---|---|
| Buffer | Indicates whether the response text should be buffered and sent only at the end of the request. This property is deprecated and provided only for backward compatibility with classic ASP. ASP.NET applications should instead use BufferOutput. |
| BufferOutput | Gets or sets a Boolean value that indicates whether response buffering is enabled. The default is true. |
| Cache | Gets the caching policy set for the page. The caching policy is an HttpCachePolicy object that can be used to set the cache-specific HTTP headers for the current response. |
| CacheControl | Sets the Cache-Control HTTP header. Acceptable values are Public, Private, or No-Cache. The property is deprecated in favor of Cache. |
| Charset | Gets or sets a string for the HTTP character set of the output stream. If set to null, it suppresses the Content-Type header. |
| ContentEncoding | Gets or sets an object of type Encoding for the character encoding of the output stream. |
| ContentType | Gets or sets the string that represents the MIME type of the output stream. The default value is text/html. |
| Cookies | Gets a collection (HttpCookieCollection) object that contains instances of the HttpCookie class generated on the server. All the cookies in the collection will be transmitted to the client through the set-cookie HTTP header. |
| Expires | Gets or sets the number of minutes before a page cached on a browser expires. Provided for compatibility with ASP, the property is deprecated in favor of Cache. |
| ExpiresAbsolute | Gets or sets the absolute date and time at which the page expires in the browser cache. Provided for compatibility with ASP, the property is deprecated in favor of Cache. |
| Filter | Gets or sets a filter Stream object through which all HTTP output is directed. |
| IsClientConnected | Indicates whether the client is still connected. |
| IsRequestBeingRedirected | Indicates whether the request is being redirected. Not available in ASP.NET 1.x. |
| Output | Gets the writer object used to send text out. |
| OutputStream | Gets the Stream object used to output binary data to the response stream. |
| RedirectLocation | Gets or a sets a string for the value of the Location header. |
| Status | Sets the string returned to the client describing the status of the response. Provided for compatibility with ASP, the property is deprecated in favor of StatusDescription. |
| StatusCode | Gets or sets an integer value for the HTTP status code of the output returned to the client. The default value is 200. |
| StatusDescription | Gets or sets the HTTP status string, which is a description of the overall status of the response returned to the client. The default value is OK. |
| SuppressContent | Gets or sets a Boolean value that indicates whether HTTP content should be sent to the client. This is set to false by default; if it is set to true, only headers are sent. |
As you can see, a few of the HttpResponse properties are provided only for backward compatibility with classic ASP. In some cases (for example, BufferOutput), the property has just been renamed; in other cases, the deprecated properties have been replaced by a more general and powerful API. This is certainly the case for cache and expiration properties.
Setting the Response Cache Policy
The response object has three properties dedicated to controlling the ability of the page being sent to the browser to be cached. The Expires and ExpiresAbsolute properties define relative and absolute times at which the page cached on the client expires and is no longer used by the browser to serve a user request. In fact, if the user navigates to a currently cached page, the cached version is displayed and no roundtrip occurs to the server. CacheControl is a third property somehow related to page caching. The property sets a particular HTTP header the Cache-Control header. The Cache-Control header controls how a document is to be cached across the network. These properties represent the old-fashioned programming style and exist mostly for compatibility with classic ASP applications.
In ASP.NET, all caching capabilities are grouped in the HttpCachePolicy class. With regard to page caching, the class has a double role. It provides methods for both setting cachespecific HTTP headers and controlling the ASP.NET page output cache. (In this chapter, we're mostly interested in the HTTP headers, and we'll keep page output caching warm for Chapter 14.)
To set the visibility of a page in a client cache, use the SetCacheability method of the HttpCachePolicy class. To set an expiration time, use the SetExpires method, which takes for input an absolute DateTime object. Finally, to set a lifetime for the cached page, pass to SetExpires the current time plus the desired interval.
| Note | In the case of conflicting cache policies, ASP.NET maintains the most restrictive settings. For example, if a page contains two controls that set the Cache-Control header to public and private, the most restrictive policy will be used. In this case, Cache-Control: Private is what will be sent to the client. |
Setting an Output Filter
In ASP.NET, a new component makes its debut the response filter. A response filter is a Stream-derived object associated with the HttpResponse object. It monitors and filters any output being generated by the page. If you set the Filter property with the instance of a class derived from Stream, all output being written to the underlying HTTP writer first passes through your output filter.
The custom filter, if any, is invoked during the HttpResponse's Flush method before the actual text is flushed to the client. An output filter is useful for applying the final touches to the markup, and it is sometimes used to compact or fix the markup generated by controls.
Building a response filter is a matter of creating a new stream class and overriding some of the methods. The class should have a constructor that accepts a Stream object. In light of this, a response filter class is more a wrapper stream class than a purely inherited stream class. If you simply try to set Response.Filter with a new instance of, say, MemoryStream or FileStream, an exception is thrown.
The following listing shows how to create a stream class that works as a response filter. For simplicity, the class inherits from MemoryStream. You might want to make it inherit from Stream, but in this case you need to override a number of methods, such as CanRead, CanWrite, CanSeek, and Read (because they are abstract). The class converts lowercase characters to uppercase ones:
public class MyFilterStream : MemoryStream { private Stream m_Stream; public MyFilterStream(Stream filterStream) { m_Stream = filterStream; } // The Write method actually does the filtering public override void Write(byte[] buffer, int offset, int count) { // Grab the output as a string string buf = UTF8Encoding.UTF8.GetString(buffer, offset, count); // Apply some changes // Change lowercase chars to uppercase buf = buf.ToUpper(); // Write the resulting string back to the response stream byte[] data = UTF8Encoding.UTF8.GetBytes(buf.ToString()); m_Stream.Write(data, 0, data.Length); } } Use the following code to associate this output filter with the Response.Filter property. Here's a sample page:
void Page_Load(object sender, EventArgs e) { Response.Filter = new MyFilterStream(Response.Filter); } Figure 12-5 shows a page that uses the sample filter.
Figure 12-5: This page uses a response filter to turn on uppercase characters.
