uSiteBuilder - The Absolute Beginners Guide

I came across uSiteBuilder earlier in 2012 when researching the best way to build Umbraco sites. I was tasked with architecting a base build from which subsequent projects could adapt and extend to a clients need. It was therefore very important that this site was maintainable, stable and easy to learn.

When I first tried out Razor I was fairly horrified by the use of the new at the time MVC and Dynamic Language Runtime features. Why isn’t visual studio giving me intellisense? Why am I writing C# in my HTML? I thought I may as well go back to hacking things together in PHP.

Over time I calmed down, I found that the Razor syntax was actually rather nice, powerful too, but the lack of intellisense in Visual Studio was painful, especially as cshtml files aren’t compiled and typos were only discovered at runtime. This wasn’t easy to use and I wasn’t happy having to use this on the base build.

Then uSiteBuilder popped up offering a code first approach with strongly, statically typed document types. Perfect!


Now uSiteBuilder is actually somewhat more complicated than just a code first way of defining document types, it is actually a completely different way to create Umbraco sites. Sites can be created using standard master pages and user controls without having to use Umbraco macros. Now this is cool, I can understand why people would like to develop in a way they are used to, but I like Umbraco macros especially now that I use Razor a lot.

Luckily uSiteBuilder doesn’t enforce this approach upon you, you can use as much or as little of the functionality as you want. I personally use uSiteBuilder to create statically, strongly typed document and member types that can be reused and version controlled. Yep, you heard that right you can get your document types into source control, nice.

Document Types in uSiteBuilder

All document types that you create using uSiteBuilder will be derived from the base class DocumentTypeBase. This class contains the standard properties that all umbraco nodes have (e.g. NiceUrl, Id and CreateDate).

To create a document type, you need to add a new cs file into the DocumentTypes folder of your uSiteBuilder project. This example will create a Page document type.

namespace Your.Namespace.CodeFirst.DocumentTypes
    using System;
    using Vega.USiteBuilder;

    /// summary
    /// The Page Class
    /// /summary 
    [DocumentType(Name = "Page", Description = "This is a page.")]
    public class Page : Vega.USiteBuilder.DocumentTypeBase

You see how the class is decorated with a “DocumentType” attribute, this is how uSiteBuilder knows that this is a document type. Here I have put in the name and description of the document type but you can also specify the icon, thumbnail, default template, allowed templates and allowed child node types. A fully decorated class may look like this:

[DocumentType(Name = "Page",
              Description = "This is the base document type for all pages.",
              AllowedTemplates = new string[] { "Page", “Page2” },
              DefaultTemplate = "Page",
              IconUrl = “icon.png”,
              Thumbnail = “thumbnail.png”,
              AllowedChildNodeTypes = new Type[] { typeof(SubPage)})]

This document type can have as many properties as desired, even zero, and these can be added as C# properties decorated with a DocumentTypeProperty attribute.

                      Name = "Main Title",
                      Description = "This is the highest level heading on a page.",
                      Tab = “Content”)]
public string MainTitle { get; set; }

To deploy this is simple. If your Umbraco installation is a straightforward website project then compile the uSiteBuilder project and copy both the generated DLL and the Vega.UsiteBuilder DLL over to the bin folder of the site. If you have the the Umbraco installation in a web application project just reference the uSiteBuilder project and the Vega.USiteBuilder DLL, build the solution and you’re good to go.

The first time after you build the solution (or any app pool restart) uSiteBuilder will perform its magic; the document types defined in the code first project will be synced to the Umbraco installation.

Things to remember:

  1. uSitebuilder never deletes anything (this may be changing though).
  2. The initial load on app start may be slightly longer.

Using uSiteBuilder in MacroScripts

When using the uSiteBuilder with Umbraco macros you’re first going to need to get an object that contains the properties stored in Umbraco. This can be done simply using the static methods in the ContentHelper class. To get the node Id you can use the Id property of the Model. If you want to get Intellisense on the node make sure to explicitly define nodeId as an int; leaving it implicitly typed (var) will give nodeId the type dynamic.

int nodeId = @Model.Id;
var node = Vega.USiteBuilder.ContentHelper.GetByNodeId(nodeId);

This will return node as an instance of the DocumentTypeBase class. This is quite useful as all of the basic properties of the document type will have Intellisense; this can be done already though using the DynamicNode class. The real benefit of uSiteBuilder comes when using the specific class you created in the code first project. This can be done using generics and the ContentHelper class.

int nodeId = @Model.Id;
var node = Vega.USiteBuilder.ContentHelper.GetByNodeId<Page>(nodeId);

This gets the specified node as the Page document type we defined earlier in the code first project. We can now use the strongly typed MainTitle property that is available in the Page object but not the DocumentTypeBase object.


This is the very basic way to use uSiteBuilder. The real power is not shown at this simplistic level, instead the power comes when having class hierarchies and types that are not strings, but that can wait for another day.


comments powered by Disqus