I ran into some issues with a web deployment project and wanted to record it for common knowledge. Basically, I added some references on a user control to another user control in a different folder. Big deal, right? Then I compiled it in VS 2005 and went about my business, tested it, and went to build the web deployment project. The build failed, and gave a couple of obscure (to me) error messages about not being able to find my control as well as not supporting circular references.

After burning too much time trying to figure this out, I finally ran across an obscure reference here that pointed me in the right direction. Here's what the issue is:

1. Web Deployment projects use aspnet_compile.exe to compile the project, and aspnet_merge.exe to merge the resulting .dll's into one big one for deployment. Visual Studio doesn't use aspnet_compile.exe.
2. Aspnet_compile.exe in a Web project takes each folder and compiles all the items under the folder to one .dll. Then they are merged.
3. Here's the problem. If you have multiple folders of user controls, say /folder1 and /folder2, and some of the controls in /folder2 have controls in /folder1 on them, then the first time you add a control in /folder1 that has a control from /folder2 on it you will get a circular reference error.
4. You won't get this error in Visual Studio with all the Intellisense to help you figure it out.
5. It will only fail in aspnet_merge.exe, which is used by many web deployment build scripts.

So, what to learn from this?

1. Organize your user controls to avoid circular reference problems.
2. Potentially use a WAP (Web Application Project) to avoid this. WAP's don't care about all the folders. You can pipe the output of a WAP into a WDP (Web Deployment Project) and still use the same build scripts