This post describes how to compile and debug a web application using IIS7 instead of the built-in web server that comes with Visual Studio 2005. The built-in server should work right out of the box without any further configuration. While this post can pretty much be applied to any ASP.NET web application, I am writing it specifically for the source code of the open source blogging engine Subtext and as a third installment on my blog posts about how to install Subtext on Windows Vista and IIS7. Most people that set up Subtext on a machine are likely to compile the source code at one point or another, especially if you want to make changes to your page template and use user controls (as I did for my Technorati and Flickr controls). For the remainder of this post I assume that you already have successfully set up the compiled binaries for Subtext and the database mainly so that I don't need to reiterate certain necessary installation steps.
There are plenty of resources online that describe how to create/debug web applications using Visual Studio 2005 on IIS7. The two most important things you have to keep in mind are:
- To debug web applications you need to start Visual Studio 2005 with the "Run as Administrator" option from the right-click context menu.
- For debugging to work you need the IIS 6 Metabase and Configuration Compatibility components installed (which should already be the case if you set up IIS7 to work with SQL Server 2005).
Update 12/10/2007: As pointed out in some of the comments, IIS7 does not have the same functionality on all editions of Windows Vista. See this post for details. Basically the bottom line is that you won't be able to get it running on the Starter, Home, or Home Premium editions of Windows Vista because the authentication portion cannot be configured as required. The Business, Enterprise, and Ultimate editions will work fine.
For the Subtext solution the same applies as for the binaries when setting up the Virtual Directory, meaning you have to make sure the application pool is set to Classic .NET AppPool. Also, the project properties for the Subtext.Web project have to be changed from Use Visual Studio Development Server to Use IIS Web server. It is okay to let Visual Studio 2005 create the Virtual Directory for you using the Create Virtual Directory button (note: If you are not executing Visual Studio 2005 with elevated rights, you will get an error message when trying to create the Virtual Directory), but again you will have to change the application pool if the default app pool is not set to Classic .NET AppPool. Now when you start debugging the application here are some common error messages you might encounter and how to resolve them. If anyone gets any other errors please let me know and I will add them to the list (with solution if available):
Message: "Unable to start debugging on the web server. The web server is not configured correctly."
Solution: Unfortunately this is one of the most vague errors you can encounter. Microsoft recommends executing the web site in non-debug mode so that you get to see the underlying IIS error message. Check to see if that message is listed below to resolve it. If there is no error when executing in non-debug mode, make sure that debug is set to true in the Web.config file like this: <compilation debug="true" defaultLanguage="c#">. Alternatively this can also be set in the .NET Compilation settings in IIS Manager.
Message: "Server Error in Application "Default Web Site". HTTP Error 404.0 - Not Found"
Solution: This message comes up if you don't even have the Virtual Directory set up. Set up the Virtual Directory and make sure the application pool is set to Classic .NET AppPool.
Message: "Unable to start debugging on the web server. Debugging failed because integrated Windows authentication is not enabled."
Solution: On the Authentication dialog in IIS Manager enable Windows Authentication and disable Forms Authentication. You cannot have both enabled at the same time.
Message: "An exception of type 'System.InvalidOperationException' occurred in System.Xml.dll but was not handled in user code. Additional Information: There is an error in the XML document."
Solution: This exception is thrown in XmlSerializerSectionHandler.cs when deserializing the blog configuration section from Web.config. When making changes to Web.config through the IIS Manager it seems to clear out the values in the BlogConfigurationSettings section, so I had to fill in the values for all configuration parameters in the section again. These are the default values:
Checkout Subtext.Framework.Security for hashing passwords.
This should be set when first installing the application
and really shouldn't be changed afterwards.
<!-- Globally control access to web services -->
<!-- Globally control use of XHTML -->
<!-- Default Item Count -->
<!-- Default Number of Posts to Show on Category Pages. Use 0 to show all. -->
<!-- Default Server Time Zone Offset -->
<!-- Whether or not to GZIP the RSS and/or atom feeds. -->
Message: "An exception of type 'System.Configuration.ConfigurationErrorsException' occurred in System.Configuration.dll but was not handled in user code. Additional information: An error occurred creating the configuration section handler for BlogConfigurationSettings: There is an error in the Xml document."
Solution: This message appears as a follow-up error of the previous message. When the previous one is fixed this should go away as well.