Debug and Release Builds in ASP.NET 2.0

One of the adjustments to make when moving from ASP.NET 1.1 to 2.0 is how to produce debug and release builds.

1.1

In 1.1 we had the Build -> Configuration Manager menu option. This command launched a dialog box to let you choose from the available build configurations. Visual Studio provided Debug and Release configurations by default. The configuration selected in the Configuration Manager would tell Visual Studio how to compile the code-behind files. A successful compilation would produce a single assembly (.dll) in the bin directory, with a debugging symbol file (.pdb) appearing if the configuration asked for debugging symbols

Sometime later, the application would receive a web request and begin to execute. At this point, the ASP.NET runtime would generate code for the web forms and user controls in the application, then compile the generated code. The compilation at runtime would use the debug setting in the compilation section of web.config to determine if it should compile optimized code, or debug code (with symbols). ASP.NET would place the results underneath the Temporary ASP.NET Files directory. It is important to select the Release configuration in VS.NET 2003 and set debug=”false” in web.config to produce a true production build in 1.1.

2.0

Here is the most important concept to come to terms with in 2.0: Visual Studio 2005 knows nothing about compiling a web application. In 1.1 VS built the code-behind and ASP.NET built the web forms. In 2.0 Visual Studio 2005 delegates all compilation responsibilities to the ASP.NET platform.

With that in mind, there are two scenarios to talk about: building a web application without a Web Site Deployment project, and building a web application with the Web Site Deployment project. Let’s start with “without”.

When you ask Visual Studio to build a web project, nothing seems to happen. You don’t get the comforting feeling of having a bin directory with a .dll file inside. This is because ASP.NET, not Visual Studio, performs the build. ASP.NET builds everything, including .cs and .vb code files. ASP.NET places all the resulting assemblies in a folder underneath the Temporary ASP.NET files directory. You’ll see the results of the build if you poke around in the directory.

Because ASP.NET does all of the compilation, the debug setting in the compilation section of web.config controls debug or release mode. Compile with debug=”true” and you’ll find the .pdb debugging symbol files alongside each assembly.

This new compilation model makes the Configuration Manager for a web site obsolete. The only option appearing in a Visual Studio 2005 web site “project” is a Debug configuration. Don’t fret – it means nothing. The web.config file now rules the school.

When you are ready to deploy, you can publish the web site. The Publish command (Build -> Publish) will precompile a web application and place the results into a directory of your choosing. You can also publish to an IIS or FTP location. When you select the Publish command you’ll see a dialog box to choose a destination, and options for strong naming, fixed naming, etc. These options map directly to switches for the command line aspnet_compiler tool (see my article for more details). The aspnet_compiler tool also provides a switch to produce debugging symbols, but this option is not available from the Publish dialog. Publish will always precompile a release build without debugging symbols.

Note: the Publish command does not change the debug setting in web.config. The Publish command always compiles for “release”, however, if you precompile to an updateable web site, and then update the web site in place (which results in dynamic compilations), those dynamic compilations will produce debug code and pdb files.

The new Web Site Deployment (WSD) project changes the above scenario slightly. The WSD adds Release and Debug configurations to the Visual Studio 2005 configuration manger. This does not mean that Visual Studio knows how to compile a web site. Instead, Visual Studio knows how to use the MSBuild file provided by WSD to ask for Debug and Release builds. You can now select Debug or Release from the Configuration Manager in Visual Studio. The build request ultimately arrives at the same aspnet_compiler tool described above, and used by the Publish command.

Unlike the Publish command, a WSD Release build will change the debug setting of web.config to false. The WSD also defaults to placing release builds in a Release directory and debug builds in a Debug directory, which is familiar to anyone using .NET outside of web forms. WSD is an awesome tool and I'm sure will be covered in more detail here (eventually).

In conclusion, you control debug and release builds using the debug attribute of the compilation section in web.config – unless you are precompiling the website with the Publish command or the Web Site Deployment tool. The WSD will let you select Debug or Release builds, precompiles the site, and modifies web.config appropriately.