A Tale of Two Developers and Visual Studio Sites and Apps

Wednesday, September 30, 2009

We've encountered several scenarios in which customers have multiple developers working on a single web application in Visual Studio. In such cases, it's not uncommon for each developer to be working on a portion of the application. There isn't any problem in working with this way, but you may encounter some very real problems when you deploy your application unless you plan in advance.

The Scenario

Suppose you have two developers working on your web application. Developer A (we'll call him John) is working on a forum for the application and developer B (who we'll call Jill) is working on a photo gallery for the site. In order to keep files and folders organized, the forum and the photo gallery will both be contained in their own folders on the final site. In other words, by browsing to www.site.com/forum, users will be able to hit the forum, and by browsing to www.site.com/photogallery, users will hit the photo gallery.

Jill has created a new web site in Visual Studio called PhotoGallery, and this is where she's going to create her pages for her portion of the application. John has created a new web site called Forum for his portion of the site. Both John and Jill frequently test their code against the ASP.NET Development Server and, after a long period of development, are both ready to deploy to the test web server.

Jill's part of the web site as shown in Solution Explorer.
Jill's PhotoGallery in Solution Explorer

Jill copies the PhotoGallery folder she created for her portion of the site to the c:\inetpub\wwwroot folder on the server and John copies the Forum folder he created to the wwwroot folder. The resulting directory structure in IIS is shown below.

Folder structure of deployed site in IIS.
Folder Structure in IIS

Everything looks fine with this scenario so far, but as soon as either John or Jill attempts to access his or her portion of the site, something bad happens as shown below.

An error occurs when the photogallery folder is browsed.
An error occurs when John or Jill browse the site.

The Problem

The problem here is that Visual Studio expects that the web sites that John and Jill created are application roots in IIS. An application root in IIS is a folder that is marked as an application. When a folder is marked as an application, the folder's icon appears as a globe with a page on it as shown below.

An Application in IIS.

Important
I converted the "forum" folder into an application for the figure above simply so that I could show you what the icon looks like. The act of copying a folder to IIS will not make a folder an application in IIS.

Since John and Jill simply copied folders into IIS, the applications they each created in Visual Studio are simply folders in IIS (like the photogallery folder in the figure above) and are not recognized as applications. Because ASP.NET does not allow for certain settings to be configured in a subdirectory of an application, both John and Jill see an error when browsing their portion of the site.

Keep in mind that this is only one example of the kind of problem you can encounter in this scenario. For example, if the root of your site was created in Visual Studio as a web application instead of a web site and developers copy web sites from Visual Studio into that directory structure, you can end up with more problems that are tough to solve.

More Info
See http://msdn.microsoft.com/en-us/library/aa983474.aspx on MSDN for an explanation of web sites vs. web applications in Visual Studio.

The Solution

How can John and Jill solve the error message they are seeing? They could simply convert the folders that they copied to IIS into application roots, but while doing so would get rid of the error, it would likely introduce other problems. For example, there Application and Session variables are specific to an application, so if both the photogallery and forum folders were marked as application roots, Application and Session variables couldn't be shared between them. Also, as we saw in the error that Jill saw in the browser, authentication modes are specific to an application. Therefore, if the site as a whole relies on ASP.NET Forms authentication, mucking around with application roots can break authentication.

A good approach to the problem that John and Jill are encountering is to change the way that they both develop the site in Visual Studio. Each should develop against a web site in Visual Studio called site.com and create a folder within that site for the part of the application they are developing. The resulting project structure in Visual Studio's Solution Explorer is shown below.

The right way to create the site in Visual Studio.

If your team consists of multiple developers and you want to ensure that you control who is working on particular parts of the project, it's wise to have your developers work off of a common site.com folder and use a source control system like TFS to check out the content that he or she needs to develop. If you don't have a source control system, you'll want to make sure that the web.config file in the site.com folder is the same for each developer and it's a good idea for each developer to change only files in his or her particular subfolder for the app.

The Terminology Can Cause Confusion

It's important that you understand the terminology involved in this kind of scenario. For example, Visual Studio can create an ASP.NET web site or an ASP.NET web application. An ASP.NET web site is not the same thing as a web site in IIS, and an ASP.NET web application is not the same as an application in IIS. I realize that's a bit confusing, so here's some information that might help to clear things up.

Web Site in Visual Studio

Web sites in Visual Studio were introduced with Visual Studio 2005. There is no project files in a web site (no .csproj or .vbproj) and the location for the web site can be anywhere on a disk. There is not a References folder in Solution Explorer when working with web sites. Instead, you set refereces in the Property Pages for the site. You are also not required to build (compile) a web site prior to running it. All of that takes place dynamically.

You create an ASP.NET web site in Visual Studio by selecting File, New Web Site.

Web Site in IIS

A web site in IIS is a node that is identified by its bindings. By default, there is one web site called Default Web Site with an HTTP binding all IPs to port 80. If you want to create a new web site, you would have to create a new binding to either a different port, a different IP, etc.

As you can see web site in Visual Studio is completely unrelated to web site in IIS.

Web Application in Visual Studio

A web application in Visual Studio uses the same model that was used for ASP.NET projects in Visual Studio .NET 2003. It was then reintroduced for Visual Studio 2005 as an add-on called Web Application Projects. That add-on became a full-fledged component of Visual Studio 2005 in SP1 and remains a component of Visual Studio 2008.

When the application is created, a project file is created along with the other files for the project. A gray-colored References folder appears in Solution Explorer so that you can review project references and/or add your own. There is also a special folder called Properties that contains the AssemblyInfo.cs or AssemblyInfo.vb file for the project. When you're ready to run the application, you must first compile it from the Build menu.

You create an ASP.NET web site in Visual Studio by selecting File, New Project.

Web Application in IIS

A web application in IIS is a node that has been marked as an application. An application in IIS is the level at which you would place your global.asax file. ASP.NET authentication methods (i.e. Windows, Forms, etc.) can be specificed at this level, but not lower in the hierarchy. Session variables and Forms authentication tickets are isolated to a web application in IIS.

As you can see a web application in Visual Studio is completely unrelated to a web application in IIS.

Final Thoughts

We worked with a customer at one point who had created a web application in Visual Studio that would eventually be deployed to the Default Web Site in IIS. During development, some of the developers who were creating portions of this site determined that they'd better create web sites in Visual Studio for their portion of the site because they new that this was eventually going to be deployed to a web site.

On the day of deployment, someone realized that the main project for the site was a web application, so they began the process of trying to convert the Visual Studio web application to a Visual Studio web site. In fact, we have thorough documentation about how to convert a web site to a web application, but going the other way is another matter altogether. The customers projects was huge, made up of thousands of pages and folders. After they had spent a considerable amount of time trying this on their own, they called us.

Getting everything back to working order took days of work, much of which was spent with the customer frustrated over a seemingly endless number of exceptions. Fix one exception and 200 others spring up to take its place. It's grueling work, and it was all the result of misunderstanding the terms and drawing correlations where none exists.

Hopefully the information I've provided here can help you to avoid a similar pitfall. Plan your projects carefully with deployment in mind, and make sure that you understand the fact that even though IIS and Visual Studio use some of the same terms, those terms mean something entirely different in each context.