@Shazwazza

Shannon Deminick's blog all about web development

Taming the BuildManager, ASP.Net Temp files and AppDomain restarts

March 28, 2012 08:14

I’ve recently had to do a bunch of research in to the BuildManager and how it deals with caching assemblies since my involvement with creating an ASP.Net plugin engine. Many times people will attempt to restart their AppDomain by ‘bumping’ their web.config files, meaning adding a space character or carriage return and then saving it. Sometimes you may have noticed that this does not always restart your AppDomain the way you’d expect and some of the new types you’d expect to have loaded in your AppDomain simply aren’t there. This situation has cropped up a few times when using the plugin engine that we have built in to Umbraco v5 and some people have resorted to manually clearing out their ASP.Net temp files and then forcing an IIS Restart, but this is hardly ideal. The good news is that we do have control over how these assemblies get refreshed, in fact the BuildManager reloads/refreshes/clears assemblies in different ways depending on how the AppDomain is restarted.

The hash.web file

An important step during the BuildManager initialization phase is a method call to BuildManager.CheckTopLevelFilesUpToDate which does some interesting things. First it checks if a special hash value is on disk and is not zero. You may have noticed a file in your ASP.Net temp files: /hash/hash.web and it will contain a value such as: 4f34227133de5346. This value represents a unique hash of many different combined objects that the BuildManager monitors. If this file exists and the value can be parsed properly then the BuildManager will call: diskCache.RemoveOldTempFiles(); What this does is the following:

  • removes the CodeGen temp resource folder
  • removes temp files that have been saved during CodeGen such as *.cs
  • removes the special .delete files and their associated original files which have been created when shutting down the app pool and when the .dll files cannot be removed (due to file locking)

Creating the hash value

The next step is to create this hash value based on the current objects in the AppDomain. This is done using an internal utility class in the .Net Framework called: HashCodeCombiner (pretty much everything that the BuildManager references is marked Internal! ). The process combines the following object values to create the hash (I’ve added in parenthesis the actual properties the BuildManager references):

  • the app's physical path, in case it changes (HttpRuntime.AppDomainAppPathInternal)
  • System.Web.dll (typeof(HttpRuntime).Module.FullyQualifiedName)
  • machine.config file name (HttpConfigurationSystem.MachineConfigurationFilePath)
  • root web.config file name, please note that this is not your web apps web.config (HttpConfigurationSystem.RootWebConfigurationFilePath)
  • the hash of the <compilation> section (compConfig.RecompilationHash)
  • the hash of the system.web/profile section (profileSection.RecompilationHash)
  • the file encoding set in config (appConfig.Globalization.FileEncoding)
  • the <trust> config section (appConfig.Trust.Level & appConfig.Trust.OriginUrl)
  • whether profile is enabled (ProfileManager.Enabled)
  • whether we are precompiling with debug info (but who precompiles :) (PrecompilingWithDebugInfo)

Then we do a check for something I didn’t know existed called Optimize Compilations which will not actual affect the hash file value for the following if it is set to true (by default is is false):

  • the ‘bin’ folder (HttpRuntime.BinDirectoryInternal)
  • App_WebReferences (HttpRuntime.WebRefDirectoryVirtualPath)
  • App_GlobalResources  (HttpRuntime.ResourcesDirectoryVirtualPath)
  • App_Code (HttpRuntime.CodeDirectoryVirtualPath)
  • Global.asax (GlobalAsaxVirtualPath)

Refreshing the ASP.Net temp files (CodeGen files)

The last step of this process is to check if the persisted hash value in the hash.web file equals the generated hash value from the above process. If they do not match then a call is made to diskCache.RemoveAllCodegenFiles(); which will:

  • clear all codegen files, removes all files in folders but not the folders themselves,
  • removes all root level files except for temp files that are generated such as .cs files, etc...

This essentially clears your ASP.Net temp files completely, including the MVC controller cache file, etc…

Then the BuildManager simply resaves this calculated has back to the hash.web file.

What is the best way to restart your AppDomain?

There is really no ‘best’ way, it just depends on your needs. If you simply want to restart your AppDomain and not have the overhead of having your app recompile all of your views and other CodeGen classes then it’s best that you simply ‘bump’ your web.config by just adding a space, carriage return or whatever. As you can see above the hash value is not dependant on your local web.config file’s definition (timestamp, etc…). However, the hash value is dependent on some other stuff in your apps configuration such as the <compilation> section, system.web/profile section, the file encoding configured, and the <trust> section. If you update any value in any of these sections in your web.config it will force the BuildManager to clear all cached CodeGen files which is the same as clearing your ASP.Net temp files.

So long as you don’t have optimizeCompilations set to true, then the easiest way to clear your CodeGen files is to simply add a space or carriage return to your global.asax file or modify something in the 4 other places that the BuildManager checks locally: App_Code, App_GlobalResources, App_WebResources, or modify/add/remove a file in your bin folder.

How does this affect the ASP.Net plugin engine?

Firstly, i need to update that post as the code in the plugin engine has changed quite a bit but you can find the latest in the Umbraco source code on CodePlex. With the above knowledge its easy to clear out any stale plugins by perhaps bumping your global.asax file, however this is still not an ideal process. With the research I’ve done in to the BuildManager I’ve borrowed some concepts from it and learned of a special “.delete” file extension that the BuildManager looks for during AppDomain restarts. With this new info, I’ve already committed some new changes to the PluginManager so that you shouldn’t need to worry about stale plugin DLLs.

Umbraco v5 Surface Controller Forms

November 29, 2011 21:22

This post will show you how to create a form in Umbraco v5 using Surface Controllers. The information in this post assumes that you are familiar with Surface Controllers (see this previous post if not) and with creating forms in ASP.Net MVC.

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.

Create a model

The easiest way to create a form in MVC is to create a model that represents your form. This isn’t mandatory but then you’ll have to use some old school techniques like getting posted values directly from the HttpRequest object.

An example could be:

namespace MySite.Models
{
    public class MyTestModel
    {
        [Required]
        public string Name { get; set; }

        [Required]
        [Range(18,30)]
        public int Age { get; set; }        
    }
}

Create a Surface Controller

For this example we’ll assume that we’re creating a locally declared Surface Controller (not a plugin, see the previous post for full details).

Some code first and explanation after:

namespace MySite.Controllers
{   
    public class MySurfaceController : SurfaceController
    {
        [HttpPost] 
        public ActionResult HandleFormSubmit(
            [Bind(Prefix = "MyTestForm")]
            MyTestModel model)
        {
            if (!ModelState.IsValid)
            {
                return CurrentUmbracoPage();
            }            
            
            //do stuff here with the data in the model... send
            // an email, or insert into db, etc...
            
            return RedirectToUmbracoPage(
                new HiveId(
                    new Guid("00000000000000000000000000001049")));
        }
    }
}

Lets break down some parts of the above Controller code:

Namespace: Generally you’ll put your locally declared controllers in the ~/Controllers folder, the above namespace reflects this.

Class: The Surface Controller class is suffixed with the term ‘SurfaceController’. This is a required convention (as per the previous post), without that suffix, the controller will not get routed.

[Bind] attribute: In the code below you’ll see that we are creating the editor with a ‘prefix’ called ‘MyTestForm’. This ensures that each input element on the form will get its name prefixed with this value. For example:

<input type="text" name="MyTestForm.Name" />

This is a recommended practice however it is optional. If you don’t prefix your form controls then you don’t need to use the [Bind] attribute. Here’s a few reasons why this is a recommended practice:

  1. Without the prefix, If there is more than 1 form rendered on your webpage and both are using the MVC validation summary, then both validation summaries will display the errors for both forms. When there is a prefix you can tell the validation summary to only display errors for the form with the specified prefix.
  2. The MVC Html helpers will generate the html id for each element and without specifying a prefix and if you have more than 1 form rendered on your page you may end up with duplicate html element Ids.
  3. If you create a scaffolded form with a custom model object such as doing:

    @{ var someModel = new MyModel(); }
    @Html.EditorFor(x => someModel)

    then MVC will automatically prefix your input fields with ‘someModel’ . For some reason MVC does this when the model name isn’t exactly ‘Model’.

return CurrentUmbracoPage: This method is built in to the base SurfaceController class and simply returns the currently executing Umbraco page without a redirect to it which is generally what you want to do in order to display any validation errors.

return RedirectToUmbracoPage: This method is built in to the base SurfaceController class and performs a redirect to a Umbraco page given an Id which is generally what you want to do when a form submission is successful. (chances are that you wont have a page with a Guid id of 00000000000000000000000000001234…. this is just an example :)

NOTE: There is also a RedirectToCurrentUmbracoPage() method!

Rendering a form

There are a few ways to render a form:

  • Directly in your Umbraco template/view
  • Using a Partial View macro
  • Using a Child Action macro which renders a partial view

Regardless of which you use to render a form, the markup will be very similar. Similar to MVC’s @Html.BeginForm, we have an @Html.BeginUmbracoForm helper:

@{
    var formModel = new MySite.Models.MyTestModel();
}

@using(Html.BeginUmbracoForm("HandleFormSubmit", "MySurface"))
{
    @Html.ValidationSummary(prefix: "MyTestForm")
    @Html.EditorFor(x => formModel, "", "MyTestForm")
    <input type="submit"/>
}

Here’s the breakdown of the above mark-up:

Html.BeginUmbracoForm: A normal MVC form would simply use Html.BeginForm which will create an action attribute for the html form tag with a URL of your controller’s action. In Umbraco however, we want the URL to be posted to the same as the URL being rendered (post back), so the BeginUmbracoForm call handles this all for us. It will create a form tag with the URL of the currently rendered Umbraco node and add some custom hidden fields to your form containing the values of where the data will actually post to (your Surface Controller’s action). The Umbraco front-end route handler will take care of all of this for you.

The parameters passed in to BeginUmbracoForm will differ depending on if your Surface Controller is a plugin controller or a locally declared controller. In this example, its a locally declared controller so we just need to give it the action name and controller name. If its a plugin Surface Controller, you’ll need to give it the action and and the controller ID. There’s also a few overloads so that you can add additional html attributes to the rendered html form tag.

@Html.ValidationSummary: The native MVC ValidationSummary doesn’t let you target specific input tags via prefixes so we’ve created a ‘better’ one that does let you do that. In this example we’re telling the validation summary to only display errors for input values that are prefixed with “MyTestForm” which is real handy if you’re rendering a few forms on the same page and using a validation summary for each.

@Html.EditorFor: This is the native EditorFor method in MVC which lets you supply a prefix name which will be used for all of your input fields. The MVC methods for rendering individual input tags also have an overload to supply a prefix if you choose not to have it scaffold your form for you.

formModel: The above mark-up will scaffold the form for us based on the model that we created previously. This example creates an inline model object (formModel) to scaffold the form but if you had a strongly typed partial view with your model type, you could just as well use the view’s Model property.

And that’s pretty much it! Happy form making :)

Umbraco Jupiter Plugins - Part 5 - Surface Controllers

November 29, 2011 14:31

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

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.

Related Posts:

  1. Umbraco Jupiter Plugins – Part 1
  2. Umbraco Jupiter Plugins – Part 2 – Routing
  3. Umbraco Jupiter Pluings – Part 3 – Trees
  4. Umbraco Jupiter Pluings – Part 4 – Editors

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!)

Sharing Controller Actions with ControllerExtenders

October 4, 2011 14:17

Why?

If you wanted to be able to share Actions between controllers in .Net there is currently no official way to do it and that is probably because it might not be something that people have thought about doing very often before. Though once I started thinking about it I realized that this concept could be used for a variety of different purposes and that other people might potentially think of whole new ways to apply this concept. Here’s a couple use cases:

  • Separating logic out of large controllers
  • Ability to distribute Controllers in DLLs whose Actions that could then be consumed by other people’s Controllers
  • Support for a ‘Multiple inheritance’ class structure

Again I think that there is some potential here for people to run with this concept in their own ways. Its probably not a concept that everyone will want/need to use, but you should know that it definitely can be done, and here’s how…

ControllerExtender

In order to extend your Controller with actions from another Controller, you’ll need to register your extension with a new class called ControllerExtender. There’s a couple of ways to go about doing this, the nicest way is to use attributes on your Controller:

[ExtendedBy(typeof(TestExtenderController))]
public class ContentEditorController : Controller
{....}

Otherwise there’s a few overloads on the ControllerExtender class to directly do this:

//Where 'this' is the controller you are extending, generally called in the 
//constructor of your controller
ControllerExtender.RegisterExtender(this, typeof (TestExtenderController));

//Where 'this' is the controller you are extending, generally called in the 
//constructor of your controller
ControllerExtender.RegisterExtender<TestExtenderController>(this);

//This registration could be created in your global.asax 
ControllerExtender.RegisterExtender<ContentEditorController, TestExtenderController>();

One important thing to note is that the ControllerExtender uses the DependencyResolver to create an instance of the extending controller class so you’ll need to ensure that your controllers are registered properly in IoC.

Illegal Extenders

The ControllerExtender will not let you extend a controller by it’s same type of it’s same sub type. Also, nested extenders do not work (though the code could be modified to support this) therefore you cannot have Controller ‘A’ be extended by Controller ‘B’ which is extended by Controller ‘C’. In this scenario when rendering actions on Controller ‘A’, only actions on Controller ‘A’ and ‘B’ will be resolved. When rendering actions on Controller ‘B’ only actions on Controller ‘B’ and ‘C’ will be resolved.

Multiple Extenders

You can register multiple extenders for one Controller but because multiple extenders may have the same Action name/signature, only the first one that is found that is a match is used. It is therefor up to the developer to make sure they are aware of this.

Custom IActionInvoker

In order to facilitate the sharing of Actions a custom IActionInvoker of type ControllerExtenderActionInvoker needs to be registered on your controller. This is easy to do in the constructor of your controller:

public MyController()
{
    this.ActionInvoker = new ControllerExtenderActionInvoker();
}

Source Code

The source code for all of this is pretty straight forward and boils down to 3 classes:

  • The static ControllerExtender class
  • The custom ControllerExtenderActionInvoker
  • The ExtendedByAttribute

ControllerExtenderActionInvoker class

This class is responsible for finding and invoking the correct Action on a controller which takes into account any of the extenders registered for the currently executing Controller.

The most up to date code can be found in the Umbraco 5 source code HERE.

ControllerExtender class

This class is responsible for maintaining the extender registrations, it allows for creating registrations and returning registrations:

public static class ControllerExtender
{

    /// <summary>
    /// Internal ConcurrentDictionary to store all registrations
    /// </summary>
    private static readonly ConcurrentDictionary<Tuple<Type, Type>, Func<ControllerBase>> 
        Registrations
            = new ConcurrentDictionary<Tuple<Type, Type>, Func<ControllerBase>>();

    /// <summary>
    /// Registers the extender.
    /// </summary>
    /// <typeparam name="TController">The type of the controller.</typeparam>
    /// <typeparam name="TExtender">The type of the extender.</typeparam>
    public static void RegisterExtender<TController, TExtender>()
        where TController : ControllerBase
        where TExtender : ControllerBase
    {
        var t = new Tuple<Type, Type>(typeof(TController), typeof(TExtender));
        if (Registrations.ContainsKey(t))
            return;

        if (typeof(TExtender).IsAssignableFrom(typeof(TController)))
        {
            throw new InvalidOperationException
                ("Cannot extend a controller by it's same type");
        }

        Registrations.TryAdd(t, () => DependencyResolver.Current.GetService<TExtender>());
    }

    /// <summary>
    /// Registers the extender.
    /// </summary>
    /// <typeparam name="T"></typeparam>
    /// <param name="controllerToExtend">The controller to extend.</param>
    public static void RegisterExtender<T>(
        ControllerBase controllerToExtend)
        where T : ControllerBase
    {
        RegisterExtender(controllerToExtend, () => DependencyResolver.Current.GetService<T>());
    }

    /// <summary>
    /// Registers the extender.
    /// </summary>
    /// <param name="controllerToExtend">The controller to extend.</param>
    /// <param name="controllerExtender">The controller extender.</param>
    public static void RegisterExtender(
        ControllerBase controllerToExtend, 
        Type controllerExtender)
    {
        var t = new Tuple<Type, Type>(controllerToExtend.GetType(), controllerExtender);
        if (Registrations.ContainsKey(t))
            return;

        if (controllerExtender.IsAssignableFrom(controllerToExtend.GetType()))
        {
            throw new InvalidOperationException
                ("Cannot extend a controller by it's same type");
        }

        Registrations.TryAdd(t, 
            () => DependencyResolver.Current.GetService(controllerExtender) as ControllerBase);
    }

    /// <summary>
    /// Registers the extender.
    /// </summary>
    /// <typeparam name="T"></typeparam>
    /// <param name="controllerToExtend">The controller to extend.</param>
    /// <param name="extender">The extender.</param>
    public static void RegisterExtender<T>(
        ControllerBase controllerToExtend, 
        Expression<Func<T>> extender)
        where T : ControllerBase
    {
        var extenderType = typeof(T);
        var t = new Tuple<Type, Type>(controllerToExtend.GetType(), extenderType);
        if (Registrations.ContainsKey(t))
            return;

        if (extender.GetType().IsAssignableFrom(controllerToExtend.GetType()))
        {
            throw new InvalidOperationException
                ("Cannot extend a controller by it's same type");
        }

        Registrations.TryAdd(t, extender.Compile());
    }

    /// <summary>
    /// Returns all registrations as a readonly collection
    /// </summary>
    /// <returns></returns>
    public static IEnumerable<KeyValuePair<Tuple<Type, Type>, Func<ControllerBase>>> 
        GetRegistrations()
    {
        return Registrations;
    }

}

ExtendedByAttribute class

This Attribute is used by the ControllerExtenderActionInvoker to created Extender registrations dynamically.

[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
public class ExtendedByAttribute : Attribute
{
    public Type ControllerExtenderType { get; private set; }

    public ExtendedByAttribute(Type controllerExtenderType)
    {
        if (!typeof(ControllerBase).IsAssignableFrom(controllerExtenderType))
        {
            throw new ArgumentException
                ("controllerExtenderType must be of type Controller");
        }
        ControllerExtenderType = controllerExtenderType;       
    }
}

Umbraco Jupiter Plugins - Part 4 - Editors

September 27, 2011 07:56

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:

  1. Umbraco Jupiter Plugins – Part 1
  2. Umbraco Jupiter Plugins – Part 2 – Routing
  3. Umbraco Jupiter Pluings – Part 3 – Trees

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.

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.

Sharing views between specific controllers

July 21, 2011 03:29

There’s no native way in MVC to share views between controllers without having to put those views in the ‘Shared’ folder which can be annoying especially if you have an inherited controller class structure, or your simply wish to just have one particular controller look for views in the folder of a different controller.

With a little help from DotPeek to see what’s going on inside of the VirtualPathProviderViewEngine, I’ve created a fairly elegant solution to the above problem which consists of a custom ViewEngine and a custom controller Attribute. Lets start with the custom Attribute, its really simple and only contains one property which is the name of the controller that you wish the attributed controller to reference views.  An example:

[AlternateViewEnginePath("ContentEditor")]
public class MediaEditorController : Controller
{  ...  }

The example above is saying that we have a MediaEditor controller that should reference views in the ContentEditor controller’s view folder, pretty simple right! A cool part about how the underlying ViewEngine works is that if a view isn’t found in the ContentEditor controller’s folder, then it will check back to the current controller’s folder, so it has built in fall back support.

The custom ViewEngine is actually pretty simple as well once you know what’s going on inside of the VirtualPathProviderViewEngine. There’s two particular methods: FindView and FindPartialView which the VirtualPathProviderViewEngine figures out which controller/folder to look in. It figures this out by looking at the current ControllerContext’s RouteValues and simply does a lookup of the controller name by using this statement:

controllerContext.RouteData.GetRequiredString("controller");

So all we’ve got to do is override the FindView and FindPartialView methods, create a custom ControllerContext with the “controller” route value to be the value specified in our custom attribute, and then pass this custom ControllerContext into the underlying base FindView/FindPartial view methods:

/// <summary>
/// A ViewEngine that allows a controller's views to be shared with other 
/// controllers without having to put these shared views in the 'Shared' folder.
/// This is useful for when you have inherited controllers.
/// </summary>
public class AlternateLocationViewEngine : RazorViewEngine
{
    public override ViewEngineResult FindPartialView(
        ControllerContext controllerContext, 
        string partialViewName, 
        bool useCache)
    {
        var altContext = GetAlternateControllerContext(controllerContext);
        if (altContext != null)
        {
            //see if we can get the view with the alternate controller 
            //specified, if its found return the result, if its not found
            //then return the normal results which will try to find 
            //the view based on the 'real' controllers name.
            var result = base.FindPartialView(altContext, partialViewName,useCache);
            if (result.View != null)
            {
                return result;
            }
        }
        return base.FindPartialView(controllerContext, partialViewName,useCache);
    }

    public override ViewEngineResult FindView(
        ControllerContext controllerContext, 
        string viewName, 
        string masterName, 
        bool useCache)
    {
        var altContext = GetAlternateControllerContext(controllerContext);
        if (altContext!= null)
        {
            var result = base.FindView(altContext, viewName, masterName, useCache);
            if (result.View != null)
            {
                return result;
            }
        }
        return base.FindView(controllerContext, viewName, masterName, useCache);
    }

    /// <summary>
    /// Returns a new controller context with the alternate controller name in the route values
    /// if the current controller is found to contain an AlternateViewEnginePathAttribute.
    /// </summary>
    /// <param name="currentContext"></param>
    /// <returns></returns>
    private static ControllerContext GetAlternateControllerContext(
        ControllerContext currentContext)
    {
        var controller = currentContext.Controller;
        var altControllerAttribute = controller.GetType()
            .GetCustomAttributes(typeof(AlternateViewEnginePathAttribute), false)
            .OfType<AlternateViewEnginePathAttribute>()
            .ToList();
        if (altControllerAttribute.Any())
        {
            var altController = altControllerAttribute.Single().AlternateControllerName;
            //we're basically cloning the original route data here...
            var newRouteData = new RouteData
                {
                    Route = currentContext.RouteData.Route,
                    RouteHandler = currentContext.RouteData.RouteHandler
                };
            currentContext.RouteData.DataTokens
                .ForEach(x => newRouteData.DataTokens.Add(x.Key, x.Value));
            currentContext.RouteData.Values
                .ForEach(x => newRouteData.Values.Add(x.Key, x.Value));

            //now, update the new route data with the new alternate controller name
            newRouteData.Values["controller"] = altController;

            //now create a new controller context to pass to the view engine
            var newContext = new ControllerContext(
                currentContext.HttpContext, 
                newRouteData, 
                currentContext.Controller);
            return newContext;
        }

        return null;
    }
}

/// <summary>
/// An attribute for a controller that specifies that the ViewEngine 
/// should look for views for this controller using a different controllers name.
/// This is useful if you want to share views between specific controllers 
/// but don't want to have to put all of the views into the Shared folder.
/// </summary>
public class AlternateViewEnginePathAttribute : Attribute
{
    public string AlternateControllerName { get; set; }

    public AlternateViewEnginePathAttribute(string altControllerName)
    {
        AlternateControllerName = altControllerName;
    }
}
Lastly, you’ll need to just register this additional ViewEngine in your global.asax, or IoC, or however you are doing that sort of thing in your application.

Umbraco Jupiter Plugins - Part 2 - Routing

May 11, 2011 10:26

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

Related Posts:

  1. 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 :)

Umbraco Jupiter Plugins - Part 1

April 29, 2011 11:55

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

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.

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

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 :)

HtmlHelper Table methods

April 22, 2011 11:29

I was hoping that these were built already but couldn’t see any descent results with a quick Google search so figured I’d just write my own… these are now part of the Umbraco v5 codebase. Here’s 2 HtmlHelper methods that allow you to very quickly create an Html table output based on an IEnumerable data structure. Luckily for us, Phil Haack showed us what Templated Razor Delegates are which makes stuff like this very elegant.

There are 2 types of tables: a table that expands vertically (you set a maximum number of columns), or a table that expands horizontally (you set a maximum amount of rows). So I’ve created 2 HtmlHelper extensions for this:

Html.TableHorizontal Html.TableVertical

Say you have a partial view with a declaration of something like:

@model IEnumerable<MyDataObject>

To render a table is just one call and you can customize exactly how each cell is rendered and styled using Razor delegates, in the following example the MyDataObject class contains 3 properties: Name, Enabled and Icon and each cell is going to render a check box with a CSS image as it’s label and there will be a maximum of 8 columns:

@Html.TableVertical(Model, 8, @<text> @Html.CheckBox(@item.Name, @item.Enabled) <label for="@Html.Id(@item.Name)" class="@item.Icon"> <span>@item.Name</span> </label> </text>)

Nice! that’s it, far too easy. One thing to note is the @<text> </text> syntax as this is special Razor parser syntax that declares a Razor delegate without having to render additional html structures. Generally Razor delegates will require some Html tags such as this: @<div> </div> but if you don’t require surrounding Html structures, you can use the special @<text> </text> tags.

Lastly here’s all the HtmlHelper code… I’ve created these extensions as HtmlHelper extensions only for consistency but as you’ll be able to see, the HtmlHelper is never actually used and these extensions could simply be extensions of IEnumerable<T>.

/// <summary> /// Creates an Html table based on the collection /// which has a maximum numer of rows (expands horizontally) /// </summary> public static HelperResult TableHorizontal<T>(this HtmlHelper html, IEnumerable<T> collection, int maxRows, Func<T, HelperResult> template) where T : class { return new HelperResult(writer => { var items = collection.ToArray(); var itemCount = items.Count(); var maxCols = Convert.ToInt32(Math.Ceiling(items.Count() / Convert.ToDecimal(maxRows))); //construct a grid first var grid = new T[maxCols, maxRows]; var current = 0; for (var x = 0; x < maxCols; x++) for (var y = 0; y < maxRows; y++) if (current < itemCount) grid[x, y] = items[current++]; WriteTable(grid, writer, maxRows, maxCols, template); }); } /// <summary> /// Creates an Html table based on the collection /// which has a maximum number of cols (expands vertically) /// </summary> public static HelperResult TableVertical<T>(this HtmlHelper html, IEnumerable<T> collection, int maxCols, Func<T, HelperResult> template) where T : class { return new HelperResult(writer => { var items = collection.ToArray(); var itemCount = items.Count(); var maxRows = Convert.ToInt32(Math.Ceiling(items.Count() / Convert.ToDecimal(maxCols))); //construct a grid first var grid = new T[maxCols, maxRows]; var current = 0; for (var y = 0; y < maxRows; y++) for (var x = 0; x < maxCols; x++) if (current < itemCount) grid[x, y] = items[current++]; WriteTable(grid, writer, maxRows, maxCols, template); }); } /// <summary> /// Writes the table markup to the writer based on the item /// input and the pre-determined grid of items /// </summary> private static void WriteTable<T>(T[,] grid, TextWriter writer, int maxRows, int maxCols, Func<T, HelperResult> template) where T : class { //create a table based on the grid writer.Write("<table>"); for (var y = 0; y < maxRows; y++) { writer.Write("<tr>"); for (var x = 0; x < maxCols; x++) { writer.Write("<td>"); var item = grid[x, y]; if (item != null) { //if there's an item at that grid location, call its template template(item).WriteTo(writer); } writer.Write("</td>"); } writer.Write("</tr>"); } writer.Write("</table>"); }

Binding a custom property with model binders

January 19, 2011 01:00
This post was imported from FARMCode.org which has been discontinued. These posts now exist here as an archive. They may contain broken links and images.
In ASP.Net MVC Model Binders are great but what if you have a property on your model that is a ‘Simple’ type that you want to assign to a custom model binder? Take the following class for example:
public class MyModel { [Required] public string Name { get; set; } [Required] public DateTime StartDate { get; set; } [Required] public DateTime StartTime { get; set; } [CustomValidation(typeof(CreateJourneyModel), "OnDateValidate")] public DateTime FullStartDateTime { get; set; } //Custom validation logic which needs to validate the full date/time internal static ValidationResult OnDateValidate(DateTime dt, ValidationContext validationContext) { return dt < DateTime.Now.AddHours(1) ? new ValidationResult("Enter a date/time greater than 3 hours from now") : ValidationResult.Success; } }

The above model will allow us to have a different date and time field rendered for input on a form but requires the combined date/time to run custom validation against. You might already be thinking: Isn’t this the same problem that Scott Hanselman solved in this post? Well, sort of but not really. What Scott did was assign a custom model binder to all instances of DateTime or set specifically on an Action parameter and was also splitting one DateTime field into 2 on the front-end . I’m not really a fan of having a custom model binder for all instances of DateTime in my application , I don’t have a DateTime parameter in my Action to explicitly assign a model binder too and I also decided to use 2 DateTime properties to represent 2 different fields on my form.  The solution presented below could allow you to custom bind any single property of your model which you could then assign custom validation to.

First, we need to put the fields on your form so they get posted back to the server. Using the Html.EditorFor(x => …..) syntax is the way to go, however, for the field we want to custom bind using Html.HiddenFor(x => …. ) is better so the field isn’t actually displayed on the form. This will add this field name to the ValueProvider when it’s posted to the server.

Next, create the model binder. Since we cannot assign a model binder to a property of a model, we need to make the binder for the model containing the property. And, since we don’t want to do any custom binding for the rest of the properties, we’ll just inherit from DefaultModelBinder and let it do the work for us. The only thing we have to do is override GetPropertyValue , check for the property that we want to custom bind and bind it!

public class MyCustomModelBinder : DefaultModelBinder { protected override object GetPropertyValue(ControllerContext controllerContext, ModelBindingContext bindingContext, System.ComponentModel.PropertyDescriptor propertyDescriptor, IModelBinder propertyBinder) { //check if it the 'FullStartDateTime' property if (propertyDescriptor.Name == "FullStartDateTime") { //try to get the date part var dateValue = bindingContext.ValueProvider.GetValue("StartDate"); DateTime date; if (!string.IsNullOrEmpty(dateValue.AttemptedValue) && DateTime.TryParseExact(dateValue.AttemptedValue, "dd/MM/yyyy", CultureInfo.InvariantCulture, DateTimeStyles.None, out date)) { //try to get the time part var timeValue = bindingContext.ValueProvider.GetValue("StartTime"); DateTime time; if (!string.IsNullOrEmpty(timeValue.AttemptedValue) && DateTime.TryParseExact(timeValue.AttemptedValue, "HH:mm", CultureInfo.InvariantCulture, DateTimeStyles.None, out time)) { //we've got both parts, join them together var fullDateTime = new DateTime(date.Year, date.Month, date.Day, time.Hour, time.Minute, time.Second); return fullDateTime; } } //could not bind return null; } //let the default model binder do it's thing return base.GetPropertyValue(controllerContext, bindingContext, propertyDescriptor, propertyBinder); } }

Last, all we need to do is assign the custom model binder to the custom model which can easily be done by just attributing the model:

[ModelBinder(typeof(MyCustomModelBinder))] public class MyModel {...}

That's it! Now all validation is handled as per normal on the custom property.