When IIS and ASP.NET don't get along

Learn to use aspnet_regiis.exe -- a hush-hush .NET utility that solves many ASP.NET installation problems.

Despite how cool ASP.NET is and all the promises Microsoft has made for it, sometimes things just go wrong. You're typing code a mile a minute, creating Web pages that are works of art and you run it to see how you're doing. Bam! You get an error message. You go into forensics mode, using your years of programming experience and .NET's wonderful diagnostics tools to get to the root of the problem and eradicate it.

But nothing works.

Although it is probably of scant comfort after six hours of intense investigative debugging, the problem might not be in your code at all. And it might not even be in Microsoft's code, either. A lot of weird errors can occur in ASP.NET indicating that it isn't installed correctly, or that something's out of sync with IIS. Maybe you're using some of the validation server controls and the client can't find the script file it needs for client-side validation. Or, an ASPX page simply isn't loading no matter what you do.

The problem is that ASP.NET installs a bunch of settings and files it uses to make the .NET magic work in Web applications. There are file extension mappings so IIS knows what DLL to use to respond to a client request (for a list, go into the Internet Services Manager and the Properties page for a Web site; go to the Home or Virtual Directory tab; select Configuration; then select the Mappings tab). The WebUIValidation.js used for client-side validation must be in the right place in the .NET Framework folder in the Windows system directory and in your various Web site directories. Or you need to manage multiple versions of the Framework.

Things can get out of sync in many ways. You might accidentally delete a critical file. You might be exploring some IIS deep magic and playing with mappings and other IIS settings. Maybe IIS wasn't installed before .NET, so IIS doesn't have a clue what ASP.NET is. Or any of many other travesties can occur on an otherwise healthy system.

The solution is to uninstall and reinstall the .NET Framework on your development machine or server, right? Well, you might ultimately have to do that, but there's an easier way to fix many common ASP.NET and IIS issues. It's a utility Microsoft doesn't make much noise about, barely mentioning it in the documentation: aspnet_regiis.exe. You'll find it in something like the C:WINDOWSMicrosoft.NETFramework<version> directory with the other .NET command-line tools. The easiest way to run it is to open the VS .NET Command Prompt window, which sets all the paths and environmental settings for you.

The tool has several options, which you can get by running either aspnet_regiis or aspnet_regiis -? at the command prompt. Figure 1 shows some of the most useful options you have available.

Option Description
-i Installs current version of ASP.NET. Same as running regsvr32.exe <dll>.
-u Uninstalls current version of ASP.NET. Same as running regsvr32.exe -u <dll>.
-ua Uninstalls all versions of ASP.NET.
-lv Lists all the versions installed, together with status and path.
-lk Lists all the paths of all IIS keys where ASP.NET is installed, together with the version.
-c Copies the client-side script files of the current version to the aspnet_client subdirectory of each existing Web site.

Figure 1: These are some of the most useful options in the aspnet_regiis tool. The -i and -c options are probably the most useful for eradicating mysterious errors from the local machine because they fix mappings and reinstall script files back into their proper places.

Another nice feature of the tool is it simplifies managing multiple versions of the .NET Framework on a machine, running different Web sites using different versions. This time, run this command:

aspnet_regiis -s W3SVC/1/ROOT/MyWebApp

where the -s parameter is the path to the Web application's virtual directory. This sets the script mappings for the specific version of ASP.NET.

References

Microsoft Knowledge Base Article 318465: "Cannot Debug ASP.NET Web Application"

Microsoft Knowledge Base Article 306005: "Repair IIS Mapping After You Remove and Reinstall IIS"

Deploying .NET Applications: Lifecycle Guide: See the section titled "Using Aspnet_regiis.exe to Manage Multiple Versions of the .NET Framework for Your Web Applications."

About the author: Don Kiely is senior information architect for Information Insights, a business and technology consultancy in Fairbanks, Alaska. E-mail him at donkiely@computer.org.

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 for subscription information.

This was first published in July 2003

Dig deeper on ASP.NET development best practices

0 comments

Oldest 

Forgot Password?

No problem! Submit your e-mail address below. We'll send you an email containing your password.

Your password has been sent to:

-ADS BY GOOGLE

SearchCloudComputing

SearchSoftwareQuality

SearchSOA

TheServerSide

SearchCloudApplications

Close