Easily debug your custom Umbraco user controls in Visual Studio

Note: this post is over a year old, it's very likely completely outdated and should probably not be used as reference any more. You have been warned. :-)

I've been looking for the best way to debug when creating user controls for Umbraco, and there were no complete instructions available online.

The simplest way for me has been as follows.

When I create a new Umbraco website, I make a structure in my development folder of three folders under the site's name:

Database
UmbracoFramework
UmbracoModules

Logically, my database mdf/ldf files go into the "Database" folder. I do this to have everything belonging to the site close together.

In UmbracoFramework, I place the cleanly downloaded files of Umbraco's install. I've changed the default web.config to the .Net 3.5 version, using directory URL's.

One important thing to note is that, for this to work in Windows 7 (and probably Vista), you need to run Visual Studio as Administrator. If you don't, the debug session won't start. If there's any work-arounds for this, I'd love to know.

So let's see what we'd need to do in Visual Studio.

After starting VS2008, we create a new (blank) solution for this project.

umbvs08_01

Then we add an existing website (note you can do this either before installing Umbraco locally or right after right, it doesn't matter).

umbvs08_02

In your build configuration manager, make sure never to build this project, there's no need.

umbvs08_03

Now we can start creating a user control, add a new ASP.NET Web Application project in the folder UmbracoModules. We'll call this one (surprise!) "HelloWorld".

So a HelloWorld folder will be created under UmbracoModules.

umbvs08_05

We won't need the web.config and default.aspx, so I delete them.

We can automatically copy the dll/pdb files and the ascx files to the UmbracoFramework folder during each build. This is done using the post-build events:

XCOPY "$(ProjectDir)bin\HelloWorld.*" "$(ProjectDir)..\..\UmbracoFramework\bin\" /y
XCOPY "$(ProjectDir)*.ascx" "$(ProjectDir)..\..\UmbracoFramework\usercontrols\" /y

Note that "Helloworld.*" is the name of the dll/pdb's we want to copy. Don't use *.* here if you reference the Umbraco framework files, else they'll get copied over the existing verions each time.

umbvs08_06

For both the UmbracoFramework AND the new module, we'll change the default webserver into a "custom" one. This is just a link to the local domain name we created in IIS.

umbvs08_07

umbvs08_07_1

Once everything is saved, we're done. We can start creating a new user control and put breakpoints in them.

umbvs08_08

Hit F5 and see what happens.

umbvs08_09

Voila! A breakpoint being hit, we can start debugging.
Sebastiaan Janssen

Dutch guy living in (and loving) Copenhagen, working at Umbraco HQ. Lifehacker, skeptic, music lover, cyclist, developer.

 

7 comments on this article

Avatar for Jay Greasley Jay Greasley | August 20 2009 07:30
Very useful, thanks.

Avatar for Donald Burgess Donald Burgess | December 16 2009 06:27
Hello Jay
I have followed your instruction and also created a entry in IIS7 to create a website "UmbracoDevelop" with a physical path to "C:\users\admin\documents\projet1\UmbracoDevelop"
the folders UmbrcoFramework and UmbracoModules are in the UmbracoDevelop folder. I have set the custom Web Server to http://UmbracoDevelop for both HelloWord and UmbracoFramework.
Also checked all the permission and they seem OK.

However, when I run debug (F%5) I get an error "Unable to start debugging on the web server. The debugger cannot connect to the remote computer. ..."

Is there something I am missing in the instruction?

Thanks
Don

Avatar for Brendan Rice Brendan Rice | August 12 2011 00:39
I keep referring to your article for the post build events, think I owe you a "thank you" :)

Avatar for Michael Michael | May 23 2012 07:30
Great stuff!! You saved me hours of trying to figure that out myself...!!

Avatar for Lotte Lotte | September 13 2012 11:16
Would this way work with Visual Studio 2010 and the latest umbraco (4.9 at time of writing I believe)? Or has this approach now been revised since?

Also, whilst I'm at it, with v4.9 do you still need to create masterpages via the browser interface and not in VS directly (think that used to be the case)?

Avatar for Sebastiaan Janssen Sebastiaan Janssen | September 13 2012 11:40
Still works, although I've now switched to using IIS Express instead of IIS, saves a lot of time setting up IIS, hostnames and starting VS as administrator.

I'm not too sure about the masterpages, you can create them in VS, but they still need some umbraco directives, so I just create them in the backoffice. That way I can also immediately assign masterpages to document types.
That said, I've been using uSiteBuilder for that before, that makes it much more VS centric.

Avatar for Sebastiaan Janssen Sebastiaan Janssen | December 6 2012 10:31
As an update to this, the approach I now use is bundled in this little package:

http://our.umbraco.org/projects/developer-tools/umbraco-visual-studio-project