Shazwazza

Custom Assembly loading with Asp.Net Core

Thu, 23 Mar 2023 15:08:15 Z

Building a plugin system in Asp.Net Core is a dream compared to previous Asp.Net versions!

In previous versions it was not really feasible to load Assemblies located outside of the /bin folder for a web application. I battled with this concept quite a long time ago and although it’s sort of possible, the notion of having a plugin system that supported loading DLLs from outside of the /bin folder was riddled with hacks/problems and not really supported OOTB.

A large part of the issues has to do with something called an ‘Assembly Load Context’. In traditional .Net there are 3 of these context types: “Load”, “LoadFrom” and “Neither”, here’s a very old but very relevant post about these contexts from Suzanne Cook. In traditional Asp.Net, the “Load” context is used as the default context and it is managed by something called Fusion (.Net’s normal Assembly Loader/Binder). The problem with this context is that it is difficult to load an assembly into it that isn’t located in Fusion’s probing paths (i.e. /bin folder). If you load in an Assembly with a different Assembly Load Context and then try to mix it’s Types with the Types from the default context … you’ll quickly see that it’s not going to work.

The “Neither” context

Here is the Neither context definition as defined by Suzanne Cook:

If the user generated or found the assembly instead of Fusion, it's in neither context. This applies to assemblies loaded by Assembly.Load(byte[]) and Reflection Emit assemblies (that haven't been loaded from disk). Assembly.LoadFile() assemblies are also generally loaded into this context, even though a path is given (because it doesn't go through Fusion).

In Asp.Net Core (targeting CoreCLR), the default Assembly Load Context is the “Neither” context. This is a flexible context because it doesn’t use Fusion and it allows for loading assemblies any way that you want - including loading an assembly from a byte array, from a path or by a name. Since all of Asp.Net Core uses this context it means that all of the types loaded in with this context can talk to each other without having the previous Asp.Net problems.

I would assume that Asp.Net Core targeting Desktop CLR would still operate the same as before and still have the 3 types of Assembly Load Context’s … Maybe someone over at Microsoft can elaborate on that one? (David Fowler… surely you know? :)

Finding referenced plugin assemblies

In many cases if you create a product that supports plugin types, developers will create plugins for your product and ship them via Nuget. This is a pretty standard approach since it allows developers that are using your product to install plugins from the Nuget command line or from within Visual Studio. In this case plugin types will be found in referenced assemblies to your application and will be automatically loaded. Asp.Net Core has an interface called Microsoft.Extensions.PlatformAbstractions.ILibraryManager that can be used to resolve your application’s currently referenced ‘Libraries’ (i.e Nuget packages) and then each ‘Library’ returned exposes the Assemblies that it includes. Asp.Net MVC 6 has an even more helpful interface called Microsoft.AspNet.Mvc.Infrastructure.IAssemblyProvider which returns a list of referenced assemblies that are filtered based on if they are assemblies that reference a subset of MVC assemblies. The default implementation of IAssemblyProvider (DefaultAssemblyProvider) is extensible and we can use it to override it’s property ReferenceAssemblies in order to supply our own product assembly names instead of the MVC ones. This is perfect since this allows us to get a list of candidate assemblies that might contain plugins for your product:

public class ReferencePluginAssemblyProvider : DefaultAssemblyProvider
{
    //NOTE: The DefaultAssemblyProvider uses ILibraryManager to do the library/assembly querying
    public ReferencePluginAssemblyProvider(ILibraryManager libraryManager) : base(libraryManager)
    {
    }

    protected override HashSet<string> ReferenceAssemblies 
        => new HashSet<string>(new[] {"MyProduct.Web", "MyProduct.Core"});
}

now if you want to get a list of candidate assemblies that your application is referencing you could do:

//returns all assemblies that reference your product Assemblies
var candidateReferenceAssemblies = referencedPluginAssemblyProvider.CandidateAssemblies;

Finding and loading non-referenced plugin assemblies

This is where things get fun since this is the type of thing that wasn’t really very feasible with traditional Asp.Net web apps. Lets say you have a plugin framework where a plugin is installed via your web app, not in Visual Studio and therefore not directly referenced in your project. For this example, the plugin is a self contained collection of files and folders which could consist of: Css, JavaScript, Razor Views, and Assemblies. This plugin model is pretty nice since to install the plugin would mean just dropping the plugin folder into the right directory in your app and similarly to uninstall it you can just remove the folder. The first step is to be able to load in these plugin Assemblies from custom locations. For an example, let’s assume the web app has the following folder structure:

App Root
- App_Plugins <—This will be the directory that contains plugin folders
  - MyPlugin1
    - bin <—by convention we’ll search for Assemblies in the /bin folder inside of a plugin
    - Views
  - MyPlugin2
    - bin <—by convention we’ll search for Assemblies in the /bin folder inside of a plugin
    - css
- Views
- wwwroot

IAssemblyLoader

The first thing we need is an ‘Microsoft.Extensions.PlatformAbstractions.IAssemblyLoader’, this is the thing that will do the assembly loading into the Assembly Load Context based on an AssemblyName and a location of a DLL:

public class DirectoryLoader : IAssemblyLoader
{
    private readonly IAssemblyLoadContext _context;
    private readonly DirectoryInfo _path;

    public DirectoryLoader(DirectoryInfo path, IAssemblyLoadContext context)
    {
        _path = path;
        _context = context;
    }

    public Assembly Load(AssemblyName assemblyName)
    {
        return _context.LoadFile(Path.Combine(_path.FullName, assemblyName.Name + ".dll"));
    }

    public IntPtr LoadUnmanagedLibrary(string name)
    {
        //this isn't going to load any unmanaged libraries, just throw
        throw new NotImplementedException();
    }
}

IAssemblyProvider

Next up we’ll need a custom IAssemblyProvider but instead of using the one MVC ships with, this one will be totally custom in order to load and resolve the assemblies based on the plugin’s /bin folders. The following code should be pretty straight forward, the CandidateAssemblies property iterates over each found /bin folder inside of a plugin’s folder inside of App_Plugins. For each /bin folder found it creates a DirectoryLoader mentioned above and loads in each DLL found by it’s AssemblyName into the current Assembly Load Context.

/// <summary>
/// This will return assemblies found in App_Plugins plugin's /bin folders
/// </summary>
public class CustomDirectoryAssemblyProvider : IAssemblyProvider
{
    private readonly IFileProvider _fileProvider;
    private readonly IAssemblyLoadContextAccessor _loadContextAccessor;
    private readonly IAssemblyLoaderContainer _assemblyLoaderContainer;

    public CustomDirectoryAssemblyProvider(
            IFileProvider fileProvider, 
            IAssemblyLoadContextAccessor loadContextAccessor, 
            IAssemblyLoaderContainer assemblyLoaderContainer)
    {
        _fileProvider = fileProvider;
        _loadContextAccessor = loadContextAccessor;
        _assemblyLoaderContainer = assemblyLoaderContainer;
    }

    public IEnumerable<Assembly> CandidateAssemblies
    {
        get
        {
            var content = _fileProvider.GetDirectoryContents("/App_Plugins");
            if (!content.Exists) yield break;
            foreach (var pluginDir in content.Where(x => x.IsDirectory))
            {
                var binDir = new DirectoryInfo(Path.Combine(pluginDir.PhysicalPath, "bin"));
                if (!binDir.Exists) continue;
                foreach (var assembly in GetAssembliesInFolder(binDir))
                {
                    yield return assembly;
                }
            }
        }
    }

    /// <summary>
    /// Returns assemblies loaded from /bin folders inside of App_Plugins
    /// </summary>
    /// <param name="binPath"></param>
    /// <returns></returns>
    private IEnumerable<Assembly> GetAssembliesInFolder(DirectoryInfo binPath)
    {
        // Use the default load context
        var loadContext = _loadContextAccessor.Default;

        // Add the loader to the container so that any call to Assembly.Load 
        // will call the load context back (if it's not already loaded)
        using (_assemblyLoaderContainer.AddLoader(
            new DirectoryLoader(binPath, loadContext)))
        {
            foreach (var fileSystemInfo in binPath.GetFileSystemInfos("*.dll"))
            {
                //// In theory you should be able to use Assembly.Load() here instead
                //var assembly1 = Assembly.Load(AssemblyName.GetAssemblyName(fileSystemInfo.FullName));
                var assembly2 = loadContext.Load(AssemblyName.GetAssemblyName(fileSystemInfo.FullName));
                yield return assembly2;
            }
        }
    }
}

That’s pretty much it! If you have an instance of CustomDirectoryAssemblyProvider then you can get Assembly references to all of the assemblies found in App_Plugins:

//returns all plugin assemblies found in App_Plugins
var candidatePluginAssemblies = customDirectoryAssemblyProvider.CandidateAssemblies;

Integrating non-referenced plugins/Assemblies with MVC

What if you had custom plugin types as MVC Controllers or other MVC types? By default MVC only knows about assemblies that your project has references to based on the DefaultAssemblyLoader. If we wanted MVC to know about Controllers that exist in a plugin not referenced by your project (i.e. in App_Plugins) then it’s a case of registering a custom IAssemblyProvider in IoC which will get resolved by MVC. To make this super flexible we can create a custom IAssemblyProvider that wraps multiple other ones and allows you to pass in a custom referenceAssemblies filter if you wanted to use this to resolve your own plugin types:

public class CompositeAssemblyProvider : DefaultAssemblyProvider
{
    private readonly IAssemblyProvider[] _additionalProviders;
    private readonly string[] _referenceAssemblies;

    /// <summary>
    /// Constructor
    /// </summary>
    /// <param name="libraryManager"></param>
    /// <param name="additionalProviders">
    /// If passed in will concat the assemblies returned from these 
    /// providers with the default assemblies referenced
    /// </param>
    /// <param name="referenceAssemblies">
    /// If passed in it will filter the candidate libraries to ones
    /// that reference the assembly names passed in. 
    /// (i.e. "MyProduct.Web", "MyProduct.Core" )
    /// </param>
    public CompositeAssemblyProvider(
        ILibraryManager libraryManager,
        IAssemblyProvider[] additionalProviders = null,
        string[] referenceAssemblies = null) : base(libraryManager)
    {
        _additionalProviders = additionalProviders;
        _referenceAssemblies = referenceAssemblies;
    }

    /// <summary>
    /// Uses the default filter if a custom list of reference
    /// assemblies has not been provided
    /// </summary>
    protected override HashSet<string> ReferenceAssemblies
        => _referenceAssemblies == null
            ? base.ReferenceAssemblies
            : new HashSet<string>(_referenceAssemblies);
    
    /// <summary>
    /// Returns the base Libraries referenced along with any DLLs/Libraries
    /// returned from the custom IAssemblyProvider passed in
    /// </summary>
    /// <returns></returns>
    protected override IEnumerable<Library> GetCandidateLibraries()
    {
        var baseCandidates = base.GetCandidateLibraries();
        if (_additionalProviders == null) return baseCandidates;
        return baseCandidates               
            .Concat(
            _additionalProviders.SelectMany(provider => provider.CandidateAssemblies.Select(
                x => new Library(x.FullName, null, Path.GetDirectoryName(x.Location), null, Enumerable.Empty<string>(),
                    new[] { new AssemblyName(x.FullName) }))));
    }
}

To register this in IoC you just need to make sure it’s registered after you register MVC so that it overrides the last registered IAssemblyProvider:

//Add MVC services
services.AddMvc();
//Replace the default IAssemblyProvider with the composite one
services.AddSingleton<IAssemblyProvider, CompositeAssemblyProvider>(provider =>
{
    //create the custom plugin directory provider
    var hosting = provider.GetRequiredService<IApplicationEnvironment>();
    var fileProvider = new PhysicalFileProvider(hosting.ApplicationBasePath);
    var pluginAssemblyProvider = new CustomDirectoryAssemblyProvider(
        fileProvider,         
        PlatformServices.Default.AssemblyLoadContextAccessor,
        PlatformServices.Default.AssemblyLoaderContainer);
    //return the composite one - this wraps the default MVC one
    return new CompositeAssemblyProvider(
        provider.GetRequiredService<ILibraryManager>(),
        new IAssemblyProvider[] {pluginAssemblyProvider});
});

Your all set! Now you have the ability to load in Assemblies from any location you want, you could even load them in as byte array’s from an external data source. What’s great about all of this is that it just works and you can integrate these external Assemblies into MVC.

Some things worth noting:

Parts of the assembly loading APIs are changing a bit in Asp.Net Core RC2: https://github.com/aspnet/Announcements/issues/149
The above code doesn’t take into account what happens if you load in the same Assembly from multiple locations. In this case, the last one in wins/is active AFAIK – I haven’t tested this yet but I’m pretty sure that’s how it works.
You may have some issues if load in the same Assembly more than once from multiple locations if those Assemblies have different strong names, or major versions applied to them – I also haven’t tested this yet

Developing a plugin framework in ASP.NET MVC with medium trust

Thu, 23 Mar 2023 15:08:09 Z

I’ve recently spent quite a lot of time researching and prototyping different ways to create a plugin engine in ASP.NET MVC3 and primarily finding a nice way to load plugins (DLLs) in from outside of the ‘bin’ folder. Although this post focuses on MVC3, I am sure that the same principles will apply for other MVC versions.

The Issues

Loading DLLs from outside of the ‘bin’ folder isn’t really anything new or cutting edge, however when working with MVC this becomes more difficult. This is primarily due to how MVC loads/finds types that it needs to process including controllers, view models (more precisely the generic argument passed to a ViewPage or used with the @model declaration in Razor), model binders, etc… MVC is very tied to the BuildManager which is the mechanism for compiling views, and locating other services such as controllers. By default the BuildManager is only familiar with assembies in the ‘bin’ folder and in the GAC, so if you start putting DLLs in folders outside of the ‘bin’ then it won’t be able to locate the MVC services and objects that you might want it to be referencing.

Another issue that needs to be dealt with is DLL file locking. When a plugin DLL is loaded and is in use the CLR will lock the file. This becomes an an issue if developers want to update the plugin DLL while the website is running since they won’t be able to unless they bump the web.config or take the site down. This holds true for MEF and how it loads DLLs as well.

.Net 4 to the rescue… almost

One of the new features in .Net 4 is the ability to execute code before the app initializes which compliments another new feature of the BuildManager that lets you add assembly references to it at runtime (which must be done on application pre-init). Here’s a nice little reference to these new features from Phil Haack: http://haacked.com/archive/2010/05/16/three-hidden-extensibility-gems-in-asp-net-4.aspx. This is essential to making a plugin framework work with MVC so that the BuildManager knows where to reference your plugin DLLs outside of the ‘bin’. However, this isn’t the end of the story.

Strongly typed Views with model Types located in plugin DLLs

Unfortunately if you have a view that is strongly typed to a model that exists outside of the ‘bin’, then you’ll find out very quickly that it doesn’t work and it won’t actually tell you why. This is because the RazorViewEngine uses the BuildManager to compile the view into a dynamic assembly but then uses Activator.CreateInstance to instantiate the newly compiled object. This is where the problem lies, the current AppDomain doesn’t know how to resolve the model Type for the strongly typed view since it doesn’t exist in the ‘bin’ or GAC. An even worse part about this scenario is that you don’t get any error message telling you why this isn’t working, or where the problem is. Instead you get the nice MVC view not found error: “…or its master was not found or no view engine supports the searched locations. The following locations were searched: ….” telling you that it has searched for views in all of the ViewEngine locations and couldn’t find it… which is actually not the error at all. Deep in the MVC3 source, it tries to instantiate the view object from the dynamic assembly and it fails so it just keeps looking for that view in the rest of the ViewEngine paths.

NOTE: Even though in MVC3 there’s a new IViewPageActivator which should be responsible for instantiating the views that have been compiled with the BuildManager, implementing a custom IViewPageActivator to handle this still does not work because somewhere in the MVC3 codebase fails before the call to the IViewPageActivator which has to do with resolving an Assembly that is not in the ‘bin’.

Full trust

When working in Full Trust we have a few options for dealing with the above scenario:

Use the AppDomain’s ResolveAssembly event
- By subscribing to this event, you are able to instruct the AppDomain where to look when it can’t find a reference to a Type.
- This is easily done by checking if your plugin assemblies match the assembly being searched for, and then returning the Assembly object if found:

static Assembly CurrentDomain_AssemblyResolve(object sender, ResolveEventArgs args)
{
    var pluginsFolder = new DirectoryInfo(HostingEnvironment.MapPath("~/Plugins"));
    return (from f in pluginsFolder.GetFiles("*.dll", SearchOption.AllDirectories)
            let assemblyName = AssemblyName.GetAssemblyName(f.FullName)
            where assemblyName.FullName == args.Name || assemblyName.FullName.Split(',')[0] == args.Name
            select Assembly.LoadFile(f.FullName)).FirstOrDefault();
}

Shadow copy your plugin DLLs into the AppDomain’s DynamicDirectory.
- This is the directory that the BuildManager compiles it’s dynamic assemblies into and is also a directory that the AppDomain looks to when resolving Type’s from Assemblies.
- You can shadow copy your plugin DLLs to this folder on app pre-init and everything ‘should just work’
Replace the RazorViewEngine with a custom razor view engine that compiles views manually but makes references to the appropriate plugin DLLs
- I actually had this working in an Umbraco v5 prototype but it is hugely overkill and unnecessary plus you actually would have to replace the RazorViewEngine which is pretty absurd.

The burden of Medium Trust

In the MVC world there’s only a couple hurdles to jump when loading in plugins from outside of the ‘bin’ folder in Full Trust. In Medium Trust however, things get interesting. Unfortunately in Medium Trust it is not possible to handle the AssemblyResolve event and it’s also not possible to access the DynamicDirectory of the AppDomain so the above two solutions get thrown out the window. Further to this it seems as though you can’t use CodeDom in Medium Trust to custom compile views.

Previous attempts

For a while I began to think that this wasn’t possible and I thought I tried everything:

Shadow copying DLLs from the plugins folder into the ‘bin’ folder on application pre-init
- This fails because even during app pre-init, the application pool will still recycle. Well, it doesn’t actually ‘fail’ unless you keep re-copying the DLL into the bin. If you check if it already exists and don’t copy into the bin than this solution will work for you but it’s hardly a ‘solution’ since you might as well just put all your DLLs into the ‘bin’ in the first place.
Trying to use sub folders of the ‘bin’ folder to load plugins.
- Turns out that ASP.Net doesn’t by default load in DLLs that exist in sub folders of the bin, though from research it looks like standard .Net apps actually do.
- Another interesting point was that if you try to copy a DLL into a sub folder of the bin during application pre-init you get a funky error: “Storage scopes cannot be created when _AppStart is executing”. It seems that ASP.Net is monitoring all changes in the bin folder regardless of whether or not they are in sub folders but still doesn’t load or reference those assemblies.

An easy solution

So, the easy solution is to just set a ‘privatePath’ on the ‘probing’ element in your web.config to tell the AppDomain to also look for Assemblies/Types in the specified folders. I did try this before when trying to load plugins from sub folders in the bin and couldn’t get it to work. I’m not sure if I was ‘doing it wrong’ but it definitely wasn’t working then, either that or attempting to set this in sub folders of the bin just doesn’t work.

<runtime>
  <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">       
    <probing privatePath="Plugins/temp" />

DLL file locking

Since plugin DLLs get locked by the CLR when they are loaded, we need to work around this. The solution is to shadow copy the DLLs to another folder on application pre-init. As mentioned previously, this is one of the ways to get plugins loaded in Full Trust and in my opinion is the nicest way to do it since it kills 2 birds with one stone. In Medium Trust however, we’ll have to jump through some hoops and shadow copy the DLLs to a temp folder that exists within the web application. IMPORTANT: When you’re copying DLLs you might be tempted to modify the name of the DLL by adding a version number or similar, but this will NOT work and you’ll get a “The located assembly's manifest definition … does not match the assembly reference.” exception.

Solution

UPDATE: The latest version of this code can be found in the Umbraco v5 source code. The following code does work but there’s been a lot of enhancements to it in the Umbraco core. Here’s the latest changeset as of 16/16/2012 Umbraco v5 PluginManager.cs

Working in Full Trust, the simplest solution is to shadow copy your plugin DLLs into your AppDomain DynamicDirectory. Working in Medium Trust you’ll need to do the following:

On application pre-init:
- Shadow copy all of your plugin DLLs to a temporary folder in your web application (not in the ‘bin’)
- Add all of the copied DLLs to be referenced by the BuildManager
Add all folder paths to the privatePath attribute of the probing element in your web.config to point to where you will be copying your DLLs
- If you have more than one, you need to semi-colon separate them

Thanks to Glenn Block @ Microsoft who gave me a few suggestions regarding DLL file locking with MEF, Assembly load contexts and probing paths! You put me back on track after I had pretty much given up.

Here’s the code to do the shadow copying and providing the Assemblies to the BuildManager on application pre-init (make sure you set the privatePath on the probing element in your web.config first!!)

using System.Linq;
using System.Web;
using System.IO;
using System.Web.Hosting;
using System.Web.Compilation;
using System.Reflection;

[assembly: PreApplicationStartMethod(typeof(PluginFramework.Plugins.PreApplicationInit), "Initialize")]

namespace PluginFramework.Plugins
{
    public class PreApplicationInit
    {

        static PreApplicationInit()
        {
            PluginFolder = new DirectoryInfo(HostingEnvironment.MapPath("~/plugins"));
            ShadowCopyFolder = new DirectoryInfo(HostingEnvironment.MapPath("~/plugins/temp"));
        }

        /// <summary>
        /// The source plugin folder from which to shadow copy from
        /// </summary>
        /// <remarks>
        /// This folder can contain sub folderst to organize plugin types
        /// </remarks>
        private static readonly DirectoryInfo PluginFolder;

        /// <summary>
        /// The folder to shadow copy the plugin DLLs to use for running the app
        /// </summary>
        private static readonly DirectoryInfo ShadowCopyFolder;

        public static void Initialize()
        {            
            Directory.CreateDirectory(ShadowCopyFolder.FullName);

            //clear out plugins)
            foreach (var f in ShadowCopyFolder.GetFiles("*.dll", SearchOption.AllDirectories))
            {
                f.Delete();
            }            

            //shadow copy files
            foreach (var plug in PluginFolder.GetFiles("*.dll", SearchOption.AllDirectories))
            {
                var di = Directory.CreateDirectory(Path.Combine(ShadowCopyFolder.FullName, plug.Directory.Name));
                // NOTE: You cannot rename the plugin DLL to a different name, it will fail because the assembly name is part if it's manifest
                // (a reference to how assemblies are loaded: http://msdn.microsoft.com/en-us/library/yx7xezcf )
                File.Copy(plug.FullName, Path.Combine(di.FullName, plug.Name), true);
            }
            
            // Now, we need to tell the BuildManager that our plugin DLLs exists and to reference them.
            // There are different Assembly Load Contexts that we need to take into account which 
            // are defined in this article here:
            // http://blogs.msdn.com/b/suzcook/archive/2003/05/29/57143.aspx

            // * This will put the plugin assemblies in the 'Load' context
            // This works but requires a 'probing' folder be defined in the web.config
            foreach (var a in
                ShadowCopyFolder
                .GetFiles("*.dll", SearchOption.AllDirectories)
                .Select(x =>  AssemblyName.GetAssemblyName(x.FullName))
                .Select(x => Assembly.Load(x.FullName)))
            {
                BuildManager.AddReferencedAssembly(a);
            }

            // * This will put the plugin assemblies in the 'LoadFrom' context
            // This works but requires a 'probing' folder be defined in the web.config
            // This is the slowest and most error prone version of the Load contexts.            
            //foreach (var a in
            //    ShadowCopyFolder
            //    .GetFiles("*.dll", SearchOption.AllDirectories)
            //    .Select(plug => Assembly.LoadFrom(plug.FullName)))
            //{
            //    BuildManager.AddReferencedAssembly(a);
            //}

            // * This will put the plugin assemblies in the 'Neither' context ( i think )
            // This nearly works but fails during view compilation.
            // This DOES work for resolving controllers but during view compilation which is done with the RazorViewEngine, 
            // the CodeDom building doesn't reference the plugin assemblies directly.
            //foreach (var a in
            //    ShadowCopyFolder
            //    .GetFiles("*.dll", SearchOption.AllDirectories)
            //    .Select(plug => Assembly.Load(File.ReadAllBytes(plug.FullName))))
            //{
            //    BuildManager.AddReferencedAssembly(a);
            //}

        }
    }
}

Umbraco Jupiter Plugins - Part 2 - Routing

Thu, 23 Mar 2023 15:08:09 Z

This is the second blog post in a series of posts relating to building plugins for Umbraco v5 (Jupiter).

Related Posts:

Umbraco Jupiter Plugins – Part 1

Disclaimer

This post is about developing for Umbraco v5 (Jupiter) which at the time of this post is still under development. The technical details described below may change by the time Umbraco Jupiter is released. If you have feedback on the technical implementation details, please comment below.

Routing & URLs

As mentioned in the previous post Umbraco Jupiter will consist of many types of plugins, and of those plugins many of them exist as MVC Controllers. Each controller has an Action which a URL is routed to, this means that each Controller plugin in Jupiter requires it’s own unique URLs. The good news is that you as a package developer need not worry about managing these URLs and routes, Jupiter will conveniently do all of this for you.

Packages & Areas

My previous post mentioned that a ‘Package’ in Jupiter is a collection of ‘Plugins’ and as it turns out, Plugins can’t really function unless they are part of a Package. In it’s simplest form, a Package in v5 is a folder which contains Plugins that exists in the ~/Plugins/Packages sub folder. The folder name of the package becomes very important because it is used in setting up the routes to create the unique URLs which map to the MVC Controller plugins. Package developers should be aware that they should name their folder to something that is reasonably unique so it doesn’t overlap with other Package folder names. During package installation, Jupiter will check for uniqueness in Package folder names to ensure there is no overlap (there will be an entirely separate post on how to create deployment packages and how to install them).

Here’s a quick example: If I have a Package that contains a Tree plugin called TestTree (which is in fact an MVC Controller) and I’ve called my Package folder ‘Shazwazza’, which exists at ~/Plugins/Packages/Shazwazza then the URL to return the JSON for the tree is: http://localhost/Umbraco/Shazwazza/Trees/TestTree/Index

Similarly, if I have a Editor plugin called TestEditor with an action called Edit, then a URL to render the Edit Action is:

http://localhost/Umbraco/Shazwazza/Editors/TestEditor/Edit

If you’ve worked with MVC, you’ll probably know what an MVC Area is. The way that Jupiter creates the routes for Packages/Plugins is by creating an MVC Area for each Package. This is how it deals with the probability that different Package developers may create MVC Controllers with the same name. MVC routes are generally based just on a Controller name and an Action name which wouldn’t really work for us because there’s bound to be overlap amongst Package developers, so by creating an Area for each Package the route becomes unique to a combination of Controller name, Action name and Area name. MVC also determines where to look for Views based on Area name which solves another issue of multiple Packages installed with the same View names.

Whats next?

In the coming blog posts I’ll talk about

how plugins are installed and loaded
how and where the Views are stored that the plugins reference
how to create all of the different types of plugins

Code Garden 2011

I’ll be doing a talk on Plugins for Umbraco Jupiter at Code Garden 2011 this year which will go in to a lot more detail than these blog posts. If you are attending Code Garden already, then hopefully this series will give you a head start on Umbraco v5. If you haven’t got your tickets to Code Garden yet, what are you waiting for?! We have so much information to share with you :)

Registering custom components in IoC for Umbraco 5 plugins

Thu, 23 Mar 2023 15:08:08 Z

Sometimes you might need to add some of your own components to the IoC container in Umbraco 5 for your plugins to function. We’ve made this extremely easy to do and it only requires 2 steps:

Create a custom class that implements Umbraco.Framework.DependencyManagement.IDependencyDemandBuilder . Ensure that this class does not have any constructor parameters otherwise it will not work. There’s only one method to implement and you can use the containerBuilder parameter to add stuff to the IoC container:

void Build(IContainerBuilder containerBuilder, IBuilderContext context);

Next you need to attribute your plugin (i.e. Tree, Editor, Menu Item, Property Editor, Surface Controller, etc….) to tell it which ‘Demand Builder’ to use. Easiest to explain with an example:

[DemandsDependencies(typeof(MyCustomBuilder))]
[Tree("4883C970-2499-488E-A963-5204F6C6F840", "My Tree")]
public class MyCustomTree : TreeController

The above code will ensure that the ‘Demand Builder’ of type MyCustomBuilder will be executed when this plugin is loaded

Thats it! Now you can add anything you need to the IoC container if you require this for your plugin.

How to inspect assemblies with reflection before including them in your application

Thu, 23 Mar 2023 15:08:08 Z

If you application supports plugins or extensions in some cases it might be useful to scan a packages assemblies before importing them in to your app. Some reasons for this might be:

Checking if the package has missing assembly references
Checking if the assembly references obsolete types that might make the package unstable
Checking the .Net targeted framework of the assembly
Any other assembly inspection to determine it is compatible with your app

To do this you can load assemblies using Assembly.ReflectionOnlyLoadFrom and Assembly.ReflectionOnlyLoad methods which load assemblies into a special assembly load context called “reflection-only context” which will safely let you inspect these assemblies.

Further reading:

A great article on Reflection Only Assembly Loading and if you want to know more about assembly load contexts, here’s an explanation.

Loading in assemblies

For this example, we’ll assume that all of the assemblies for a package are in some folder outside of the normal /bin folder (not loaded in to the current app) and each assembly for the package will need to be inspected for type references that are not supported.

A common mistake when loading in assemblies with reflection (especially in the LoadFrom context) is to load them in one at a time, whereas they generally will need to be all loaded in before inspecting them since they probably have references to each other. Another thing that generally must be done is adding an event listener on AppDomain.ReflectionOnlyAssemblyResolve because even though all known referenced assemblies are loading into the context some assemblies might not be explicitly referenced but are need to load the assembly. This handler provides a way to resolve those missing references.

The first thing to do is setup the event handler

AppDomain.CurrentDomain.ReflectionOnlyAssemblyResolve += (s, e) =>
{
    var a = Assembly.ReflectionOnlyLoad(e.Name);
    if (a == null) throw new TypeLoadException("Could not load assembly " + e.Name);
    return a;
};

Next we need to load all of the assembly files in the folder

foreach (var f in files) Assembly.ReflectionOnlyLoadFrom(f);

Then load all of their referenced assemblies in to the reflection context

//Then load each referenced assembly into the context
var assembliesWithErrors = new List<string>();
foreach (var f in files)
{
    var reflectedAssembly = Assembly.ReflectionOnlyLoadFrom(f);
    foreach (var assemblyName in reflectedAssembly.GetReferencedAssemblies())
    {
        try
        {
            Assembly.ReflectionOnlyLoad(assemblyName.FullName);
        }
        catch (FileNotFoundException)
        {
            //if an exception occurs it means that a referenced assembly could not be found                        
            errors.Add(
                string.Concat("This package references the assembly '",
                    assemblyName.Name,
                    "' which was not found, this package may have problems running"));
            assembliesWithErrors.Add(f);
        }
    }
}

In the catch, I’m detecting assembly reference errors and adding an error message to the outgoing method response and also adding that assembly to the assembliesWithErrors list which is used later to ensure we’re not inspecting assemblies that couldn’t be loaded.

Now that all the assemblies are loaded we can inspect them (ignoring ones with errors). This example is looking for any assemblies that have types implementing ‘MyType’. If they do implement this type, add the assembly to a list to return from the current method.

//now that we have all referenced types into the context we can look up stuff
foreach (var f in files.Except(assembliesWithErrors))
{
    //now we need to see if they contain any type 'MyType'
    var reflectedAssembly = Assembly.ReflectionOnlyLoadFrom(f);
    var found = reflectedAssembly.GetExportedTypes()
        .Where(TypeHelper.IsTypeAssignableFrom<MyType>);
    if (found.Any())
    {
        dllsWithReference.Add(reflectedAssembly.FullName);
    }
}

Separate AppDomain

It’s best to execute all of this logic in a separate AppDomain because once assemblies are loaded in to a context, they cannot be unloaded and since we are loading in from files, those files will remain locked until the AppDomain is shutdown. Explaining how to create a separate AppDomain is outside the scope of this article but the code is included in the source below.

Source Code

Here’s a class the encapsulates all of this logic and of course if you can do much more when inspecting assemblies for various types.

https://gist.github.com/Shazwazza/7147978

Umbraco Jupiter Plugins - Part 5 - Surface Controllers

Thu, 23 Mar 2023 15:08:08 Z

This is the fifth blog post in a series of posts relating to building plugins for Umbraco v5 (Jupiter). This post will explain what a Surface Controller is, what they can be used for and how to create one.

Disclaimer

Related Posts:

What is a Surface Controller?

A Surface Controller is an MVC controller that interacts with the front-end (or render layer) of Umbraco. An example of a Surface Controller could be a controller that has a Child Action used to display a Twitter Feed, or a controller that has an Action to accept some posted information from a form. Child Actions on Surface Controller will probably be primarily used for Child Action Macros in Umbraco v5.

Since Surface Controllers are plugins, this means that you can create a package that contains Surface Controllers to distribute whatever front-end functionality you like to Umbraco developers. Surface Controllers, just like Tree Controllers and Editor Controllers get automatically routed for you.

Creating a Surface Controller

Important convention: All Surface controller names MUST be suffixed with ‘SurfaceController’. For example, if you are creating a Surface Controller to display system a Twitter feed, you might call your controller: TwitterFeedSurfaceController. If you don’t follow this convention, you’re surface controller wont be routed.

The first step is to create a class that inherits from the base Surface Controller class: Umbraco.Cms.Web.Surface.SurfaceController

The next step is to define some MVC Action’s to do whatever it is you’d like them to do. Here’s some examples:

Creating an action to partake in a Child Action Macro. To define this is very simple and follows the exact same MVC principles to creating a Child Action… just add a ChildActionOnlyAttribute to your action method:

[ChildActionOnly]
public ActionResult DisplayTwitterFeed()

Creating a child action to simply be used as a normal MVC child action which get rendered using @Html.Action or @Html.RenderAction
Create an action to handle some posted form data:

[HttpPost]
public ActionResult HandleMyFormSubmission(MyFormModel model)

Maybe you’d like to track all links clicked on your page. You could use jquery to update all of your links on your page to point to your custom action URL with the real URL as a query string. Then your custom action will log the real link address and redirect the user to where they want to go.

Plugins vs Non-plugins

A Surface Controller ‘can’ be a plugin, meaning that you can create it as a plugin and distribute it as part of a package. However, if you are creating your own Umbraco website and do your development in Visual Studio like most of us, you don’t need to create a Surface Controller with a plugin definition and install it as part of a package, you can just define it locally just like a controller in a normal MVC project. If you do want to ship your Surface Controller as part of a package then you must attribute your Surface Controller with the SurfaceAttribute, and give it an Id. If you don’t do this then Umbraco will detect that its loading a Surface Controller plugin without an Id and throw an exception.

As a plugin

Standard practice for creating any kind of controller is to put your controllers in the ‘Controllers’ folder (this is not mandatory but a simple convention to follow). So If you’ve created a new project in Visual Studio, you’d create a folder called ‘Controllers’, then create your Surface Controller class with the SurfaceAttribute and an Id:

using System.Web.Mvc;
using Umbraco.Cms.Web.Context;
using Umbraco.Cms.Web.Surface;
using Umbraco.Framework;

namespace MyProject.Controllers
{
    [Surface("98625300-6DF0-41AF-A432-83BD0232815A")]
    public class TwitterFeedSurfaceController : SurfaceController
    {

    }
}

Because this Surface Controller is a plugin, you’ll need to attribute your project assembly (just like when creating Trees or Editor plugins). You can declare this in any of your classes or in the AssemblyInfo.cs file.

[assembly: AssemblyContainsPlugins]

As a locally declared Surface Controller

This is pretty much identical to the above but you don’t have to include the SurfaceAttribute or attribute your assembly. If you’ve got an Umbraco v5 website that you’re working on you should just create a ~/Controllers folder to put your controller in, just as if you were creating a normal MVC project. Then you can create your Surface Controller:

using System.Web.Mvc;
using Umbraco.Cms.Web.Context;
using Umbraco.Cms.Web.Surface;
using Umbraco.Framework;

namespace MyProject.Controllers
{
    public class TwitterFeedSurfaceController : SurfaceController
    {

    }
}

Using a Surface Controller

The usage of a Surface Controller really depends on what you’ve created your surface controller to do. Probably the 3 main ways to use them will be:

Create a ChildAction Macro by using the Macro UI in the back office and selecting a child action that you’ve declared on your Surface Controller, then render the macro in your template or inline in the WYSIWYG editor.
Directly render a child action declared on your Surface Controller by using @Html.Action or @Html.RenderAction
Create an Html form to post data to an action on your Surface Controller using @Html.BeginUmbracoForm (more on this in the next blog post!)

Umbraco Jupiter Plugins - Part 1

Thu, 23 Mar 2023 15:08:08 Z

This is the first blog post in a series of posts relating to building plugins for Umbraco v5 (Jupiter)

Disclaimer

What is a plugin

Since Umbraco Jupiter has been built from the ground up, we first need to define some v5 terminology:

Plugin = A single functional component that extends Umbraco such as a Tree, an Editor, a Menu Item, etc…
Package = A group of Plugins installed into Umbraco via the ~/Plugins/Packages/[Package Name] folder

The Umbraco v5 back-office has been architected to run entirely on Plugins, in fact the core trees, editors, etc… that are shipped with Umbraco are Plugins in v5.

Types of plugins

The list of Plugin types will most likely increase from the time of this blog post to when Jupiter is launched but as it stands now here are the types of Plugins supported in v5:

Property Editors
- This term is new to v5. In v4.x there was no differentiation between a Data Type and it’s underlying ‘Data Type’ editor. In v5 we’ve made a clear distinction between a ‘Data Type’ (as seen in the Data Type tree and used as properties for Document Types) and the underlying editor and pre-value editor that it exposes. An example of a Property Editor would be uComponents’ Multi-Node Tree Picker. An example of a Data Type would be when an Umbraco administrator creates a new Data Type node in the Data Type tree and assigns the Multi-Node Tree Picker as it’s Property Editor.
- So uComponents Team, this is where you need to focus your efforts for version 5!
Menu Items
- Context menu items such as Create, Publish, Audit Trail, etc… are all plugins.
- See this post in regards to creating menu items in v5, though there have been some new features added since that article was created which I’ll detail in coming posts in this series.
Editors
- Editor plugins are all of the interactions performed in the right hand editor panel and in modal dialogs in the back-office.
- For example, the Content Editor core plugin in v5 manages the rendering for all views such as editing content, sorting, copying, and moving nodes, and nearly all of the other views that the context menu actions render.
- Editors are comprised mostly of MVC Controllers, Views, JavaScript & CSS.
Trees
- All trees are plugins, for example, the Content tree, Media tree, Document Type tree are all different plugins.
- Trees are actually MVC controllers.
- Tree nodes use Menu Items to render Editors
Presentation Addins (Yet to be officially named)

Another type of plugin are Controllers that are installed via packages that interact with the presentation layer, an example of this might be the Controller Action that accepts the post values from a Contour form.

Whats next?

In the coming blog posts I’ll talk about

how plugins are installed and loaded
how the Umbraco routing system works with all of these controllers
how and where the Views are stored that the plugins reference
how to create all of the different types of plugins

Code Garden 2011

Umbraco Jupiter Plugins - Part 4 - Editors

Thu, 23 Mar 2023 15:08:08 Z

This is the fourth blog post in a series of posts relating to building plugins for Umbraco v5 (Jupiter). This post will show you how to get started with building an editor. An Editor is the term used to express the editing pane on the right hand side of the back-office. Examples include: the content editor, media editor, document type editor, script editor, etc..

Related Posts:

Disclaimer

Defining an Editor

An Editor in Umbraco v5 is the combination of: An MVC Controller, View(s), JavaScript and CSS. The first step to creating an Editor is to create a class that inherits from the Umbraco base editor class: Umbraco.Cms.Web.Editors.StandardEditorController.

The next step is to register this editor as an editor plugin. To do this you just need to add an attribute to your class such as:

[Editor("ADD307B3-A5F9-4A89-ADAC-72289A5943FF")]

The mandatory parameter passed to this attribute is the editor plugin ID (this MUST be unique so ensure you generated a new GUID for every single one of your plugins).

The next thing you’ll need to do to ensure your editor plugin is found and loaded is to ‘advertise’ that your assembly contains a plugin. To do this, just edit your assembly’s AssemblyInfo.cs file and add the following attribute:

[assembly: AssemblyContainsPlugins]

Creating an Editor

Important convention: All Editor controller names MUST be suffixed with ‘EditorController’. For example, if you are creating an editor to display system information, you might call your Editor: SystemInfoEditorController. If you don’t follow this convention, you’re editor controller wont be routed.

When creating an Editor there are a few base classes to choose from. Generally however, you should inherit from: Umbraco.Cms.Web.Editors.StandardEditorController. The other base classes and their hierarchy are as follows:

Umbraco.Cms.Web.Mvc.Controllers.BackOffice.SecuredBackOfficeController
- Umbraco.Cms.Web.Editors.BaseEditorController
  - Umbraco.Cms.Web.Editors.DashboardEditorController
    - Umbraco.Cms.Web.Editors.StandardEditorController

When inheriting from any of the base classes above, you will be required to create a constructor accepting an parameter of type: IBackOfficeRequestContext :

[Editor("ADD307B3-A5F9-4A89-ADAC-72289A5943FF")]
public class MyEditorController : StandardEditorController
{
    public MyEditorController(IBackOfficeRequestContext requestContext)
        : base(requestContext)
    {
    }        
}

The StandardEditorController has an abstract method: Edit(HiveId id) that needs to be implemented (the abstract Edit Action is marked as [HttpGet])

[Editor("ADD307B3-A5F9-4A89-ADAC-72289A5943FF")]
public class MyEditorController : StandardEditorController
{
    public MyEditorController(IBackOfficeRequestContext requestContext)
        : base(requestContext)
    {
    }
        
    public override ActionResult Edit(HiveId id)
    {
        return View();
    }
}

Most Editors will be displaying a view to edit data based on a HiveId which is the unique identifier type for pretty much all data in Umbraco 5. If you are writing an editor to edit data in a custom Hive provider, then this will work seamlessly for you. Even if you are creating an editor for data that you aren’t writing a custom Hive provider for, you can still use HiveId as a unique identifier since it has support for wrapping Guid, Int and String Id types. If however you decide that HiveId isn’t for you, then you can inherit from one of the other editor base classes that doesn’t have the abstract Edit method attached to it and create your own Actions with your own parameters.

The above Edit Action simply returns a view without a model to be rendered. At this point, you’ll need to know where your view should be stored which has everything to do with MVC Areas or embedding views.

MVC Areas & Jupiter Packages

In a previous post we talk about how packages in v5 are actually registered as their own MVC Area. All packages get installed to the following location: ~/App_Plugins/Packages/{YourPackageName} . If you aren’t embedding your views, then they should be stored inside of your package folder. Each plugin type has a specific view folder name that your views should be stored in:

Editor views & partial views:
- ~/App_Plugins/Packages/{YourPackageName}/Editors/Views/ {EditorControllerName}/{ViewName}.cshtml
- ~/App_Plugins/Packages/{YourPackageName}/Editors/Views/Shared/ {ViewName}.cshtml
Property Editor partial views:
- ~/App_Plugins/Packages/{YourPackageName}/PropertyEditors/Views/Shared/ {ViewName}.cshtml
Dashboard partial views:
- ~/App_Plugins/Packages/{YourPackageName}/Dashboards/Views/ {ViewName}.cshtml
Rendering (front-end) partial views:
- ~/App_Plugins/Packages/{YourPackageName}/Views/Partial/ {ViewName}.cshtml

So with the controller created above, I would have a view in the following location:

~/App_Plugins/{MyPackageName}/Editors/Views/MyEditor/Edit.cshtml

NOTE: The package name folder will be created when installing your NuGet package and will be based on your NuGet package name and version assigned.

Embedding views

Many of the views shipped with v5 are embedded which helps to reduce the number of actual files that are shipped. This is also handy if you don’t want to give the ability for people to change what’s in your markup.

Embedding a view is really easy:

Create a Razor (.cshtml) view in your Package’s project
View the Properties for this file and choose ‘Embedded Resource’ as the ‘Build Action’

Now to use the embedded view we use the following syntax:

[Editor("ADD307B3-A5F9-4A89-ADAC-72289A5943FF")]
public class MyEditorController : StandardEditorController
{
    public MyEditorController(IBackOfficeRequestContext requestContext)
        : base(requestContext)
    {
    }
        
    public override ActionResult Edit(HiveId id)
    {
        return View(EmbeddedViewPath.Create("MyProject.Editors.Views.Edit.cshtml"));
    }
}

Its important to get the correct path to your view file. In this instance, my view’s path in my project is: MyProject.Editors.Views.Edit.cshtml

Displaying your Editor

Most of the time an editor is displayed by clicking on a node in the tree or by accessing a context menu item. In a previous post about creating trees there was a method to create a tree node:

protected override UmbracoTreeResult GetTreeData(HiveEntityUri id, FormCollection queryStrings)
{
    NodeCollection.Add(
        CreateTreeNode(id, null, "My only node", string.Empty, false));
    return UmbracoTree();
}

This simply created a tree node that had no editor URL but now that we have an editor, I’ll update the code to click through to my Edit Action:

protected override UmbracoTreeResult GetTreeData(HiveId id, FormCollection queryStrings)
{
    NodeCollection.Add(
        CreateTreeNode(id, null, "My only node",
        Url.GetEditorUrl("MyEditor", id, new Guid("ADD307B3-A5F9-4A89-ADAC-72289A5943FF")),
        false));
    return UmbracoTree();
}

GetEditorUrl is an extension method of UrlHelper which has a few overloads for generating an Editor’s Url. In this case we are passing in the Editor’s name and Id with the Id of the current node being rendered in the tree.

When the node is clicked it will now link to the Edit Action of the MyEditor Controller.

Umbraco Jupiter Plugins - Part 3 - Trees

Thu, 23 Mar 2023 15:08:08 Z

This is the third blog post in a series of posts relating to building plugins for Umbraco v5 (Jupiter). This post will show you how to get started with building a tree. A more in-depth example including rendering out child nodes, using many of the inbuilt helper/extension methods will come in a future blog, though in the meantime once you’ve read this post if you want to see more in-depth examples you can easily find them in our v5 source code.

Related Posts:

Disclaimer

Defining a tree

A tree in Umbraco v5 is actually an MVC Controller that returns JSON data. The first step to creating a tree is to create a class for your tree that inherits from the Umbraco base tree controller class: Umbraco.Cms.Web.Trees.TreeController

Important convention: All Tree controller names MUST be suffixed with ‘TreeController’. For example, if you are creating a tree to display system information, you might call your Tree: SystemInfoTreeController. If you don’t follow this convention, your tree controller won’t be routed.

The next step is to register this tree as a tree plugin. To do this you just need to add an attribute to your class such as:

[Tree("A18108B1-9C86-4B47-AC04-A3089FE8D3EA", "My Custom Tree")]

The two parameters passed to this attribute are:

The tree plugin ID (this MUST be unique so ensure you generated a new GUID for every single one of your plugins)
The tree title. This will be the text rendered for the root node of your tree, however, this can be overridden and you could render out any title that you wish for your root node and it could even be dynamic. Also note that we will be supporting localization for the tree title.

The next thing you’ll need to do to ensure your tree plugin is found and loaded is to ‘advertise’ that your assembly contains a tree plugin. To do this, just edit your assembly’s AssemblyInfo.cs file and add the following attribute:

//mark assembly for export as a tree plugin
[assembly: TreePluginAssembly]

[assembly: AssemblyContainsPlugins]

Creating a tree

Constructor

When inheriting from the base Umbraco.Cms.Web.Trees.TreeController, you will be required to create a constructor accepting an parameter of type: IBackOfficeRequestContext :

[Tree("A18108B1-9C86-4B47-AC04-A3089FE8D3EA", "My Custom Tree")]
public class MyTreeController : TreeController
{
    public MyTreeController(IBackOfficeRequestContext requestContext)
        : base(requestContext)
    {
    }

    //more code will go here....
    
}

The IBackOfficeRequestContext will most likely contain references to everything you’ll need to get the data for your tree. It includes references to:

Hive
Umbraco settings
The TextManager (localization framework)
All of the registered plugins in the system
… and a whole lot more

However, you’ll be please to know that all plugins including Trees can take part in IoC contructor injection. So, if you want more objects injected into your tree controller you can just add the parameters to your constructor and they’ll be injected so long as they exist in the IoC container.

Overriding methods/properties

There is one property and one method you need to override:

RootNodeId

This property is just a getter and returns the root node id for your tree. Many trees exist at the absolute root of the data which is called the SystemRoot. An example of a tree that exists at the system root would be trees like the: Data Type tree, Macro tree, Packages tree, tc… since they don’t have a heirarchy. Tree’s that have different start node Ids are trees like: Content, Media and Users. Since each one of those entities share the same data structure, we separate these data structures under different start nodes from the SystemRoot.

For the most part, if you are creating a utility type tree or a custom tree that doesn’t exist under a special hierarchy, the SystemRoot is what you’ll want:

protected override HiveEntityUri RootNodeId
{
    get { return FixedHiveIds.SystemRoot; }
}

GetTreeData

This method is the method that returns the JSON tree data though to make it easy you don’t have to worry about JSON whatsoever. All you need to do is add TreeNode objects to the existing NodeCollection of the tree controller.

As a very simple example, if you wanted to render out one node in your tree you could do this:

protected override UmbracoTreeResult GetTreeData(HiveEntityUri id, FormCollection queryStrings)
{
    NodeCollection.Add(
        CreateTreeNode(id, null, "My only node", string.Empty, false));
    return UmbracoTree();
}

The CreateTreeNode is a helper method which is part of the base TreeController class that has many useful overloads. In this example, we’re giving it an id, not passing in any custom query string parameters, a title, not giving it an editor url and tagging the node as not having any children.

Registering a tree

In order to get your tree to show up in the back office, you need to register the tree in the config file: ~/App_Data/Umbraco/Config/umbraco.cms.trees.config , and here’s all you need to do to put it in the ‘settings’ app (as an example):

<add application="settings" 
     controllerType="MyProject.MyTreeController, MyProject" />

NOTE: At CodeGarden we discussed that you can ship your plugin inside a package and have your own config file deployed which Umbraco will recognize so that you don’t have to edit the already existing file…. This is still true! But we’ll write another blog post about that

More in depth example?

As I mentioned at the start of this post I’ll write another one detailing our many extension and helper methods when rendering out trees, how to add menu items to your nodes, customize your icons, change the editor for particular nodes, etc… In the meantime though, please have a look at the v5 source code, the trees all exist in the project: Umbraco.Cms.Web.Trees