Working with ASP.NET

The rest of this chapter looks in detail at installing and configuring different types of web applications on IIS. We’ll begin by looking at ASP.NET applications and how to install and configure them on IIS.

Note 

ASP.NET applications can also work when IIS is configured to run in IIS 5 isolation mode, but ASP.NET works differently in this case. Specifically, when IIS is running in worker process isolation mode, ASP.NET uses the same worker process architecture used by IIS, including support for recycling, health monitoring, and so on. When IIS is running in IIS 5 isolation mode, ASP.NET uses its own process model where ASP.NET configuration settings are defined in the XML configuration file machine.config, which is contained in the directory SystemRoot%\Microsoft.NET\Framework\<version>\CONFIG, where <version> is the version of the .NET Framework installed on the machine. There are some exceptions to this, however; see the ASP.NET documentation for more info.

Installing ASP.NET

If you refer back to Figure 8-2, you’ll notice that ASP.NET is not listed in the Web Service Extension column of the details pane. This is because in my particular configuration of Windows  Server 2003, Enterprise Edition, I added the Application Server role but did not install ASP.NET as part of that role. The first thing I must do if I want to run ASP.NET applications (such as the sample application earlier in this chapter) is install ASP.NET on my IIS machine: To do this, open Add Or Remove Programs, select Add/Remove Windows Components, choose Application Server, click the Details button, select ASP.NET, and click OK. Once this is finished, press F5 to refresh IIS Manager, and the WSE node should show ASP.NET in its list of extensions.

Tip 

If ASP.NET shows up as an extension in WSE but has the status Prohibited, it means the ASP.NET component of IIS is installed on the server but it is not yet enabled. In this case, right-click the ASP.NET extension of WSE and select Allow to enable ASP.NET applications to run on your server.

Using the Default Application

Let’s see if you can get the sample ASP.NET application I described earlier in this chapter to work on IIS. The simplest way to do this is to use the Default Web Site that is created when IIS is installed and which has C:\Inetpub\wwwroot as its home directory. Start by copying the default.aspx page you created to this directory. Now let’s look at your Default Web site in IIS Manager (see Figure 8-3).

Figure 8-3: Default Web Site with an ASP.NET default document

Notice that there is a subdirectory called aspnet_client in your Default Web Site. This directory is automatically created to allow ASP.NET to take advantage of the client-side script processing features of .NET Framework server controls. This is a developers’ topic and is beyond the scope of this book, so I won’t discuss it further here.

Now right-click the Default Web Site and select Browse. You might expect the sample ASP.NET application to run at this point, displaying the message “This page was last refreshed on [date] [time]”; but instead, the “under construction” message from your iisstart.htm page is displayed. This is likely a problem with the default document order, so open the Default Web Site Properties sheet and select the Documents tab (see Figure 8-4).

Figure 8-4: Changing the default document order

Note that installing and enabling ASP.NET adds Default.aspx to your list of default documents, but unfortunately it’s at the bottom of the list. The solution is to either move it to the top of the list or delete any other default documents, such as iisstart.htm, from the site’s home directory. In this example, keep iisstart.htm and move Default.aspx to the top of the default documents list.

Right-click the Default Web Site again and select Browse. This time, the sample ASP.NET application should run and display the expected message in the details pane (see Figure 8-5).

Figure 8-5: Verifying that your ASP.NET application works

Application Pools

Before you look at creating other ASP.NET applications on your machine, let’s pause for a moment and discuss application pools, a feature of IIS when it is running in worker process isolation mode. An application pool is basically a logical representation of the worker process(es) that service an ASP.NET application running on IIS. By default, each application pool has a single worker process (w3wp.exe) associated with it, and each worker process has an HTTP request queue within http.sys associated with it. When a client (web browser) tries to open the Default.aspx page in your Default Web Site, http.sys places the request in the queue for the Default Application Pool (the application pool associated with the Default Web Site) until the worker process for that pool can pull the request from the queue and generate a response.

Note 

A common way to describe the relationship between application pools and worker processes is to say that application pools are separated from each other by worker process boundaries.

If you have several applications running on your server (corresponding to several websites or virtual directories), you may want to place each of your applications in its own separate application pool so they each have their own worker process associated with them. That way, if any of your applications fail, none of the worker processes associated with other applications running on the server will be affected. This feature of application pools is thus integral to the ability of IIS 6 to isolate applications from each other for improved reliability. You can also run multiple applications within a given application pool to conserve resources on your server; but if you do and one of the applications fails, the others may be affected.

Default Application Pool

When IIS is configured to run in worker process isolation mode, a Default Application Pool called DefaultAppPool is created under the Application Pools node in IIS Manager (see Figure 8-6). This pool contains the Default Application, which is automatically created for the Default Web Site when IIS is installed.

Figure 8-6: The Default Application running within the DefaultAppPool

Right-clicking the DefaultAppPool allows you to perform a number of administrative tasks on it, including:

• Manually stopping and starting the pool When an application pool is manually stopped by an administrator, all applications associated with it are rendered unavailable to clients and a “service unavailable” message is displayed in the browser window until the pool is started again. Application pools may also suddenly stop for other reasons, such as configuration errors where nonexistent identities are used as a security context for running the pool or the initiation of the rapid-fail protection feature of IIS. Stopping an application pool is not the same as stopping the website containing the application.

• Manually recycling the worker process(es) associated with the pool Recycling is an IIS 6 feature that lets you periodically restart worker processes associated with the pool; it is typically used when running flaky applications that have a tendency to crash over time. Recycling is discussed in more detail in Chapter 12.

• Saving configuration to a file This saves the configuration of the application pool to an XML file that can then be imported into another server.

• Opening the properties sheet for the pool This allows you to configure recycling, performance, health, and identity settings for the pool. I’ll discuss configuring application pools in Chapters 10 and 12.

Application Pools and Worker Processes

There are two cases in which an application pool may have more than one worker process associated with it. The first is when you create a web garden, a feature of IIS that allows you to have multiple worker processes service a given application pool for improved performance. The other is if the application pool is configured for overlapped recycling to occur, in which case when the worker process is recycled, there will briefly be two worker processes (the one being terminated and the new one generated to take its place) associated with the same pool. In both cases, an application within the pool may experience what is called multi-instancing, that is, multiple instances of the application running concurrently. This can cause problems if the application is not specifically designed to handle this situation. Older ISAPI extensions and ASP applications are particularly vulnerable to this issue and may require recoding (or running in IIS 5 isolation mode). Alternatively, you can avoid using a web garden for your application, or you can disable overlapped recycling for the pool. Web gardens and worker process recycling are covered in more detail in Chapter 12.

Creating Application Pools

Let’s create a second application pool on your server so you can experiment with moving applications between pools. Right-click the Application Pools node and select New | Application Pool to open the Add New Application Pool dialog box (see Figure 8-7). Type a friendly name for the pool (AppPool #1 is suggested) that will only be used in IIS Manager, and specify whether to use the default settings for the new pool or copy its configuration settings from a pool you specify (for this example, use the former option).

Figure 8-7: Creating a new application pool

You should now have two pools (DefaultAppPool and AppPool #1) displayed under the Application Pools node in the console tree. At this point, the DefaultAppPool has an application (the Default Application) running in it, while AppPool #1 has no application running in it.

Tip 

Even if you only have one website (the Default Web Site) running on your server, you may want to create a second application pool in addition to the DefaultAppPool. The reason is that if you are modifying your ASP.NET application, you can run both the existing and modified versions simultaneously, each assigned to its own pool, to simplify testing your modifications. In other words, you will be using application pools to isolate different versions of your application from each other.

Assigning Applications to Application Pools

Now let’s move the Default Application from the DefaultAppPool to AppPool #1 by assigning the Default Application to AppPool #1:

1. Right-click the Default Web Site (which contains the Default Application) and select Properties to open its properties sheet.

2. Switch to the Home Directory tab and select AppPool #1 from the Application Pool list box.

3. Click OK to apply the change, and close the properties sheet.

Notice now that the Default Application in IIS Manager has moved from the DefaultAppPool to AppPool #1 (see Figure 8-8).

Figure 8-8: Moving an application between pools

Note 

You can’t delete an application pool if there are still applications assigned to it. You must first move the applications to other pools and then delete the pool.

Creating Applications

Now let’s create a few more ASP.NET applications on your server and experiment with configuring these applications. For simplicity, I’ll explain how to edit the Default.aspx file in C:\Inetpub\wwwroot to display the heading “Welcome to ASP.NET #####”, where ##### is the friendly name of the website that will host your new application. Then you’ll create a content folder to contain the modified page and make this folder the home directory of the website or virtual directory that contains your application. Specifically, go ahead and create the following directories:

• C:\webstuff\appone which contains Default.aspx where ##### = Site One

• C:\webstuff\apptwo which contains Default.aspx where ##### = Site Two

and so on as necessary.

Creating a Root-Level Application

To create a new root-level application on IIS, first create a new website using the methods outlined in Chapter 7. For this example, use the Web Site Creation Wizard to create a new site called Site One and assign it one of the several IP addresses bound to your server’s network card. This ensures the site has a unique identity so it can start properly. As the home directory for your new site, choose the folder \appone described earlier.

Once you’ve finished creating the new site, you’ll see that a Default Application node appears under the DefaultAppPool node in the console tree (see Figure 8-9). Remember that earlier you moved the Default Application associated with your Default Web Site from the DefaultAppPool to AppPool #1. Notice also that this new node is associated with Site One, not the Default Web Site. Why has this new node appeared?

Figure 8-9: Are there now two Default Applications?

The answer can be found on the Home Directory tab of the properties sheet for the newly created Site One (see Figure 8-10). Your new application has an application name, an application starting point, and specific execute permissions, and it is assigned to a specific application pool. Let’s examine each of these application settings for our new application.

Figure 8-10: Defining an application using an application name and starting point

First, the application name for your new application is Default Application. Application Name is a friendly name for your application that appears only in IIS Manager. By default, when you create a new website on IIS, an application is created for it and given the name Default Application. Because this is the same name assigned to the application created for the Default Web Site, it is somewhat confusing—you now have two separate applications with the same name but different content directories. To eliminate this confusion, rename your new application something different, such as App One. Before you do this, however, let’s continue to look at the application settings for your application.

The starting point for your new application is <Site One>. This is the name of the node in the IIS metabase that contains the configuration settings for your application, and the name of the website you created is used to generate this name.

The Execute Permissions is set by default as Scripts Only. This setting lets ASP.NET pages run but not executable code such as .exe files. This is a safety feature to ensure hostile code won’t run on the server. However, you can select Scripts and Executables if you want to allow any code (compiled or scripted) to run in the directory, or you can select None if you want to allow only static HTML to be served from this directory.

Finally, the application pool to which the new application is assigned is the DefaultAppPool. This is done automatically for every new root application you create on IIS, but as I mentioned earlier, you can move your application to a separate pool to isolate it if you want to.

Renaming an Application

You can rename your new application simply by overtyping a new name in the Application Name field on the Home Directory tab and clicking Apply (see Figure 8-10 again). Try changing its name from Default Application to App One, and note that the node under the DefaultAppPool also changes from Default Application to App One, which is a little easier to follow.

Removing an Application

Let’s say you changed your mind and don’t want to host an ASP.NET application in your new website named Site One (perhaps you just want to serve static HTML from the site instead). To remove your App One application, click the Remove button on the Home Directory tab (shown in Figure 8-10). The result of this action is that the application name field goes blank and the starting point changes to <No Application Defined>. IIS takes some time to flush the configuration changes to the metabase, so App One may still be displayed for a while under DefaultAppPool in IIS Manager, even if you press F5 to refresh the console.

Note 

Instead of disappearing entirely from the DefaultAppPool, a new node called ROOT may appear that appears to be mapped to <Site One>. This appears to indicate that there is a website on the server that has no application configured for it.

Creating an Application from an Existing Website

You still have a new website called Site One but there is no application defined for the site, so let’s create one. Click the Create button, specify a new application name such as New App One, specify execute permissions, select an application pool for the application, and click OK. Note that the Create button is only displayed if you first remove the existing default Application Name using the Remove Button. Verify in IIS Manager that the application is assigned to the pool you selected.

Application Starting Points

I should pause and define more clearly what we mean by the term “application.” In IIS lingo, an application is a collection of files contained in a given virtual directory (and usually its subdirectories) and that can be executed using an applicable web service extension like ASP or ASP.NET. For example, on an IIS machine, the Default Web Site might contain the virtual (or physical) directories \sales, \service, \support and \support\legacy. All of these subdirectories are usually part of the same application: the root application called Default Application. On the other hand, you could select one of these subdirectories—\support, for example—and remove the Default Application from the Directory tab of its properties sheet, and then create a new application for the directory. At this point, any subdirectories beneath the \support directory (such as \legacy) would be part of the new application and would no longer belong to the Default Application. So another way of defining an application on IIS is as a contiguous subtree of folders whose root folder is the application starting point, where none of the lower nodes have their own starting points defined but instead share the same starting point as the root folder. More briefly, every file and directory beneath the starting point directory of a website is part of the same application until another starting point directory is found.

Tip 

If you remove the application starting point from a subdirectory (either virtual or physical) of a site’s home directory, clients will not be able to start the application by opening files in this subdirectory (or in directories beneath it). Note that removing an application starting point does not remove the content itself from the associated directory.

Applications and Virtual Directories

I should point out an important difference between physical and virtual directories as far as IIS applications are concerned. If you create a physical subdirectory within the home directory of a website on which an application is defined, the physical directory has the same name, starting point, execute permissions, and application pool as the root application defined for the parent website. If you create a virtual subdirectory within the home directory of the site, however, a new application name is assigned to the virtual directory (by default, IIS uses the virtual directory name for the application name). For example, if you create a virtual directory called \Sales in Site One described previously, and you open the properties sheet for this virtual directory, on the Virtual Directory tab the application name will be listed as Sales and the application starting point as <Site One>\Sales. The execute permissions and application pool settings are inherited from the parent application, however. If you want your new virtual directory to be part of the parent application (website root application) instead of being a separate application, click Remote on the Virtual Directory tab. When you do this, the icon for the virtual directory’s node in IIS Manager changes from a gear icon (signifying a separate application) to a folder icon with a small world attached to it (signifying it is part of the parent website, which has a large world icon).

Unloading Applications

If an application is started by a client request, it is loaded into memory for execution. You can manually unload your application from memory by clicking the Unload button on the Home Directory tab of the application’s associated website. However, you can only perform an unload from the application’s home directory, not from any subdirectory beneath it.

Configuring Applications

Once you’ve created a new application on IIS, you need to configure it. To configure an ASP.NET application, click the Configuration button on the Home Directory tab of the website on which the application is defined. This opens the Application Configuration screen (see Figure 8-11), which has three tabs: Mappings, Options, and Debugging. We’ll examine each of these and the settings they contain. But first, note that application settings can be configured at three levels:

• Web Sites level These settings are global for all sites on the server.

• Website level Each site is configured separately.

• Virtual directory level For virtual directories within a particular website.

  
  Figure 8-11: Configuring an application

There are a few differences when configuring application settings at these different levels:

• The option for caching ISAPI applications cannot be configured at the virtual directory level. Instead, this level inherits the value for this setting from its parent website. Caching ISAPI applications is discussed in Chapters 12 and 13.

• The Web Sites level has a fourth tab called ASP Caching that enables and configures the caching of compiled ASP templates on IIS. This feature is covered in Chapter 12 when we discuss IIS performance.

• You can programmatically override virtual directory or website application settings for each individual ASP.NET page within a virtual directory or website.  

  Note 

  Physical subdirectories within a website configured as an application do not have configurable application settings—only virtual directories do.

Application Configuration: Mappings

This tab is used to associate specific filename extensions to the associated ISAPI or CGI program used to execute these files, a process called application mapping. IIS 6 comes with a set of predefined application mappings that associate various file extensions with the different ISAPI extensions, as shown in Table 8-1.

Table 8-1: Default File Extensions Defined for Different ISAPI Extensions

ISAPI Extension	Associated File Extensions
asp.dll	.asa, .asp, .cdx, .cer
aspnet_isapi.dll	.asax, .ascx, .ashx, .asmx, .aspx, .axd, .cs, .csproj, .licx, .rem, .resources, .resx, .soap, .vb, .vbproj, .vsdisco, .webinfo
httpobdc.dll	.idc
ssinc.dll	.shtm, .shtml, .stm

You can add, remove, or modify any of these application mappings by specifying a different ISAPI DLL for executing files having that extension, specifying which HTTP verbs like GET or POST should be passed to the DLL for processing (other verbs will not be passed), and whether you want to allow the application to run in a directory without execute permissions. You can also create your own custom application mappings by associating specific file extensions with a specific ISAPI DLL. For example, I could map the file extension .mitch to asp.dll and save all my ASP pages with this extension. (I don’t know why I would do this—vanity probably!)

Of course, a more common use for application mappings is to configure IIS to use new scripting languages other than the default VBScript and JScript. For example, Perl is a scripting language that is commonly used for developing CGI scripts to run on UNIX web servers. If you obtained a Perl engine or script interpreter (typically perl.exe) from some third-party vendor, you could configure IIS to process Perl scripts (text files with the file extension .pl) using this engine as follows:

1. Open the properties sheet for the website where the Perl script will run and switch to the Home Directory tab.

2. Click the Configuration button to display the Mappings tab of the Application Configuration screen (see Figure 8-11 again).

3. Click Add and browse to where the Perl engine is located, typically \Perl\bin or something similar.

4. Specify .pl as the file extension to be mapped to the engine.

5. Specify which verbs should be passed to the engine when processing HTTP requests (typically GET or POST).

6. Select the Script Engine check box to allow the Perl engine to execute, and click OK. Note that if you leave this check box unselected, you will have to specify Scripts And Executables as execute permissions on the web site where your Perl application resides; but if you select the check box, then you can use the Scripts Only permissions instead, which is safer.

Of course, the steps may differ slightly depending on the instructions that come with your third-party script engine.

Tip 

The Verbs field on the Mappings tab indicates which HTTP verbs are allowed. In earlier versions of IIS, this field was named Exclusions and indicated which verbs were prohibited.

Note 

For information on configuring wildcard application mappings, see the section “Working with ISAPI,” later in this chapter.

Application Configuration: Options

The Options tab of the Application Configuration screen lets you configure certain functional and performance aspects of running ASP.NET applications on IIS (see Figure 8-12). For example, Session Timeout lets you persist session state information for your application and allows you to configure how long this information will be persisted before it is discarded. Persisting session state information is important in multipage ASP.NET applications such as online order forms to prevent users from having to re-enter information during their session. By default, session state is enabled with a timeout of 20 minutes.

Figure 8-12: Configuring application options

ActivePerl

You can obtain Perl for Windows from Active State (www.activestate.com). When Windows Server 2003 is released, Active State will probably have a version of their ActivePerl product that runs on this platform. The latest beta version of ActivePerl installs as a Windows Installer Package (.msi file) and automatically configures Perl to run on IIS by creating .pl and .plx file extensions and mapping them to perl.exe (for CGI execution) and perlis.dll (for ISAPI execution). The nice thing about ActivePerl is that it comes in both CGI and ISAPI varieties, and you can choose which form to use for interpreting your scripts. Once you install ActivePerl on IIS you can test it using the sample script found in Knowledge Base article Q245225 on the Microsoft Product Support Services (PSS) website at support.microsoft.com. Don't forget to enable the appropriate CGI and ISAPI extensions for your Perl engine using WSE, or your Perl scripts won't work!

Another setting you can configure on this tab is the default scripting language used for the ASP.NET application. This is the scripting language assumed for .aspx pages when no language is explicitly declared within the page; it is VBScript by default. If you do not wish to use VBScript, you must manually type the default scripting language you prefer in this field (JScript is the main alternative to VBScript on IIS).

Another setting on this tab is ASP Script Timeout, which lets you specify in seconds how long IIS lets a script run before terminating it. The timeout value can range from 1 second upward, with a default setting of 90 seconds. A shorter timeout value will reduce wasted IIS resources but may interfere with distributed applications when the network is slow.

As for the remaining settings on this page, I’ll cover enabling parent paths in Chapter 10 when we deal with IIS security, and buffering in Chapter 12 when we discuss performance issues.

Note 

When a script is terminated by IIS, an event is written to the Event Log. See Chapter 13 for information about IIS events in the Event Log.

Application Configuration: Debugging

The Debugging tab lets you enable client- and server-side debugging for your ASP.NET applications and configure custom error messages for script errors that may occur. I’ll talk about application debugging more in Chapter 13 when we look at maintaining and troubleshooting IIS.