James Jackson-South

Context based property mapping with UmbMapper

Mon, 21 Aug 2017 10:15:26 Z

Mo Mapping, Mo Problems

A few weeks ago I wrote an article about my new Umbraco mapping engine UmbMapper. If you haven't read that post please do, and better yet, please download it and give it a try.

There's been a longstanding puzzle I've been trying to solve for a while now with mapping engines. One that I couldn't crack with Ditto and until today I didn't think I could solve it with UmbMapper.

I was wrong :)

The Problem

Consider the following POCO class.

public class Page {

    public string Name { get; set; }

    public string Slug => this.Name.ToUrlSegment();
}

Mapping this kind of class is impossible with conventional reflection-based run-time mappers as there is no way to guarantee that the Name property has a value. You'll get a NullReferenceException and a whole heap of frustration.

You can workaround this with Umbraco but it's not pretty. You could either

Turn Slug into a method which works but makes it impossible to serialize.
Create an event handler to calculate and store the property when saving the doctype. This is oh-so-ugly and means spreading logic all over the place.

The Solution

With UmbMapper you can map these properties in the following manner.

First let's define our class.

public class Page {

    public string Name { get; set; }

    public string Slug { get; set; }
}

And our mapper.

public class PageMap : MapperConfig<Page>
{
    public PageMap()
    {
        this.AddMap(p => p.Name);
        this.AddMap(p => p.Slug).MapFromInstance(i => i.Name.ToUrlSlug());
    }
}

The MapFromInstance method is our friend here. This has the following signature.

/// <summary>
/// Sets the property mapping predicate. Used for mapping from known values in the current instance.
/// </summary>
/// <param name="predicate">The mapping predicate</param>
/// <returns>The <see cref="PropertyMap{T}"/></returns>
public PropertyMap<T> MapFromInstance(Func<T, object> predicate)

With this method we can map any combination of lazy/non-lazy properties at run-time and be guaranteed the correct result and we keep our mapping logic where it belongs.

Fantastic!

Get it While it's Hot!

Give UmbMapper a whirl, it's simple to use but immensely powerful giving you the means to create flexible, scalable Umbraco websites with very little effort.

Strong Typed Umbraco Mapping with UmbMapper

Sun, 13 Aug 2017 20:02:23 Z

Greetings and Salutations!

It's not often I write code I'm immediately happy with and proud of but this happened to me just recently so I thought I'd share it with the community.

As I'm sure you know, dear reader, I'm a big fan of a pretty sweet CMS made by some fantastic friends of mine in Denmark called Umbraco. If you haven't played around with it, please do, it stands out, in my opinion, as easily the most usable, flexible, and fun to work with CMS in the NET ecosystem by a country mile.

I'm always looking for inventive ways to work with it and to make it even easier for others to do so as well so when I had a flash of inspiration lying, flu-ridden on my couch I had to pop a couple of pills, crank open the laptop, and furiously tap away to produce what I'm sharing.

A Little History

I've been writing mapping code for Umbraco for a few years now with two of the big guns in the Umbraco package scene, Lee and Matt. You might have heard of the package we produced together called Ditto

I'm proud of what we achieved with Ditto. I think we've managed to push attribute based mapping about as far as it can go, crafting a very performant, very flexible system that has served me well (and I think many others) over the years.

I even wrote an article about it a couple of years ago in the fantastic Skrift magazine.

As my skill-set has grown though and my tastes have changed I have found myself curious about how far and fast I can push mapping.

Introducing UmbMapper

Not the most exciting name ever but definitely some of the most exciting code I've come up with.

UmbMapper is a new, convention-based mapper that I've written for mapping IPublishedContent to strong-typed POCO classes. Strong-typed? Let's quote my own words from a couple of years ago.

Opens dictionary… Strong typing involves the strict enforcement of type rules with no exceptions, allowing the detection of incorrect type usage either at run time or at compile time. Having strong typing catches more type errors than weak typing, resulting in fewer hard errors. It can cut down on many hours of painful debugging.

Umbraco offers what I would call "Stringly Typing". You can get your property type out of the API but you have to pass a string in order to do so. That’s pretty damn cool but it doesn’t quite feel natural and easy enough for me to use as a developer. I’m lazy and the last thing I want to do it type lots and learn how to spell things.

Clued up? Great, let's carry on.

The Elevator Pitch

Why use it? Well, let me explain.

UmbMapper works in a completely different way to Ditto and ModelsBuilder. It uses the concept of convention-based mapping configuration classes to do the work for you which allows you to perform fine-grained mapping with very little overhead.

I want my POCO's to be super lean and you should too. Imagine getting to write code like this in your Umbraco project to represent your document types.

public class PublishedItem
{
    public int Id { get; set; }

    public string Name { get; set; }

    public DateTime CreateDate { get; set; }

    public DateTime UpdateDate { get; set; }

    public MyEnum MyEnumType{ get; set; }

    public Image Image { get; set; }

    public RelatedLink Link { get; set; }
}

Ain't that pretty? No attributes, no inheriting of particular interfaces, nothing but pure, good old fashioned POCO goodness! This makes it great for larger projects (As well as small ones) where you can apply design patterns like DDD to maintain flexibility and help your application scale.

So how do we map it? Here's where the magic happens.

public class PublishedItemMap : MapperConfig<PublishedItem>
{
    public PublishedItemMap()
    {
        this.AddMap(p => p.Id);
        this.AddMap(p => p.Name);
        this.AddMap(p => p.CreateDate);
        this.AddMap(p => p.UpdateDate).SetAlias(p => p.UpdateDate, p => p.CreateDate);
        this.AddMap(p => p.MyEnumType).SetMapper<EnumPropertyMapper>();
        this.AddMap(p => p.Image).SetMapper<UmbracoPickerPropertyMapper>();
        this.AddMap(p => p.Link);
    }
}

Look at that API!! How crisp, how clean, how marvellous! But wait... It gets better.

For simpler classes, there are more terse mapping methods available

public class PublishedItemMap : MapperConfig<PublishedItem>
{
    public PublishedItemMap()
    {
        this.AddMappings(
            x => x.Id,
            x => x.Name,
            x => x.DocumentTypeAlias,
            x => x.Level).ForEachIndexed((x, i) => x.AsLazy());

        this.AddMappings(
            x => x.SortOrder,
            x => x.CreateDate,
            x => x.UpdateDate).ForEach(x => x.AsLazy());
    }
}

Or for really, really simple classes

public class LazyPublishedItemMap : MapperConfig<LazyPublishedItem>
{
    public LazyPublishedItemMap()
    {
        this.MapAll().ForEachIndexed((x, i) => x.AsLazy());

        this.MapAll().ForEach(x => x.AsLazy());
    }
}

Registering a mapper is as easy as follows

MapperConfigRegistry.AddMapper(new LazyPublishedItemMap());

Now that's what I call a nice API; super simple to use but powerful with a multitude of other mapping instructions available.

Configuration

The AddMap() method and subsequent methods called in the mapper constructor each return a PropertyMap<T> where T is the class you want to map to. This allows us to use a simple fluent API to configure each property map.

The various mapping configuration options are as follows:

AddMap() Instructs the mapper to map the property.
AddMappings() Instructs the mapper to map the collection of properties.
MapAll() Instructs the mapper to map all the properties in the class.
SetAlias() Instructs the mapper what aliases to look for in the document type. The order given is the checking order. Case-insensitive.
SetMapper() Instructs the mapper what specific IPropertyMapper implementation to use for mapping the property. All properties are initially automatically mapped using the UmbracoPickerPropertyMapper.
SetCulture() Instructs the mapper what culture to use when mapping values. Defaults to the current culture contained within the UmbracoContext.
AsRecursive() Instructs the mapper to recursively traverse up the document tree looking for a value to map.
AsLazy() Instructs the mapper to map the property lazily using dynamic proxy generation. You need to mark your property with the virtual keyword for that to work.

Available IPropertyMapperimplementations all inherit from the PropertyMapperBase class and are as follows:

UmbracoPickerPropertyMapper The default mapper. Maps directly from Umbraco's Published Content Cache via GetPropertyValue. Runs automatically.
EnumPropertyMapper Maps to enum values. Can handle both integer and string values.
UmbracoPickerPropertyMapper Maps from all the Umbraco built-in pickers.
DocTypeFactoryPropertyMapper Allows mapping from mixed IPublishedContent sources like Nested Content. Inherits FactoryPropertyMapperBase.

These mappers handle most use cases since they rely initially on Umbraco's PropertyValueConverter API. Additional mappers can be easily created by inheriting the PropertyMapperBase class which give you all the properties you need.

I've already built you mappers for Archetype and NuPickers though so you don't need to worry about those :)

In Summary

I'm hoping by now you can see how beneficial UmbMapper can be in your projects. It's fast, easy to use and should help you build flexible, scalable Umbraco websites giving you the freedom to spend less time boiler-plating and more time concentrating on the fun stuff.

Please visit the Github repo and download the packages from Nuget and if you have any questions, just holler and I'll do my best to help you out.

Thanks for reading!

Update

I was asked by my good friend Mads on Twitter to elaborate on how lazy mapping works so I thought I best do so.

Any sufficiently advanced technology is indistinguishable from magic. - Gandalf the Grey

If a mapper is configured using the AsLazy() instruction and the class contains properties using the virtual keyword, the mapper will generate a dynamic proxy class at run-time to represent the type we are mapping to. This class actually inherits our target class and you'll be able to see it by attaching a debugger.

The class looks something like this:

public class LazyPublishedItemProxy : LazyPublishedItem, IProxy
{
    /// <summary>
    /// Gets or sets the <see cref="IInterceptor"/> for intercepting 
    /// <see cref="System.Reflection.MethodBase"/> calls.
    /// </summary>
    IInterceptor Interceptor { get; set; }

    // Property interceptors are written below using Reflection.Emit
}

Any properties configured with lazy mapping are not actually mapped until you specifically call the getter on the property. (Via means of MethodInfo interception using the terribly complicated Reflection.Emit API).

This means that we can map large collections with very little overhead. MEGAWHOOP!

It was really interesting code to write so I encourage you to look through the source to see how it was all put together, it's very similar to how Entity Framework used to lazy map navigation properties.

When to use it?

I recommend using this when mapping any pickers or anything that requires significant work when mapped via the Property Value Converter API. You'll most likely be able to use it on all properties but I would always load test any large sites to strike the right performance balance.

Fun with UmbracoVirtualNodeRouteHandler

Wed, 13 May 2015 05:37:56 Z

This morning I answered a question on Our Umbraco regarding the best approach to provide a url allowing deep links for virtual nodes in Umbraco. In my answer I demonstrated how to use UmbracoVirtualNodeRouteHandler as a means of telling Umbraco what node to pass as my RenderModel.

Shannon talks about the UmbracoVirtualNodeRouteHandler with custom routing on his blog

I thought I'd expand on some of the functionality available to the developer by documenting a trick I use with implementations of UmbracoVirtualNodeRouteHandler to provide custom routing.

Use Case

Quite often I find myself reusing a single document type with multiple templates; I'm sure you have also. Most commonly a LoginRegisterPage or similar.

Now I don't know about you but one of the things I miss when using Umbraco is the ability to use Url.Action to generate urls for my content. I like routing in MVC and I think it's important, especially with the type of page as above to be able to generate the correct urls from within your views or controllers.

To understand what I am going to do here you first need to understand how routing works in Umbraco.

If you have the DocumentType LoginRegisterPage with the assigned template LoginPage this will map to a RenderMvcController called LoginRegisterPageController with an ActionResult LoginPage. This behaviour is standardised and predictable so we can utilise it.

DocumentType == Controller
Template == ActionResult

Example

So let's start by creating some routes.

// Custom routing for the membership pages so we can use
// proper redirects. 
RouteTable.Routes.MapUmbracoRoute(
"LoginPage",
"Login/",
new
{
    controller = "LoginRegisterPage",
    action = "LoginPage"
},
new LoginRegisterPageNodeRouteHandler());

RouteTable.Routes.MapUmbracoRoute(
"RegisterPage",
"Register/",
new
{
    controller = "LoginRegisterPage",
    action = "RegisterPage"
},
new LoginRegisterPageNodeRouteHandler());

Here I have created two routes that map to the relative urls /Login and /Register. They both map to the same controller but since two different templates are used it will map to two different ActionResult methods.

Note: I didn't use the word "virtual" in my handler names since I am mapping to actual nodes.

From here I will create a class that takes advantage of the predictability.

/// <summary>
/// An Umbraco route handler that allows the retrieval of the template alias name from the route action. 
/// </summary>
public abstract class TemplatedUmbracoVirtualNodeRouteHandler : UmbracoVirtualNodeRouteHandler
{
    /// <summary>
    /// Get the template from the current route.
    /// </summary>
    /// <param name="requestContext">
    /// The <see cref="RequestContext"/> containing information about the current HTTP request and route. 
    /// </param>
    /// <returns>
    /// The <see cref="string"/> representing the template alias.
    /// </returns>
    protected virtual string GetTemplateAlias(RequestContext requestContext)
    {
        return requestContext.RouteData.GetRequiredString("action");
    }
}

This class adds an additional method GetTemplateAlias to our handler pulling in the RouteData action variable which we know matches the template name of the node we want in the content tree.

And from here we can implement this our handler.

/// <summary>
/// The generic login/register page node route handler.
/// </summary>
public class LoginRegisterPageNodeRouteHandler : TemplatedUmbracoVirtualNodeRouteHandler
{
    /// <summary>
    /// returns the <see cref="IPublishedContent"/> associated with the route.
    /// </summary>
    /// <param name="requestContext">
    /// The request context.
    /// </param>
    /// <param name="umbracoContext">
    /// The umbraco context.
    /// </param>
    /// <returns>
    /// The <see cref="IPublishedContent"/>.
    /// </returns>
    protected override IPublishedContent FindContent(RequestContext requestContext, UmbracoContext umbracoContext)
    {
        UmbracoHelper helper = new UmbracoHelper(umbracoContext);
        string alias = typeof(LoginRegisterPage).Name;
        string templateAlias = this.GetTemplateAlias(requestContext);

        return helper.TypedContentAtRoot()
            .First()
            .Descendants()
            .First(d => d.DocumentTypeAlias.InvariantEquals(alias)
                     && d.GetTemplateAlias().InvariantEquals(templateAlias));
    }
}

Note: I use Ditto to create strong-typed models for my back office content. It's ace, you should give it a go!

If you look at the code in my handler you will see that I am searching the content for nodes that match both the name and template of the one I want.

It's as simple as that really... I can now use Url.Action("LoginPage", "LoginRegisterPage") and Url.Action("RegisterPage", "LoginRegisterPage") throughout my code to provide the correct urls to my respective pages priding me with functionality I sorely missed.

Experiments with Umbraco's IContentService

Wed, 25 Mar 2015 10:59:31 Z

I haven't had very much experience with the Umbraco ContentService. I've only just started playing around with it so if I've missed something obvious please tell me in the comments.

A Confusing API

Reading through the documentation, it seems a shade basic considering the importance of the subject matter and really doesn't go out of it's way to explain what to do and what will happen.

When saving an item using the content service, the methods signature for the first overload available for setting a property value is as follows.

IContentBase.SetValue(string propertyAlias, object value);

According to the documentation you should be able to set different types as the second argument. At time of writing they give the following example:

// Given a `ContentService` object get Content by its Id, set a few values
// and saves the Content through the `ContentService`
var content = contentService.GetById(1234);
content.SetValue("bodyText", "This text will be added to by RTE field");
content.SetValue("date", DateTime.Now);
contentService.Save(content);

Note the DateTime.Now instance there. Unfortunately support for the different types seems extremely limited. Passing a float causes the following exception.

The best overloaded method match for 'Umbraco.Core.Models.ContentBase.SetPropertyValue(string, string)' has some invalid arguments.

Yowza! That really doesn't give a great developer experience.

Magic Strings

Not much in Umbraco when dealing with content is strong-typed. If I were to hazard a guess as to why, ~~I would imagine it was because the code tooling to do some of the conversion functionality we can now was not available when the API's were designed.~~ (Update Turns out it was just a design decision). I have, however, felt the distinct impression at times through conversation that strong-typing is not wanted in certain areas.

I'm doing my best to provide it to developers when dealing with the cached IPublishedContent methods by contributing to Ditto. Content services, however, are not part of the scope for that project so having spent so much time developing with Umbraco in a strong-typed manner, coming across them here was a bit of a shock.

Let's look at that method again.

IContentBase.SetValue(string propertyAlias, object value);

The first parameter accepts a string. Now I don't know about you but the most common use case I would imagine for the method would be uploading a form or importing content through another service.

That form or service would contain classes with properties and using the API in this format would require the developer to insert magic strings for every property or use reflection to loop through with the property info name manipulating them for each instance.

Not code I want to write...

Expression Trees to the Rescue!

I wanted a way that I could call the method in the following format and not have to write those pesky strings:

IContentBase.SetValue(() => Class.Property);

In order to do that I will need to create an extension method that uses an Expression Tree. This is done by creating a Lambda Expression to represent the property.

Once inside our method we check to see whether, a property is being passed, and if so, coerce the various property values to call the old method with sanitized values.

/// <summary>
/// Sets the value of an <see cref="IContentBase"/> property to the given value.
/// </summary>
/// <param name="contentBase">
/// The <see cref="IContentBase"/>.
/// </param>
/// <param name="propertyLambda">
/// The <see cref="Expression"/> designating the value to save.
/// </param>
/// <typeparam name="T">
/// The <see cref="Type"/> of the property value.
/// </typeparam>
/// <exception cref="ArgumentException">
/// Thrown if the given <see cref="Expression"/> is not in the correct form.
/// </exception>
public static void SetValue<T>(this IContentBase contentBase, Expression<Func<T>> propertyLambda)
{
    MemberExpression expression = propertyLambda.Body as MemberExpression;

    if (expression == null)
    {
        throw new ArgumentException("You must pass a lambda of the form: '() => Class.Property' or '() => object.Property'");
    }

    PropertyInfo property = expression.Member as PropertyInfo;
    if (property != null)
    {
        MemberExpression member = (MemberExpression)expression.Expression;
        ConstantExpression constant = (ConstantExpression)member.Expression;
        object fieldInfoValue = ((FieldInfo)member.Member).GetValue(constant.Value);
        object value = property.GetValue(fieldInfoValue, null);
        string name = property.Name.ToSafeAlias(true);
        contentBase.SetValue(name, value.ToString());
    }
}

It's basic and doesn't take into account type conversion to and from strings, nor existing supported types but it's certainly a step in the right direction and better than what was there before.

Obviously, also, there is a an element of assumption in that technique in that we cannot predict what the alias will be and can only go on the most likely name based on the property. Personally though I don't believe the alias should be human editable and should be abstracted away with greater convention. That allows greater predictability and better quality code.

I would like to see more API signatures in Umbraco like the example I have created and would be more than happy to help try to tighten up the various APIs for the next major version.

Let me know what you think.