This tip describes how to use the ASP.NET IIS Registration Tool to manage Web apps on a machine running multiple versions of ASP.NET.
Life is getting more complex for ASP.NET developers. Suppose you have been developing with ASP.NET 1.0 since it was released and have several Web applications running on your machine. Now, though, you're starting a new project and you need to use ASP.NET 1.1 as the platform.
Because of one reason or another (maybe the IT department or company hosting the server is not ready to install the new version), upgrading the other Web applications to version 1.1 might not be an option. Here's the common question: How do you tell one Web application to use the new version and the others to use the previous version? The simple answer is to use the ASP.NET IIS Registration Tool, which is included with each version of the .NET Framework and usually is located at <WinDir>Microsoft.NETFramework<version>aspnet_regiis.exe.
Under the hood
Before I go into how to use this tool, I'll give you a little background on why a particular ASP.NET installation is invoked when a client calls an .aspx page. When a client browser requests a page, it makes that request to the Web server or IIS -- not to ASP.NET. It's IIS' responsibility to determine what to do with this request. In the case of an .aspx page, IIS loads the ASP.NET ISAPI extension -- aspnet_isapi.dll -- and passes it the request. The ASP.NET ISAPI extension then passes the request to the ASP.NET worker process, aspnet_wp.exe. So you can see there is a lot going on whenever a request comes in. But because each version of the .NET Framework installs its own version of aspnet_isapi.dll and aspnet_wp.exe, how does IIS know which one to invoke for any particular .aspx page? You can find the answer in the IIS management console, located under the Administrative Tools section of the Control Panel.
To determine which version of ASP.NET is being used, open the IIS management console, right-click on the virtual directory or Web site, and select Properties. On the Directory or Home Directory tab, click on the Configuration button. As shown in Figure 1, you should be on the Mappings tab, which displays a list of file extensions and the path to the corresponding CGI executable or ISAPI extension. The key here is to see which version of the ASP.NET ISAPI extension is being invoked for .aspx pages. For version 1.0 it should be <WinDir>Microsoft.NETFrameworkv1.0.3705aspnet_isapi.dll; for version 1.1 it should be <WinDir>Microsoft.NETFrameworkv1.1.4322 aspnet_isapi.dll.
Figure 1. The Application Configuration dialog in the IIS management console allows you to view and control which ASP.NET version is being used by your Web application.
Under the default Web site, say you have two virtual directories, OldVersion and NewVersion, each representing a different Web application. If you want the NewVersion Web site to use version 1.1, all you need to do is re- map the executable path for all the ASP.NET extensions to <WinDir>Microsoft.NETFrameworkv1.1.4322aspnet_isapi.dll. It sounds easy enough, but on my machine I would need to re-map 21 extensions! Doing this manually would be quite frustrating, which is why the ASP.NET IIS Registration Tool was created. I imagine someone at Microsoft got similarly frustrated at some time during the .NET development cycle, giving way to this tool.
aspnet_regiis -s W3SVC/1/ROOT/NewVersion
Watch out for a couple of possible pitfalls here. One thing to remember is your command prompt must be in the <WinDir>Microsoft.NETFrameworkv1.1.4322 directory; otherwise, there's no telling which version will be executed. The other thing to remember is the path to the virtual directory might not always begin with W3SVC/1/. The number 1 denotes that this is the first Web site installed in IIS. If you're using Windows XP Pro or Windows 2000 Pro, you don't need to worry about this because these operating systems allow only one Web site under normal circumstances. If you're using Windows 2000 Server or Windows Server 2003, however, which both allow multiple Web sites, you'll need to determine the path for the Web site you're working with. The easiest way I know of to do this is to go to the Web site's Properties dialog and on the Web Site tab click on the Properties button in the logging section. As shown in Figure 2, you should see the Log File Name at the bottom of the General Properties tab. This is the path you should use, minus the actual filename itself. In this case, the path would be W3SVC2/.
Figure 2. You can find the IIS Metabase path for a Web site easily in the Logging Properties dialog of the IIS management console.
Another handy option for this tool is to view all the applications that are mapped to ASP.NET and which version they are mapped to. This is also another way to find the path name for the Web site. For this option, use this syntax:
This syntax will display something like this:
As you can see, the ASP.NET IIS Registration Tool is a fairly mundane, nuts- and-bolts kind of tool that is not going to get anybody very excited. But it can save you a lot of time and trouble if, like me, you do a considerable amount of multiversion ASP.NET development. I work with almost a dozen Web applications on my laptop and I've got all my aspnet_regiis commands scripted in a batch file. With this batch file, I can get my extension mappings back to a safe configuration with one click in case something screwy happens or I do something stupid - neither of which are uncommon occurrences. Also, I can port all my Web applications more easily to another server if the need arises.
I suggest running the tool with the -lk option to see what applications are currently set up in IIS and what ASP.NET versions they are mapped to. Then create a batch file so you can re-create this configuration easily if disaster strikes.
References aspnet_regiis Web site: http://www.microsoft.com
Ken McNamee is an independent consultant who works with companies in need of highly scalable, data-driven Web applications. And who doesn't need one of those these days? Prior to this, he led a team of developers in re-architecting the Home Shopping Network's e-commerce site, HSN.com, to 100 percent ASP.NET with C#. E-mail him at kmcnamee@aspnetPRO.com.
This article was provided by asp.netPRO Magazine, an online information resource for the ASP.NET developer community, which helps professional software developers build, deploy and run the next generation of dynamic, distributed Web applications quickly and easily. Click here to learn more.
Please let other users know how useful this tip is by rating it below. Do you have a tip or code of your own you'd like to share? Submit it here.
This was first published in October 2003