The global.asax file supports three directives: @Application, @Import, and @Assembly. The @Import and @Assembly directives work as shown in Chapter 3. The @Import directive imports a namespace into an application; the @Assembly directive links an assembly to the application at compile time.

The @Application directive supports a few attributes: Description, Language, and Inherits. Description can contain any text you want to use to describe the behavior of the application. This text has only a documentation purpose and is blissfully ignored by the ASP.NET parser. Language indicates the language being used in the file. The Inherits attribute indicates a code-behind class for the application to inherit. It can be the name of any class derived from the HttpApplication class. The assembly that contains the class must be located in the Bin subdirectory of the application.

A global.asax file can contain code wrapped by a <script> tag. Just as for pages, the <script> tag must have the runat attribute set to server. The language attribute indicates the language used throughout:

<script language="C#" runat="server">
    ...
</script>

If the language attribute is not specified, ASP.NET defaults to the language set in the configuration, which is Microsoft Visual Basic .NET. The source code can also be loaded from an external file, whose virtual path is set in the Src attribute. The location of the file is resolved using Server.MapPath—that is, starting under the physical root directory of the Web application.

<script language="C#" runat="server" src="somecode.aspx.cs" />

In this case, any other code in the declaration <script> block is ignored. Notice that ASP.NET enforces syntax rules on the <script> tag. The runat attribute is mandatory, and if the block has no content, the Src must be specified.

The server-side <object> tag lets you create new objects using a declarative syntax. The <object> tag can take three forms, as shown in the following lines of code, depending on the specified reference type:

<object id="..." runat="server" scope="..." class="..." />
<object id="..." runat="server" scope="..." progid="..." />
<object id="..." runat="server" scope="..." classid="..." />

In the first case, the object is identified by the name of the class and assembly that contains it. In the last two cases, the object to create is a COM object identified by the program identifier (progid) and the 128-bit CLSID, respectively. As one can easily guess, the classid, progid, and class attributes are mutually exclusive. If you use more than one within a single server-side <object> tag, a compile error is generated. Objects declared in this way are loaded when the application is started.

The scope attribute indicates the scope at which the object is declared. The allowable values are defined in Table 16-5. Unless otherwise specified, the server-side object is valid only within the boundaries of the HTTP pipeline that processes the current request. Other settings that increase the object’s lifetime are application and session.

If you define static properties in the global.asax file, they will be accessible for reading and writing by all pages in the application:

<script language="C#" runat="server">
    public static int Counter = 0;
</script>

The Counter property defined in the preceding code works like an item stored in Application—namely, it is globally visible across pages and sessions. Consider that concurrent access to Counter is not serialized; on the other hand, you have a strong-typed, direct global item whose access speed is much faster than retrieving the same piece of information from a generic collection such as Application.

To access the property from a page, you must use the ASP.global_asax qualifier, shown here:

Response.Write(ASP.global_asax.Counter.ToString());

If you don’t particularly like the ASP.global_asax prefix, you can alias it as long as you use C#. Add the following code to a C#-based page (or code-behind class) for which you need to access the globals:

using Globals = ASP.global_asax;

The preceding statement creates an alias for the ASP.global_asax class (or whatever name your global.asax class has). The alias—Globals in this sample code—can be used throughout your code wherever ASP.global_asax is accepted. In ASP.NET 4, however, you can also rely on the dynamic type.

The RewritePath method lets you change the URL of the current request on the fly, thus performing a sort of internal redirect. As a result, the displayed page is the one you set through RewritePath; the page shown in the address bar remains the originally requested one. The change of the final URL takes place on the server and, more importantly, within the context of the same call. RewritePath should be used carefully and mainly from within the global.asax file. If you use RewritePath in the context of a postback event, you can experience some view-state problems.

protected void Application_BeginRequest(Object sender, EventArgs e)
{
   var context = HttpContext.Current;
   var o = context.Request["id"];
   if (o != null)
   {
      var id = (Int32) o;
      var url = GetPageUrlFromId(id);
      context.RewritePath(url);
   }
}
protected String GetPageUrlFromId(Int32 id)
{
   // Return a full URL based on the input ID value.
   ...
}

The preceding code rewrites a URL such as page.aspx?id=1234 to a specific page whose real URL is read out of a database or a configuration file.

In Chapter 7, we discussed expressions allowed in ASP.NET pages to bind control properties to embedded global or local resources. The $Resources and meta:resourcekey expressions for global and local resources, respectively, work only at design time. What if you need to generate text programmatically that embeds resource expressions, instead? Both the Page and HttpContext classes support a pair of programmatic methods to retrieve the content of resources embedded in the application.

GetGlobalResourceObject retrieves a global resource—that is, a resource defined in an .resx file located in the App_GlobalResources special folder. GetLocalResourceObject does the same for an .resx file located in the App_LocalResources special folder of a given page.

msg1.Text = (String) HttpContext.GetGlobalResourceObject(
     "Test", "MyString");
msg2.Text = (String) HttpContext.GetLocalResourceObject(
     "/MyApp/Samples/ResPage.aspx", "PageResource1.Title");

The first parameter you pass to GetGlobalResourceObject indicates the name of the .resx resource file without an extension; the second parameter is the name of the resource to retrieve. As for GetLocalResourceObject, the first argument indicates the virtual path of the page; the second is the name of the resource.

The Execute method allows you to consider an external page as a subroutine. When the execution flow reaches the Server.Execute call, control is passed to the specified page. The execution of the current page is suspended, and the external page is spawned. The response text generated by the child execution is captured and processed according to the particular overload of Execute that has been used. Table 16-9 lists the overloads of the Execute method.

Note that if a TextWriter object is specified, the response text of the child execution is accumulated into the writer object so that the main page output can be used later at will. Here’s some sample code:

void Page_Load(Object sender, EventArgs e)
{
    var builder = new StringBuilder();
    builder.Append("<b>Response generated before
                    Execute is called</b><hr/>");

    // Capture child content
    var writer = new StringWriter();
    Server.Execute("child.aspx", writer);
    builder.Append(writer.ToString());

    builder.Append("<hr/><b>Response generated after
                   the call to Execute.</b>");

    Label1.Text = builder.ToString();
}

It’s interesting to look at the internal implementation of the Execute method. Both the main and child pages are run by the same HttpApplication object as if they were the same request. What happens within the folds of Execute is a sort of context switch. First, the method obtains an HTTP handler from the application factory to serve the new request. The original handler of the main request is cached and replaced with the new handler. The spawned page inherits the context of the parent; when this step is finished, any modification made to Session or Application is immediately visible to the main page.

The handler switching makes the whole operation extremely fast, as there’s no need to create a new object to serve the request. When the child page returns, the original handler is restored. The execution of the main page continues from the point at which it was stopped, but it uses the context inherited from the child page.

The Transfer method differs from the Execute method in that it terminates the current page after executing the specified page. The new page runs as if it was the originally requested one. The Transfer method has the following overloads:

public void Transfer(String);
public void Transfer(String, Boolean);
public void Transfer(IHttpHandler, Boolean);

The string parameter indicates the destination URL. The Boolean parameter indicates what to do with regard to the QueryString and Form collections. If the parameter is true, the collections are preserved; otherwise, they are cleared and made unavailable to the destination page (which is the recommended approach). You can also directly indicate the HTTP handler to invoke, with the same security issues that were mentioned for Execute.

All the code that might be following the call to Transfer in the main page is never executed. In the end, Transfer is just a page redirect method. However, it is particularly efficient for two reasons. First, no roundtrip to the client is requested, as is the case, for example, with Response.Redirect. Second, the same HttpApplication that was serving the caller request is reused, thus limiting the impact on the ASP.NET infrastructure.

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, respectively, 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. A third property somehow related to page caching is CacheControl. 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 cache-specific 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 18.

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.

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 (because they are abstract) a number of methods, such as CanRead, CanWrite, CanSeek, and Read. 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);
}

Response filters provide an interesting opportunity for developers to build more powerful applications, but I caution you to be careful when considering this option. As the sample demonstrates, changing the case of the entire output is not a smart move. If done without care, the change ends up affecting the view state and the internal script code, both of which consist of case-sensitive text, seriously compromising the functionality of the page. Second, filters must be activated on a per-page basis. If you need to filter all the pages in a Web site, you’re better off writing an HTTP module.

The HttpResponse class has several methods to make the page response it represents dependent on files or cache item changes. The methods AddFileDependency and AddCacheItemDependency (and their versions that handle multiple dependencies) make the page response invalid when the specified file or files or cached item or items are modified.

This is a simple form of programmatic page output caching, not as powerful as the API that we’ll examine in Chapter 18, but still worth a look. The API discussed in Chapter 18 is superior because it allows you to control how the page response is cached, assigning also the cached output a duration and perhaps a location.

The method AddCacheDependency completes the offering, as it gives you the possibility to make the page response dependent on any dependency object available to your application, including custom dependency objects. See Chapter 18 for more details on custom dependency objects.

As you can see, there are three methods for writing potentially large chunks of data down to the output stream: BinaryWrite, WriteFile, and TransmitFile. Of the three methods, TransmitFile is the most stable and reliable, although you won’t notice any significant difference for most files.

Both the WriteFile and BinaryWrite methods seem perfect for streaming binary data down to the client. However, both can put the Web server memory under pressure if called to work on very large files. Why? It’s because both methods load the entire data block (the contents of the file or the byte array) into the Web server’s memory. For large files, this can cause severe problems that can culminate in the recycling of the ASP.NET process. The TransmitFile method is designed to elegantly work around the problem. It sends output directly from a file to the ASP.NET ISAPI extension and then down to the client, without passing a humongous string to the ISAPI extension.

Table 16-12 lists the properties that define the type of request being issued.

The anonymous ID is usually transmitted through a cookie (whose default name is .ASPXANONYMOUS) and serves the purpose of giving an identity to nonauthenticated users, mainly for user profile functions. The anonymous ID is a GUID and is transmitted as clear text. It doesn’t play any relevant role with authentication and security; it is merely a way to track nonregistered users as they move around the site. (See Chapter 7 for profiles and Chapter 19, for user authentication.)

Initially, CurrentExecutionFilePath and FilePath share the same content—the requested URL. However, in cases of server-side redirects, the value of CurrentExecutionFilePath is automatically updated. You should check CurrentExecutionFilePath for up-to-date information about the target URL.

The HttpBrowserCapabilities object groups in a single place values that identify a fair number of browser capabilities, including support for ActiveX controls, scripting languages, frames, cookies, and more. When the request arrives, the user agent information is used to identify the requesting browser and an instance of the HttpBrowserCapabilities class is created and populated with browser-specific information. The information is in no way dynamically set by the browser; instead, it is retrieved from an offline server-side repository.

Table 16-13 lists the HttpRequest properties that expose the client data that ASP.NET pages might want to use for server-side processing. The following table includes, for example, cookies, forms, and query string collections.

The Params collection combines four different but homogeneous collections—QueryString, Form, ServerVariables, and Cookies—and it replicates the information contained in each of them. The collections are added in the following order: QueryString, Form, Cookies, and finally ServerVariables.

Table 16-14 lists the properties that relate to the open connection.

The Uri class provides an object representation of a Uniform Resource Identifier (URI)—a unique name for a resource available on the Internet. The Uri class provides easy access to the parts of the URI as well as properties and methods for checking host, loopback, ports, and DNS.

The server variables set in the ServerVariables collection are decided by the run-time environment that processes the request. The information packed in the collection is, for the most part, excerpted from the HTTP worker request object; another part contains Web server–specific information. The ServerVariables collection is just a friendly name/value model to expose that information.

The SaveAs method lets you create a file to store the entire content of the HTTP request. Note that the storage medium can only be a disk file; no stream or writer can be used. Because ASP.NET by default isn’t granted write permissions, this method causes an access-denied exception unless you implement ad hoc measures. Granting the ASP.NET account full control over the file to be created (or over the whole folder) is one of the possible ways to successfully use the SaveAs method. The following listing shows possible content that SaveAs writes to disk:

GET /MyApp/Samples/Ch14/Misc/TestFilter.aspx HTTP/1.1
Connection: Keep-Alive
Accept: */*
Accept-Encoding: gzip, deflate
Accept-Language: it,en-us;q=0.5
Cookie: .ASPXANONYMOUS=AGzHqyVAyAEkAAAAO ... MWE3YZreWoYt-jkSc_RwU169brWNTIw1
Host: localhost:1066
User-Agent: ...

UA-CPU: x86

If the intercepted request is a POST, you’ll find posted values at the bottom of the string.

A golden rule of Web security claims that all user input is evil and should always be filtered and sanitized before use. The @Page directive has an attribute—ValidateRequest—that automatically blocks postbacks that contain potentially dangerous data. This feature is not the silver bullet of Web input security, but it helps detect possible problems. From a general security perspective, you’re better off replacing the automatic input validation with a strong, application-specific validation layer.

The automatic input validation feature—ValidateRequest—is enabled by default and implemented via a call to the HttpRequest’s ValidationInput method. ValidateInput can be called by your code if the validation feature is not enabled. Request validation works by checking all input data against a hard-coded list of potentially dangerous data. The contents of the collections QueryString, Form, and Cookies are checked during request validation.