Figure 17-1 represents the general structure of the HTTP request message as defined by the HTTP/1.1 specifications.

Figure 17-1. Structure of a request message

Unless you are writing a browser, it is not necessary to understand the full details of the standard. However, a general understanding is useful to a developer who needs to extract information from the HttpRequest object. A few observations:

For debugging—or simply out of curiosity—you may want to view the raw contents of the HTTP request. A simple way to do this is to use the SaveAs method of the HttpRequest class to write the request to a file where it can be viewed with a text editor. The method, as shown here, takes two parameters: the name of the output file and a bool type switch that indicates whether HTTP headers are to be included in the output.

this.Request.SaveAs("c:\myrequest.txt",true);

Posting a form containing two text boxes to the Web server generates this sample output. Of most interest are the browser description, referring Web page, and text box content values.

POST /ideas/panel.aspx HTTP/1.1
Cache-Control: no-cache
Connection: Keep-Alive
Content-Length: 158
Content-Type: application/x-www-form-urlencoded
Accept: image/gif, image/x-xbitmap, image/jpeg, */*
Accept-Encoding: gzip, deflate
Accept-Language: en-us
Cookie: ASP.NET_SessionId=uszrfs45z4f20y45v0wyyp45
Host: localhost
Referer: http://localhost/ideas/panel.aspx
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; 
.NET CLR 1.0.3705; .NET CLR 1.1.4322; .NET CLR 2.0.40607)

__VIEWSTATE=%2FwEPDwULLTEwODExMTgwOTAPZBYCA ...
   &txtFirstName=joanna&txtLastName=larson&btnSubmit=Submit

Table 17-1 summarizes selected properties of the HttpRequest class. Where applicable, it includes the underlying header and message field on which its content is based.

The built-in features of ASP.NET reduce the amount of direct interaction required between an application and the HttpRequest object. For example, we saw in Section 16.2, “Web Forms Controls,” that ASP.NET Web controls generate code that is automatically tailored to the client's browser—eliminating the need for the application code to implement logic to identify the browser. There are, however, some cases where an application must access the object fields directly. Logging Web statistics is one; another is working with cookies.

Cookies are used to store information on the computer of a client that has cookies enabled on his browser. The browser is responsible for passing the cookie value as part of the request and handling any cookies returned from the server. The Cookies attribute references the collection of cookies returned by the browser. The following code loops through the collection displaying the name, value, and expiration date of cookies in the collection.

// Read cookies returned by browser
foreach(string cookieName in Request.Cookies.AllKeys){
   HttpCookie cookie = Request.Cookies[cookieName];
   Response.Write(cookie.Name+" = "+cookie.Value
                  +"<br>Expires: "+cookie.Expires);
}

The only cookie in this collection is the ID used by ASP.NET to identify sessions. ASP.NET's use of cookies is discussed further in the next section.

.NET_SessionId = avsqkn5501m3u2a41e3o4z55
Expires: 1/1/0001 12:00:00 AM 

The server responds with a status line that includes the message's protocol version, a success or error code, and a textual description of the error code. This is followed by the general header and the response header that provides information about the server. The entity header provides metainformation about the body contents or the resource requested.

ASP.NET provides the HttpWebRequest and HttpWebResponse classes for working with HTTP requests and responses, respectively. They are discussed in detail later in the chapter, but let's take a preliminary look at how they can be used to display portions of a response message.

Listing 17-1 contains a simple application that sends a request to a user-entered URL, receives the response, and extracts the status code and server description. Run the program from the command line by typing in the program name and domain name you want to contact:

//File: showserver.cs
using System; 
using System.Net; 
class WebClient
{
   // To run, type in:  showserver <domain name>
   public static void Main(string[] args) 
   {
      HttpWebRequest request; 
      HttpWebResponse response; 
      if(args.Length>0)
      {
         string url="http://"+args[0];
         // Create a request to the URL 
         request = (HttpWebRequest) WebRequest.Create(url); 
         try
         {
            response = (HttpWebResponse) request.GetResponse(); 
            Console.WriteLine("Web Host: "+response.Server);
            Console.WriteLine("Response Status: "+ 
                              response.StatusCode);
         } catch ( Exception ex)
         {
            Console.Write(ex.Message);
         }
      } else 
      {
         Console.Write("You must enter a domain name.");
      }
   }
}

Table 17-2 lists selected properties of the HttpResponse class. Some of those excluded exist only for ASP compatibility and have been deprecated by newer properties.

Particularly noteworthy is the Cache property, which can greatly affect how pages are displayed to a browser. It is used to define a caching policy that dictates if and how long pages are cached. We'll look at this property in Section 17.5, “Caching.”

An example that displayed the contents of a cookie was presented in the discussion of the HttpRequest class. Let's extend that example by demonstrating how the response object is used to create and return a cookie to the client.

// Create a cookie
HttpCookie myCookie = new HttpCookie("userid","007");
// Cookie will live for 10 minutes
// Timespan(days, hours, minutes, seconds)


myCookie.Expires = DateTime.Now.Add(new TimeSpan(0,0,10,0));
// Add to collection
Response.Cookies.Add(myCookie);
// Later... Read specific cookie
myCookie = Request.Cookies["userid"];
if(myCookie !=null) Response.Write("userid: "+myCookie.Value);

The Response.Write method, which we have used in numerous examples to emit output into the response stream, is the most commonly used method. Other useful methods include the following:

A simple, but useful, example (see Listing 17-2) illustrates how these methods can be used to download a file. The client request for this page includes a query string with the name of a requested file. The page locates the file (or returns an error message) and uses WriteFile to send it to the user. The AppendHeader, ClearContent, and End methods prepare and manage the response stream.

//File: requestfile.aspx
<%@ Page Language="C#"  %>
<script Language="C#"  runat="Server">
   private void Page_Load(object sender, EventArgs e)
   {
      //http://localserver/ideas/requestfile.aspx?file=notes.txt
      string fileRequest = Request.QueryString["file"];
      if(fileRequest!=null) {
         // File is store in directory of application
         string path = Server.MapPath(fileRequest);
         System.IO.FileInfo fi = new System.IO.FileInfo(path);
         if (fi.Exists) {
            Response.ClearContent(); // Clear the response stream


            // Add a header to indicate attachment type
            Response.AppendHeader("Content-Disposition", 
                                  "attachment;filename="+fi.Name);
            Response.AppendHeader("Content-Length",
                                  fi.Length.ToString());
            // Use octet-stream to indicate unknown media type
            Response.ContentType="application/octet-stream";  
            // Write file to output stream
            Response.WriteFile(fi.FullName);
            Response.End(); // Flush buffer output to the client
         }  else {
            Response.Write(path+" does not exist.");
         }
      } else {
         Response.Write("No Download file was specified.");
      }
   }
</script>

This area is used by developers to hold constant data values required by an application. These values typically include preference settings that define the appearance of a Web page. This entry illustrates how font settings are added using an <add> element and a key-value pair of attributes:

<add key="mainFont" value="arial" />

Values are retrieved from the appSettings section using the static AppSettings property of the ConfigurationSettings class:

myFont = ConfigurationSettings.AppSettings["mainFont"];

As mentioned previously, web.config files can be placed hierarchically within a directory structure, with files at lower levels overriding the settings of files in parent directories. This approach permits you to tailor the actions of ASP.NET down to the application and page level. However, this flexibility brings with it the potential problem of keeping track of the settings in multiple configuration files. As an alternative, ASP.NET provides a way to configure the settings for multiple directories in a single web.config file by using <location> elements. The <location> section operates as a configuration file within a configuration file. The element has a path attribute that takes the value of a virtual directory name. The settings within the contained <system.web> block apply to the virtual directory.

As an example, suppose that during application development we want to view the trace information as we test our applications. Because we don't want this voluminous output in the final product, we can set up a virtual “test” directory and enable tracing for that directory only.

<location path="test">
   <system.web>
      <trace enabled="true" pageOutput="true" />
   </system.web>
</location>  

This has the same effect as placing a web.config file with this trace setting in the physical directory associated with the “test” virtual directory.

This is the area in web.config where an administrator can configure just about any aspect of the ASP.NET environment. It can be used to set session time-out length, user authentication and authorization rules, the type of session state management used, and the default culture used for processing requests. Table 17-3 summarizes the more important elements in this section.

Of particular interest are the authentication, authorization, and membership elements that are discussed in Section 17.3, “ASP.NET Application Security.” Other useful sections are summarized here.

<compilation  debug="true"  defaultLanguage="C#"  />

<customErrors defaultRedirect = "defaultError.aspx" mode="On" >
   <error statusCode="404" redirect="Error404.aspx" />
</customErrors>

<trace
   enabled="true"
   pageOutput="false"
   traceMode="SortByTime"
    requestLimit="5",
   localOnly="false"
</trace>

<sessionState 
   mode="InProc"
   stateConnectString="tcpip=127.0.0.1:42424"
   sqlConnectionString="data 
       source=127.0.0.1;Trusted_Connection=yes"
   cookieless="false"
   timeout="15"
/>

<connectionStrings>
  <add name="movies"
    connectionString=
      "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=/movies.mdb;"
    providerName="System.Data.OleDb"/>
</connectionStrings>

string cs= 
ConfigurationSettings.ConnectionStrings["movies"].ConnectionString;

The web.config file plays an important role in supporting authentication and authorization in ASP.NET security. Listing 17-5 presents many of its elements and optional attribute values that are used to select and implement a security method.

The first thing to note is the mode attribute in the <authentication> element, which specifies the type of authentication being used. Contained in the <authentication> section is a <forms> tag or <passport> tag (not shown) that corresponds to the type of authentication chosen. The <forms> tag, which is used in a later example, contains several key attributes. The loginurl specifies the login page that a user is directed to when she has not been authenticated. The timeout attribute specifies how long a user may wait between requests before the authentication ticket expires. Thus, if the value is set to 5 minutes and the user has not requested a page in that interval, she is forced to log in again at her next request. The protection attribute specifies how, or if, ticket authentication information is processed before it is written to a cookie. You'll normally set this to All.

The <forms> element may contain a <credentials> element that can be used as a mini-database to list each user and his password. The advantage of placing them here, as we see in a later example, is that .NET authentication classes provide methods to automatically perform authentication against these names. To add a measure of security for storing the passwords, the passwordFormat attribute is provided to specify how the passwords are encrypted.

Web.config may also contain an <authorization> section that explicitly allows or denies access to users based on their name or role (think of role as a group the user belongs to). The <allow> and <deny> tags are processed in the order they occur in the file. When the tag's policy can be applied to the user, processing stops. If no allow or deny policy matches the user, the user is authorized to access the resource.

<Configuration>
   <system.web>
      <authentication mode="{Windows|Forms|Passport|None}">
         <forms name="Cookiename"
            loginurl="path to login file"
            timeout="minutes"
            protection="{None|All|Encryption|Validation}"
            path="Cookiepath"  >
         <credentials passwordFormat="Clear|MDS|SHA1}">
            <user name="User Name" password="password" />
         </credentials>  
         </forms>
      </authentication>

      <authorization>
         <allow users="comma-separated list" 
            roles="roles list" />
         <deny  users="comma-separated list" 
            roles="roles list />

      </authorization>
      ...
   </system.web>
   ...
</configuration>

The configuration file segment in this example is used for both user authentication and authorization. The <credentials> element contains the names and passwords of three users who may access the system. The <authorization> element contains rules that deny login access to all anonymous users as well as one individual user. Only users Joanna and Ruth are permitted to access the Web page.

<system.web>
   <authentication mode="Forms">
      <forms name="AppCookie" 
         loginUrl="applogin.aspx" protection="All"
         timeout="10" path="/"   >
         <credentials passwordFormat="Clear">
            <user name="joanna" password="chicago" />
            <user name="ruth"   password="raleigh" />
            <user name="kim"    password="newyork" />
         </credentials>
      </forms>
   </authentication>
   <authorization>
      <deny users="?,kim" />
   </authorization>

The same authorization rights can be granted by a combination of allow/deny rules:

<allow users="joanna,ruth"  />
<deny users="*" />

This denies access to all users (the asterisk (*) wildcard selects all users) except for those that are explicitly allowed. When both <allow> and <deny> are present, the order in which they are placed can be important. In this example, placing the <deny> rule first would deny access to all users, and the <allow> rule would be ignored.

The web.config file used in this example redirects the initial request for a Web page to applogin.aspx, which accepts login credentials and performs user authentication. The login part is easy—two text boxes are used to accept a user name and password. The technique for authenticating the user is more interesting.

Traditionally, login screens validate a user-supplied name and password against a database or file containing valid users. You are still free to do this in ASP.NET, but there are other options. These include storing names and passwords in the web.config file, or using the ASP.NET Membership class and its preconfigured database to manage user credentials. For demonstration purposes, this example uses web.config as the data store. Keep in mind that this is not the recommended approach if there are more than a few users, or multiple servers are used, which would require synchronizing the configuration file across machines.

As Listing 17-6 illustrates, the FormsAuthentication class plays the key role in authenticating a user and creating the authentication ticket that identifies the user. This important class provides static properties and methods that are used to manipulate and manage authentication information. Two of its methods are used here: Authenticate accepts a name and password, which it attempts to validate against the data in web.config; RedirectFromLoginPage redirects the user to the page originally requested, and creates an authentication cookie for the user. The second parameter to this method indicates whether the cookie should persist on the user's machine beyond the lifetime of the session.

<%@ Page Language="C#" %>
<html>
<head>
<title>login</title>
<script  runat="Server">
  void verify_Form(object sender, System.EventArgs e)
  {
    // Code to verify user against a database goes here...
    // or use .NET to verify user using web.config info.
    // Name and password are compared against web.config content
    if( FormsAuthentication.Authenticate(
           txtName.Text,txtPW.Text))
    {
      // Redirect to original form and 
      // create authentication ticket
      bool persistCookie=false;
      FormsAuthentication.RedirectFromLoginPage(txtName.Text, 
            persistCookie);
    }
    else
    { errmsg.Text="Cannot log in user."; }
  }
</script>
</head>
<body >
<form id=Form1 method=post runat="server">
  <asp:Panel id="pnlName" 
        style="Z-INDEX: 101; LEFT: 20px; POSITION: absolute; 
        TOP: 64px"
        BackColor = "#efefe4"
        Height="120px" Width="278px"
        runat="server" >
  <TABLE>
    <TR>
      <TD><asp:Label id="lblName" Runat="server" 
                 text="User ID:"></asp:Label></TD>
      <TD><asp:TextBox id="txtName" Runat="server"> 
             </asp:TextBox></TD></TR>
    <TR>
      <TD><asp:Label id="lblPW" Runat="server" 
                 text="Password:"></asp:Label></TD>
      <TD><asp:TextBox id="txtPW" TextMode="Password"
           Runat="server"> </asp:TextBox></TD></TR>
    <TR>
      <TD colspan=2 align=center>
          <asp:Button ID="btnSubmit" 
              Text="Submit" Font-Bold="true"
              OnClick="verify_Form" Runat="server" /></TD></TR>
    <TR>
      <TD colspan=2 align=center>
             <asp:Label id=errmsg runat="server" /></TD>
    </TR>
  </TABLE>
</asp:Panel>
</FORM>
</body>
</html>

Authentication is often only the first step in permitting a user to access Web resources; the second step is authorization—the process of determining what resources the user is authorized to access. If all users have full access, this step can be ignored. However, if a user's access rights, or role, are determined by membership in a group, this group must be identified and associated with the user.

After a user is created in ASP.NET, information about that user is available through the Page.User property. This property returns a principal object, so named because it implements the IPrincipal interface. This interface has two important members (see Figure 17-5) that the principal object implements: Identity, which can be used to get the name of the user, and the IsInRole method that is used to check a user's group membership.

Figure 17-5. User information is encapsulated in a GenericPrincipal object

The IsInRole method is passed a role name and returns a bool value indicating whether the user is in that role. It is the developer's task to assign the roles to the authenticated user object so that this method will have an internal list to check against. Looking at Figure 17-5, you would expect this list to be part of the GenericPrincipal object—and you would be right. The constructor for this class accepts as one of its parameters a string array of roles to be associated with the user. To assign these roles, the application can take advantage of the AuthenticateRequest event that occurs when the identity of a user is established. A handler for this event is placed in the global.asax file.

Listing 17-7 shows how code in the event handler assigns roles to the current user. It determines the user roles—in this case, calling GetRoles—and places them in a string array. This array, along with the current Identity, is passed to the GenericPrincipal constructor to create a new object that updates the value of the User property.

<%! file:global.asax %>
<%@ Import Namespace="System.Security" %>
<%@ Import Namespace="System.Security.Principal" %>
<%@ Application   %>
<script language = "C#" runat=server>
protected void Application_AuthenticateRequest(
                   object src, EventArgs e)
{
   if (Request.IsAuthenticated)
   {
      string currUser= Context.User.Identity.Name;
      string roles= GetRoles(currUser);
      string[] appRoles = roles.Split(new char[]{'|'});
      // Create GenericPrincipal class and add roles to it
      // GenericPrincipal(IIdentity identity, string[] roles)
      Context.User = new GenericPrincipal(
                         Context.User.Identity, appRoles);
   }
}
private string GetRoles( string username )
{
   // Code here would query database for user's role(s).
   // Return role as delimited string that can split into array.
   return "Administrator|Operator";
}

After the authentication steps are complete, an application may want to log information or make decisions based on information about the user. The User property exposes all of the members shown in Figure 17-5. Further authentication details, such as when the authentication cookie expires or when it was issued, can be obtained from properties exposed by the authentication ticket. As shown in Listing 17-8, an instance of the cookie is created and then converted to a FormsAuthenticationTicket object by using the Decrypt method of the FormsAuthentication class. The properties of this object are then displayed.

// Display authentication details
Response.Write("Client: "+ User.Identity.Name+"<br>");
if(User.IsInRole("Operator")) Response.Write(
          "Role: Operator<br>");
string cookieName = FormsAuthentication.FormsCookieName;
HttpCookie authCookie = Context.Request.Cookies[cookieName];
if(authCookie !=null)
{
   // Create ticket from cookie and display properties
   FormsAuthenticationTicket authTicket = null;
   authTicket = FormsAuthentication.Decrypt(authCookie.Value); 
   Response.Write("Issued: "+authTicket.IssueDate+"<br>");
   Response.Write("Expiration: "+authTicket.Expiration+"<br>");
   Response.Write("Persistent: "+authTicket.IsPersistent);
}

All sessions using the application may access the Application object through the Application property of the System.Web.UI.Page type. The only thing to note about accessing data is that it must be cast, because the information is stored as an object. Here is a segment that illustrates the primary properties and methods for working with the Application object:

int target = (int) Application["targetBMI"];
// Change value
Application["targetBMI"] = 22;
// List all HttpApplicationState values
foreach( string s in Application.AllKeys){
       Response.Output.Write("<br>{0} = {1}",s,Application[s]);
}
// Remove Application item
Application.Remove("obeseBMI");

Not illustrated are the Lock and UnLock methods that allow application variables to be updated in a thread-safe manner.

The variables contained in application state have two primary uses: as read-only data globally available across all of the application's sessions, and as variables that are updated to keep statistics regarding the application's use. Both of these uses can be handled more efficiently using a different approach.

The ASP.NET data cache provides a more flexible approach for making read-only data available on an application-wide basis. Its contents are as accessible as those in the application object, and it offers the advantage of having its contents automatically refreshed at a specified time interval. (Its use is described in Section 17.5.) As a rule-of-thumb, use application state to preload small amounts of read-only data required by an application; use the data cache when working with large amounts of data.

The problem with maintaining usage data in application state is that the data is available only during the life of the application. When it ends, the data is gone. In addition, if there are multiple servers, the data will apply to only one server. A better approach is store the information in a central database.

Core Note

Application recycling refers to shutting down and restarting an application based on criteria such as time, memory usage, and number of client requests. It is set using the <processModel> tag in the web.config file. The following setting recycles the application every two hours.

<processModel timeout="120">

By default, ASP.NET stores session state in-process using the aspnet_wp.exe process. This means that the information is managed in memory space where the application is running. This has the advantage of providing fast access to the data. The drawbacks are that it must run on a single server—precluding its use with Web farms—and that all session data is lost if the server reboots. Given this, it is recommended for single-server sites that need to maintain moderate amounts of data in state.

To select in-process session state management, set the mode attribute to InProc in the <sessionState> element of the web.config file. As shown here, you can also specify a time limit specifying how long the process may be idle before the session data is discarded.

<configuration>
   <system.web>
      <sessionState mode="InProc" timeout="30"/>
   </system.web>
</configuration>

The concept of out-of-process session state management entails the use of a mechanism outside of the application's process to store state data. ASP.NET provides two such mechanisms: a separate process running on a selected state server and the use of a data server to store state information.

When session state mode is used, session state is stored in the Aspnet_ state.exe process. This allows an application running on multiple servers to share state information. Because the server running this process is accessed via a network on the Internet, performance is slower than using the in-process approach. Also, the data is susceptible to a server reboot.

To access a state server, make sure the machine selected is running the Aspnet_state.exe process. Any server accessing the state server must set the <sessionState> element in its web.config file to point to the state server. The default port used is 42424. On a Windows-based operating system, this can be changed through the registry.

<configuration>
   <system.web>
      <sessionState mode="StateServer"  
         stateConnectionString="192.168.1.109:42424"
      />
   </system.web>
</configuration>

Using a SQL Server database to store session state data also offers the capability of sharing data among machines. In addition, SQL Server security features can be used to selectively provide access to the data; and, of course, the data is not transient because it exists in tables. The disadvantages of this approach are that it only works with Microsoft SQL Server and it is the slowest of the three session state modes.

To prepare a machine running SQL Server to handle session state requires no more than creating the tables that ASP.NET expects. The InstallPersistSqlState.sql script takes care of this. By default, the script is located in the systemrootMicrosoft.NETFrameworkversion folder. It creates a database named ASPState that contains the state tables.

Web.config is used to tell ASP.NET that session information for the application(s) is stored on a SQL Server. The <sessionState> element is set to specify the mode and connection string.

<configuration>
  <system.web>
    <sessionState mode="SQLServer"
      sqlConnectionString="datasource=x; user id=sa; password="/>
  </system.web>
</configuration>

SQL Server should be considered when there is a need to maintain data beyond the life of the session. For example, sites often persist the content of a shopping cart so it is available when the user logs in again.

Because the use of SQL Server slows Web page performance, it should be used only on those pages in an application that require state data. The @Page directive has an EnableSessionState attribute that dictates how state is used on the page. It can be set to false to disable session state, true to enable read and write session state, or readOnly.

The mandatory Duration attribute specifies the length, in seconds, that the page or control is cached. Setting this to 20 seconds generates the underlying statement:

Response.Cache.SetExpires(DateTime.Now.AddSeconds(20));

The Location attribute specifies where the caching can occur. In general, caching occurs on a server, browser, or somewhere in between, such as on a proxy server. The values of this attribute correspond to these locations: Any, Client, DownStream, Server, ServerAndClient, or None. DownStream refers to a cache-capable device other than the origin server. None disables caching everywhere.

In Chapter 16, we developed a BMI calculator Web page in which the user enters a height and weight value and the BMI value is returned. Because there are thousands of combinations of height (htf, hti) and weight (wt) parameters, several slightly different versions of the same page are likely to be created. The VaryByParam attribute is available for cases such as this. Its value indicates the parameter(s) (from a POST or query string) that should be considered when selecting a page to cache. For example, the following statement causes a page to be cached for each unique combination of wt, hti, and htf values:

<%@ OutputCache Duration="60"  VaryByParam="wt;hti;htf" %>

Figure 17-7 shows four requests that result in three unique pages being cached with their calculated BMI value. Note that we could have also assigned an asterisk (*) to VaryByParam to indicate that each parameter's value affects the cache.

Figure 17-7. Cachedpage: VaryByParam="wt;hti;htf"

Be aware that you can create some unexpected results if you set VaryByParam incorrectly. If only the wt parameter were specified in this example, requests with a weight of 168 and heights of 5'1" and 6'1" would return the same Web page. The page returned to both would be the one requested earliest.

VaryByHeader caches a different version of a page, based on the value of the Request Header fields (refer to Figure 17-1). This is the most commonly used with the Accept-Language field to ensure that different language versions of a Web page are cached.

The final conditional attribute to be familiar with is VaryByCustom. This is most useful when you have a Web page that is rendered differently depending on the client's browser type and version. To create different page versions by browser type, set the VaryByCustom attribute to "Browser".

<%@ OutputCache Duration="60"  VaryByParam="*"
                               VaryByCustom="Browser" %>

This attribute also can be set to recognize custom values that your program generates. Please refer to caching documentation for details on this.

All parts of a Web page are not created equally. Some, such as headers and links, rarely change, whereas other sections, such as the latest stock exchange quotes, change by the minute. A desirable caching strategy is to identify the static objects on the page and cache only those. This can be done in ASP.NET by creating custom controls (.ascx files) for the sections of the Web page to be cached. Custom controls have their own OutputCache directive that determines how they are cached, irrespective of the form containing them.

To illustrate the concept, let's create a simple control to be embedded within a Web page (see Figure 17-8). This segment simply contains a couple of links to other Web sites.

<!-- File: CacheFrag.ascx  -->
<%@ OutputCache Duration="30" VaryByParam="None" %>
<b>My Links</b><br>
<a href=http://www.moviesites.org>Movies</a><br>
<a href=http://www.imdb.com>Movie Reviews</a>
<br>

Figure 17-8. Example of custom control with its own caching policy

The application Web page to hold this control displays a title and date. Note that its caching is turned off by setting Location to None. The result is that only the control is cached.

<!-- File: CacheMain  -->
<%@ Page Language="C#"  %>
<%@ OutputCache Location="None" VaryByParam="*" %>
<%@ Register TagPrefix="frag" TagName="fraglinks" 
                Src="CacheFrag.ascx" %>
<HTML>
   <HEAD><TITLE>Sample Web Site</TITLE>
   <body>
      <center> <b>Fragment Sample</b>
      <br>
      <% Response.Output.Write(DateTime.Now.ToString("f")); %>
      </center>
      <frag:fraglinks id="fragmentlink" runat="server" />
   </body>
</html>

The simplest way to add data to a data cache is to use the key-value syntax of the Cache property of the Page class:

Cache["userid"] = "rigoletto";

The Cache.Insert method is often a better approach since it takes full advantage of the fact that each cache entry is actually an instance of the CacheEntry class. This class contains many useful properties that are set by passing parameters to the Insert method:

public void Insert(
   string key,
   object value,
   CacheDependency dependencies,
   DateTime absoluteExpiration,
   TimeSpan slidingExpiration,
   CacheItemPriority priority,
   CacheItemRemovedCallBack cb
);

Cache.Insert (
   "userid", 
   "rigoletto",
   null,
   DateTime.Now.AddMinutes(20),
   TimeSpan.Zero,
   CacheItemPriority.Normal,
      null
);

Either the absoluteExpiration or slidingExpiration parameter can be used to determine when the cached data expires. The former sets a specific date and time; the latter sets the expiration to occur a specified amount of time after the value is last accessed. To disable sliding expiration, assign the value Cache.NoSlidingExpiration.

The dependencies parameter allows cached data to be tied to files, directories, or other objects in the cache. Establishing this dependency causes the cached data to be removed when the object it is dependent upon changes. Thus, if cached data comes from a file and the file contents are modified, the data in the cache is removed.

string filename = "actors";
CacheDependency dep = new CacheDependency(fileName);
cache.Insert("key", "value", dep);

The priority parameter makes sense when you understand that data in a cache is not guaranteed to remain there. Because there is no limit on what can be placed in the cache, ASP.NET periodically invokes a resource scavenging process to remove less important data from the cache. The determination of what is important is based on the priority of the resource. By setting this priority to a CacheItemPriority enum value, you can reduce, or increase, its likelihood of being removed through scavenging. Enum values may be set to AboveNormal, BelowNormal, Default, High, Low, Normal, and NotRemovable.

To retrieve data from the cache, simply specify the key (case is ignored) of the desired data:

String user = (string) Cache["userid"];

Because the data is stored as an object, it is necessary to cast the result. If no data exists for the key, a null value is returned.

The true value of data caching comes into play when large amounts of data need to be saved to restore a page's state. As was explained in the previous chapter, ViewState automatically saves data and state information for Web controls on a page as long as the page posts to itself. Figure 17-9 illustrates this. In it, we have Web page A containing a list box populated with several hundred items from a database. In steps 1 and 2, a user performs some action that results in a modified version of the same page being returned to the client. State is retained automatically because the contents of the page's list box—and any other fields—are passed in the ViewState field.

Figure 17-9. Use a data cache to preserve information between separate pages

Suppose the user selects an item in the list box on page A that requires loading page B to show more details about the item. The server constructs the description as page B and returns it to the browser, discarding page A. After viewing this page, the user now wants to return to A. In the absence of caching, page A must be reconstructed by retrieving data from the database. To avoid this, the contents of the list box can be cached prior to navigating to page B (step 3):

// Step 3: Save listbox data before making server request 
Cache["listbox"]= actors.Items;

In step 6, page A is constructed using data from the cache to restore the list box.

// Step 6: Fill list box from cache
if(Cache["listbox"] !=null){
   ListItemCollection li= (ListItemCollection)Cache["listbox"];
   for(int i=0;i< li.Count; i++){
      ListItem a= li[i];
      actor.Items.Add(a);
   }
}
Cache["listbox"] = null;  // Clear cache

The cache is cleared after the page is restored; otherwise, both the cache and view state will contain the contents of the ListBox. It is worth noting that another option is to turn view state off for the ListBox (EnableViewState=false) and rely on caching to maintain its content.

Core Note

Data caching should be considered as a substitute for ViewState when data is read-only, or there is a large amount of it, or its update frequency is in minutes or hours rather than seconds, or when the data is not unique to individual users.

This file is stored in the root of the virtual directory containing the application(s) it is to be associated with. Its primary purpose is to hold the handlers that respond to the Application object's events. It is similar to an .aspx file in that it is compiled into an assembly when the Web application is first accessed. Unlike the Web page, however, it inherits from the HttpApplication class.

Here is a simple global.asax file that displays copyright information at the bottom of each page returned by an application in its virtual directory. It does this by implementing a custom handler for the EndRequest event. Notice that the format of the event handler for this, and all Application events in the global.asax file, is Application_eventname.

<%! file:global.asax %>
<%@ Application Language="C#" %>
<script runat=server>
protected void Application_EndRequest(object sender, EventArgs e)
{
   this.Context.Response.Output.Write(
      "<br>&copy2005 BMI Software");
}
</script>

Global.asax supports four other important events that are not members of the HttpApplication class: Application_Start, Application_End, Session_Start, and Session_End. The purpose of these events, which should be clear from their name, is to mark the beginning and end of an application and the sessions using it. They are the most frequently implemented event handlers in the global.asax file—performing the bookend operations of state initialization and cleanup. To illustrate this, let's extend the preceding global.asax example to keep track of the number of sessions that request an application and display this session number below the copyright.

The session counters are kept in an HttpApplicationState object represented by the Application property of the HttpApplication base class. It acts like a dictionary to hold information during the lifetime of an application (refer to Section 17.4, “Maintaining State”).

As shown in Listing 17-10, counters that track the number of sessions and sessions cancelled are initialized to zero when the Application_Start event fires. The session counter is incremented when a Session_Start occurs, and the counter for terminated sessions is incremented when a Session_Ends event occurs.

<%! global.asax %>
<%@ Application Language="C#" %>
<script language = "C#" runat=server>
// Can also use Application_OnStart syntax
void Application_Start(Object Sender, EventArgs e)
   {
      // Initialize counters with application scope
      Application["Sessions"] = 0;
      Application["TerminatedSessions"] = 0; 
   }
void Session_Start(Object Sender, EventArgs e)
   {
      Application.Lock();
      Application["Sessions"]=(int) Application["Sessions"] + 1;
      Application.UnLock();
   }
void Session_End(Object Sender, EventArgs e)
   {
      Application.Lock();
      Application["TerminatedSessions"] = 
         (int) Application["TerminatedSessions"] + 1;
      Application.UnLock();
   }
protected void Application_EndRequest(object sender,
                                      EventArgs e)
   {
      string sessionCt= "Session #: 
            "+Application["Sessions"].ToString();
      // Display copyright and current session number
      this.Context.Response.Output.Write(
            "<br>&copy2005 BMI Software<br>"+sessionCt);
   }
</script>

As with the .aspx file, code can be separated from the global.asax file and placed in a code-behind file. The code is compiled into a DLL and placed it in the in subdirectory of the application. The Inherits attribute of the Application directive points to the class implemented in the DLL.

To convert the preceding example to use a code-behind file, we remove code from the global.asax file, leaving only the Application directive:

<%! file:global.asax %>
<%@ Application  Inherits="sessionctr" %>

The code-behind file must be implemented as a class that inherits from HttpApplication. Here is a segment of the code:

// file: sessionctr.cs
using System;
using System.Web;
public class sessionctr: HttpApplication
{
   void Application_OnStart(Object Sender, EventArgs e)
   {
      Application["Sessions"] = 0;
      Application["TerminatedSessions"] = 0; 
   }
   // Remainder of assembly code goes here
}

There are two minimal requirements for building a functioning HttpModule: It must contain a class that implements the IHttpModule interface and it must register an event handler to process one of the HttpApplication events. An example of this is shown in Listing 17-12. The code adds copyright information to the bottom of all pages returned by the application—exactly the same function performed by the earlier global.asax file.

The IHttpModule interface consists of two methods—Init and Dispose—that must be accounted for. We use Init to register the event handler that will be called when the EndRequest event occurs. Note that access to the events is provided through the HttpApplication object that Init receives as a parameter.

using System;
using System.Web;
namespace CustomModules{
public class FooterModule: IHttpModule
{
   public void Init(HttpApplication httpApp)
   {
      httpApp.EndRequest += new EventHandler(this.OnEndRequest);
   }
   public void Dispose() {}
   // 
   public void OnEndRequest (Object obj, EventArgs e)
   {
      HttpApplication httpApp = (HttpApplication) obj;
      httpApp.Context.Response.Output.Write(
               "<br>&copy2005 BMI Software");
   }
}
}

To use the module with a Web application, compile it and place it in the in subdirectory of the application or in the Global Assembly Cache (GAC). Next, the assembly must be registered in either the web.config or machine.config file. In this example, we use a web.config file, which is placed in the root of the application's virtual directory. A portion of the file is shown here:

<configuration>
   <system.web>
      <httpModules>
         <add name="copyright"
         type="CustomModules.FooterModule, footmodule" />
      </httpModules>
   </system.web>
</configuration>

The key part is the <add> element that takes the form:

<add name=friendly name  type=class name, assembly />

This element is enclosed by the <httpModules> elements. Multiple <add> elements can be used to specify multiple modules.

URL rewriting is the process of changing a requested URL so that it is redirected to another resource. This is commonly used to ensure that bookmarked links continue to work when directories and resource names are changed on a Web server.

An HTTP module provides a convenient and easy-to-use approach for rewriting a URL. The implementation logic in the module is straightforward:

The most important issue to be resolved in developing a rewriter is selecting an event in the request's lifecycle where the URL checking and modification should occur. The three HttpAppliction event candidates are shown in Table 17-6, along with the criteria for selecting them. (Authentication is discussed in Section 17.5.)

In general, if no authentication is being used, place the rewrite logic in an event handler for the BeginRequest event.

Listing 17-13 contains code for a simple rewriter module with the rewriting logic included in the AuthorizeRequest event handler. Look closely at this code. It first calls a static method Rewrites.getRewrites() that returns a hash table in which the keys are old URLs and the associated value is the replacement URL. The hash table is checked to see if it contains the currently requested path and if it's in the table, a call is made to Context.RewritePath. The new URL is passed to it, and the method automatically takes care of details such as including any query string with the new URL.

using System;
using System.Web;
using System.Collections;
namespace CustomModules
{
   public class ReWriteModule: IHttpModule
   {
      public void Init(HttpApplication httpApp)
      {
         httpApp.AuthorizeRequest += new 
               EventHandler(this.OnAuthorizeRequest);
      }
      public void Dispose() {}
      // Determine if requested URL needs to be rewritten
      public void OnAuthorizeRequest( Object obj, EventArgs e)
      {
         // Get hash table containing old and replacement URLs
         Hashtable urls = Rewrites.getRewrites();
         HttpApplication httpApp = (HttpApplication) obj;
         // Get path of requested URL
         string path = httpApp.Context.Request.Path.ToUpper();
         // See if path is in hash table 
         if(urls.ContainsKey(path))
            path= (string)urls[path];
         httpApp.Context.RewritePath(path);   // Rewrite URL
      }
   }
}

The module is registered by placing the following entry in the web.config file:

<add name="redirector"
       type="CustomModules.ReWriteModule, rewritemodule" />

The process of identifying URLs to be rewritten can be implemented in various ways. This example stores the old and replacement URLs in an XML file using the following format:

<!--  File: redirector.xml   -->
<RewriterConfig>
   <RewriterRules>
      <Rule>
         <OldPath>/ideas/calculator.aspx</OldPath>
         <NewPath>/utilities/calculator.aspx</NewPath>
      </Rule>
      <Rule>
         <OldPath>/ideas/bmi.aspx</OldPath>
         <NewPath>/utilities/bminew.aspx</NewPath>
      </Rule>
   </RewriterRules>
</RewriterConfig>

This information could also be stored in the web.config file, although some overhead is required to do this. For details, refer to “Adding a Custom Configuration Section” on page 824.

In many cases, the functionality you want to add to a Web server environment can be implemented using HTTP modules or the global.asax file. As a guide to making the choice, let's review their features:

Either can be used to handle HttpApplication events. If the feature being added applies to all applications on the server, a module is the better choice; if the feature is specific to an application, use a global.asax file.

ASP.NET provides handlers for .aspx, .soap, .asmx (Web services), and other standard ASP.NET file types. So why create a custom handler? The primary motivation is to support new file extensions or existing file extensions that require added processing features. For example, when a text file (.txt) is requested, ASP.NET simply returns the contents of the file. As an exercise, let's improve this with a handler that accepts a URL with the name of the text file and a query string parameter that specifies a keyword to search for in the file. The output from the handler is a listing of the text file with all instances of the keyword highlighted, as well as a count of the number of times the keyword occurs in the document.

The IHttpHandler interface contains two members that must be implemented in our custom handler class: the ProcessRequest method and the Reuseable property. As shown in Listing 17-14, ProcessRequest contains the code that processes the HTTP request; IsReusable indicates whether the instance of the handler can be reused for other requests. This is applicable only when a handler factory is providing handlers and pools them for reuse.

This handler responds to URL requests that contain a text file and query string containing a keyword to search for in the file:

HTTP://www.scilibrary.com/films.txt?kwd=Bogart

The context object provides access to the file name through the Request.PhysicalPath property. An attempt is made to open the text file and read it line by line. Each line is searched for the keyword using Regex.Match. If a match is found, the method BoldWord is called to place HTML bold (<b>) tags around the text. This method also increments the word counter.

// file: txthandler.cs
using System;
using System.Web;
using System.IO;
using System.Text.RegularExpressions;
public class TextHandler: IHttpHandler
{
   static int wordCt=0;
   static string BoldWord(Match m) 
   {
      // Get the matched string and place bold tags around it
      string kwd = m.ToString();
      kwd="<b>"+kwd+"</b>";
      wordCt += 1;
      return kwd;
   }
   public void ProcessRequest(HttpContext ctx)
   {
   // Get file to be opened
   string filePath= ctx.Request.PhysicalPath;
   int ndx= filePath.LastIndexOf(@"");
   string fileName = filePath.Substring(ndx+1);
   // Keyword to search for in file
   string keyWord = ctx.Request["kwd"];
   // Create HTML response
   ctx.Response.Output.Write("<html><body >");
   ctx.Response.Output.Write("File: "+fileName+
            " &nbsp;Keyword: <b>"+keyWord+"</b><hr size=1>");
   string line;
   try {
      StreamReader reader= new StreamReader(filePath);
      // Read lines of file and display in response 
      while ((line = reader.ReadLine()) != null) 
      {
         if (keyWord!= null) {
         // search for keyword and highlight
            string newLine = Regex.Replace(line, keyWord,
                 new MatchEvaluator(TextHandler.BoldWord), 
                                    RegexOptions.IgnoreCase);
            line= newLine;
         }
         ctx.Response.Output.Write("<br>"+line);
      }
      reader.Close();
   } catch (Exception e)
   {
      ctx.Response.Output.Write("<br>"+e.Message);
   }
   // Display number of matches
   ctx.Response.Output.Write("<br><br>Word Matches: " + 
          wordCt.ToString());
   ctx.Response.Output.Write("</body></html>");
   wordCt=0; // reset since it is static
   }
   public bool IsReusable
   {
      get {return false;}
   }
}

The final code is compiled and placed in the in subdirectory of the application.

For ASP.NET to be aware of the handler, an entry is made in the machine.config or application's web.config file. In this example, we place an <add> element in the web.config file. This element contains three attributes that define the handler and the conditions for using it. Verb specifies the type of request to be handled, such as GET or POST. The * is a wildcard character that represents any type request. The path attribute indicates the requested resource name that is mapped to the handler; and type specifies the handler class or handler factory and its containing assembly.

<httpHandlers>
   <add verb="*" path="*.txt" type="TextHandler,txthandler"/>
</httpHandlers>

The final step in deployment is to make IIS (Internet Information Service) aware that requests for the .txt extension are to be handled by ASP.NET. This is done by using Internet Services Manager to map the file extension to the ISAPI extension DLL (aspnet_isapi.dll). Follow these steps:

With these steps completed, TextHandler is now called to process all requests for .txt files. Figure 17-12 shows output from a sample request.

Figure 17-12. Output from HTTP handler that displays text files

Core Note

If an extension used by an HTTP handler is not mapped in IIS to ASP.NET, IIS attempts to return the contents of any file requested having that extension. ASP.NET never sees the request.