How I develop Umbraco

Dec 23 2010

Overview

In this article I'm going to cover the way that I setup my system for developing against Umbraco. I'm putting this together as everyone seems to have their own flavor to doing development so I thought I'd throw my hat into the arena with yet another setup to give new (and experienced) developers another way to go about it.

And hey, this has worked quite well for me for a while, maybe other can benefit from it ;).

Environment

So for this I'm going to be running the following software:

  • Visual Studio 2010
    • I use Cassini as a development database, not IIS. I don't use IIS as it requires (under Vista and 7) that you use an admin account to debug. Since my day-to-day Windows account isn't an admin (seriously, you don't need an admin for day-to-day work!) Cassini makes a lot more sense
  • SQL Server Express

Although I'm running Windows 7 I've used this setup on Windows XP and Vista as well, so don't fear if you're running an archaic OS :P.

Side note: I'm using the Umbraco Juno (4.6) beta release, but again this is a moot point, it works with any Umbraco 4.x instance

Getting Umbraco running

So once you've downloaded Umbraco and extracted it fire up Visual Studio. First thing I do is create a blank Visual Studio project

For development I use Web Application projects, so create a new empty Web Application (ensuring you've got the right version of .NET selected too ;)) using the naming schema of SolutionName.Web:

New WAP

Once I've added a Web Application I create the solutions required for WebFormsMVP projects, a Logic and Services project (which I then remove the Class1.cs file) and a Test project (omitted from here as it's not important to the overall post). This will end you up with an empty Visual Studio solution (well, except for a web.config file):

Look ma', no files

Now we have to copy all the files, except for the /bin folder, into Visual Studio:

Files to copy

There's already a web.config in the project, so we'll just replace it with the one that Umbraco supplied us, otherwise we wont have any of the config settings for Umbraco wont work, and we don't want that.

Now that Visual Studio is looking nicely filled out I exclude the following folders from the solution:

  • data
  • install
  • media
  • umbraco
  • umbraco_client

I also delete the App_Code folder.

There is method to this madness, I copy them across so I can ensure that they are in my project folder when I add it to source control. But the reason that I exclude it is so that Visual Studio wont include them in the JIT compilation when you fire up the debugger. This is most important with the /umbraco folder, as that contains ASP.Net files, the other folders (data, media, etc) don't contain files that I want in source control, so that's why I don't need them in Visual Studio.

Now the Solution Explorer looks a bit more useful:

Solution with Umbraco

It's almost done, there's just 1 more problem, we need to handle the Umbraco assemblies. As you'll remember we excluded that from being copied into Visual Studio. This is because the assemblies are a dynamic feature, so including them into the project directly is a bad idea, also, the /bin folder should never be included in source control!

So I close off Visual Studio so I can do some restructuring in Windows, basically I want the following structure in source control:

  • /src
    • /UmbracoDemo3.* (where the projects resides)
    • /UmbracoDemo3.sln
  • /lib
    • /umbraco-4.6

Now I copy across all the assemblies into the umbraco-4.6 folder, then upon reopening Visual Studio I add the assemblies as references into the Web project. Now when the project is compiled it will then copy all the assemblies into the local /bin for the web application. I recommend deleting the App_Global.asax.dll (and the reference to it) as it just becomes a royal pain in the ass when working with WebFormsMVP.

Any external assemblies which I need to include as a reference to a project that can't be obtained via NuGet I'll also put into there.

Note: You don't have to reference all of them, there is a subset of assemblies which you need to add and they will pull in the rest but I've never really sat down and worked out what ones they are.

Done, now you can spin up Cassini and then you're good to install Umbraco and start developing.

Conclusion

So that brings us to a finale of how I go about doing Umbraco setup with Visual Studio. Here's a few notices of things which I didn't cover in this article but can be useful to know:

  • I share databases, since the CI process of Umbraco isn't exactly great it's simpler to use a shared database for development
  • I use Visual Studio for pretty much all file editing (css, masterpages, IronRuby, etc), but I create them through the Umbraco UI as it will set up the database records nicely
umbraco
Posted by: Aaron Powell
Last revised: 26 Dec, 2010 01:11 PM History

Trackbacks

Comments

Jon Carlos
Jon Carlos
26 Dec, 2010 01:07 PM

Hey Aaron

Nice post but I have a couple of questions.

  1. How do you manage updating the version of Umbraco? Currently we run a web project and add an on build complete action to copy the files out in to a full Umbraco install, this enables us to replace the Umbraco install without copying/remembering all the files we've created/edited. It gives us very clear separation between what we made and what is Umbraco core.

  2. Where do you put your tests?

Cheers for the post, it's great a share this kind of stuff.

Jon

Matt Brailsford
Matt Brailsford
26 Dec, 2010 01:09 PM

Always great to see how others setup their projects. This is actually very similar to how I run now after seeing your unit testing session at CG10. I'm still yet to give WebFormsMVP a try simply due to the size of my projects not really being big enough, but will be giving it a try when a suitable project pops up.

Thanks for sharing.

Matt

Aaron Powell
Aaron Powell
26 Dec, 2010 01:18 PM

Jon

All the files which are "core" are excluded from Visual Studio, but I don't see how versioning is a concern. I've always said that no package should install into the /umbraco or /umbraco_client folder, because yes, you should be able to replace it if needed. Although I hardly ever see a project which I need to 'quickly upgrade' Umbraco. Clients pay for that to be done :P

As for tests, I left the project creation of out the steps mostly cuz I was lazy, partially because it wasn't important (I've added clarification into the post).

Matt

Even if the project only has a single .NET user control you should have WebFormsMVP, otherwise how are you testing that control ;). Also if you don't do it up front it can often be one of those "oh, I'll do it next time" thing, and "next time" is always put off ;).

Joshka
Joshka
26 Dec, 2010 01:38 PM

IIS Express can be run as a non-admin from Visual Studio 2010 Service Pack 1 (presently in beta).

Rick Mather
Rick Mather
26 Dec, 2010 03:42 PM

It's great to see how others, core developers especially, like to set up their Umbraco projects. After experimenting with using a separate web application and post build events, this is pretty much the same solution structure that I now use.

I'd be interested to know how you handle 3rd party packages. Do you move any package assemblies into the lib folder, and put these under source control as well? What about other package resources?

Roland
Roland
26 Dec, 2010 03:51 PM

Thanks for sharing, very useful blog entry.

ranjit
ranjit
26 Dec, 2010 04:01 PM

loved ur post....

Aaron Powell
Aaron Powell
26 Dec, 2010 10:24 PM

Josh

I deliberately ignored IIS Express as it's still a beta product in a beta service pack. It's also not supported in VS 2008 which I know a lot of devs still use.

Rick Mathers

I actually don't use a lot of packages, but ones I do use (ie - uComponents) I treat as external references and store them in the /lib folder structure.

Emmanuel Bellas
Emmanuel Bellas
29 Dec, 2010 01:02 AM

Hi Aaron,

I've been working on a substantial Custom Section app in the Umbraco admin.

I've got a bunch of aspx pages (which inherit umbraco.BasePages.UmbracoEnsuredPage for security), but I've just been putting this in a subfolder in the umbraco folder (e.g. /umbraco/[client_name]/).

I've also been using a completely separate project with build events to copy the files over to the umbraco installation folder. I've been trying to structure all of my custom usercontrols in such a way that the project can be run outside of the Umbraco admin.

What would you recommend the best structure be for custom sections in an Umbraco solution?

Aaron Powell
Aaron Powell
29 Dec, 2010 04:28 AM

Emmanuel

I would have a folder /plugins/[client name]/ and put everything in that.

I'm very much against putting anything in the /umbraco folders basically because when a new version is released you should be able to remove the whole folder and put the new one in, there's often a lot of changes in these folders between versions (new files, removed files, etc).

Emmanuel Bellas
Emmanuel Bellas
09 Jan, 2011 03:31 AM

Aaron

Thanks for your response.

After doing some Custom Section development for umbraco I have found the following:

  • to use a custom tray icon for your new section/app you need to place this icon in /umbraco/images/tray/ directory, or modify the /umbraco/css/umbracoGui.css file and declare a new class that your custom section will use.
    • ...remembering when you create a custom section you add an entry into the umbracoApp table and in the appIcon column you provide the name of the icon file or the css class (which will be located in the aforementioned folder/file respectively)
    • although you can probably just define the path of the appIcon field in the umbracoApp table as e.g. "../../../plugins/clientname/appIco.gif" so you don't need to place it in the umbraco ss folder.
  • When deploying, don't forget to also update the section (in /umbraco/config/lang/en.xml) to include an entry for the custom section (so that a nice "title" appears when you hover your mouse over the custom app icon).
  • if you make changes to the umbracoGui.css file, you will need to delete the files in /Appdata/TEMP/ClientDependency/ and /Appdata/ClientDependency/ for the changes to appear in the Umbraco admin.

As we can see we cannot get entirely away from the /umbraco/ folder. So far these are the only limitations I've found where you're pretty much forced to modify stuff inside the umbraco folder.

Aaron Powell
Aaron Powell
09 Jan, 2011 07:25 AM

No, you don't have to remove those folders just change the version in Client Dependency. Refer to the documentation: http://clientdependency.codeplex.com/documentation

Rasmus
Rasmus
05 Feb, 2011 11:50 PM

Hi

Great post. I'm new to this and MVP and I'm wondering what kind of projects the services and logic are ? by the look of the icon it looks like it is windows forms applications is that right ?

Aaron Powell
Aaron Powell
06 Feb, 2011 06:57 AM

They are class library projects. They have no UI concerns so they need no UI project

Mads
Mads
17 Apr, 2011 09:29 PM

Hi Aaron

Great post. I have a single problem, after setting everything op I get the error below. Any ideas?

Configuration Error Description: An error occurred during the processing of a configuration file required to service this request. Please review the specific error details below and modify your configuration file appropriately.

Parser Error Message: Could not load type 'umbraco.presentation.urlRewriter.FormRewriterControlAdapter'.

Source Error:

Line 3:    <browser refID="Default">
Line 4:      <controlAdapters>
Line 5:        <adapter controlType="System.Web.UI.HtmlControls.HtmlForm"
Line 6:                 adapterType="umbraco.presentation.urlRewriter.FormRewriterControlAdapter" />
Line 7:      </controlAdapters>

Source File: D:\Privat\Programming\Projects\Umbraco\Umbraco\App_Browsers\Form.browser Line: 5

Best Regards Mads

Aaron Powell
Aaron Powell
17 Apr, 2011 11:04 PM

I believe that that type resides in the umbraco.presentation assembly, so ensure that you've got that included in your /bin.

Mads
Mads
18 Apr, 2011 06:03 AM

Hi Aaron

That assembly is not in the downloaded folder from the umbraco website. If i just install the downloaded files in a IIS setup it works perfectly. So its kinda weird that i would need to download this file separated to get it working in visual studio?

Best regards Mads

Mads
Mads
18 Apr, 2011 06:11 AM

Hi again

If i should indeed download this file separated, do you have any idea where i can get it?

Best regards Mads

Aaron Powell
Aaron Powell
18 Apr, 2011 06:16 AM

My bad, it's in umbraco.dll.

I took a guess (didn't have the 4.7.x download on my machine) but I just looked and yeah, it's in umbraco.dll.

blog comments powered by Disqus