Skip to main content

Umbraco Mapper: New Releases Supporting Umbraco V8

Today I've published two new versions of the Umbraco Mapper package, a package that supports the use of view models, by mapping Umbraco content to custom view model classes (original thinking was Automapper for Umbraco I guess).

They are available on for download or can be installed via NuGet.

I was surprised to see that it's been over 5 years since this package was originally built by myself and some colleagues at Zone - a long time in technology. We're still making use of it though, and as I had some popular demand - well, two people(!) - for a version compatible with the latest Umbraco release, thought it would be good to prepare one.

I've taken an approach of restructuring the solution such that there's a common project, containing non-Umbraco dependent core set of functionality, and then created two Visual Studio projects within the solution, one referencing the Umbraco 7 binaries and one the Umbraco 8 ones. That way, I can support both versions moving forward, and at least minimise the extra effort in terms of duplicated code to maintain moving forward. If all goes as expected, I'll be talking about this technique in more detail, along with other factors involved in upgrading packages to Umbraco 8, in an edition of Skrift near you in a month or so.

Release Details

There are two new versions of the package:

  • Version 3.0 - targeting Umbraco 6 and 7
  • Version 4.0 - targeting Umbraco 8
Umbraco 7 (Umbraco Mapper 3.0) Release

This provides almost the same functionality as the most recent 2.0.9 release. However I have bumped the major version due to a few minor breaking changes, mainly taking the opportunity to streamline a few things.

  • The recursiveProperties string parameter passed to the mapping operations has been removed. This an API design issue from the start really, as it was never necessary, and since support has been added for marking particular view model fields to be mapped recursively via the attributes or the property mapping dictionary you can provide in the mapping call.
  • Have changed the approach to passing a CustomMapping object in the property mapping dictionary to require a type and method rather than a CustomMapping instance itself. This aligns with the use via attribute, and improves internal code re-use as version specific Umbraco dependency is removed.
  • Have added a new FallBackMethods property mapping override and attribute. This isn't necessary to use when targeting version 7 as the only method of "falling back" to retrieve a property value when it's not found on the current content node is recursively, via the ancestors in the tree, when the MapsRecursively boolean attribute or property mapping override can be used. It paves the way though for supporting other methods - namely language fallback, in version 8.

I've also restructured the solution and some namespaces as part of the work to support Umbraco 8, though this shouldn't have any effect for users of the package.

Umbraco 8 (Umbraco Mapper 4.0) Release

The release for Umbraco 8 should provide the same functionality as has been available for Umbraco 7, though obviously working with the new release of the CMS platform.

There are two additional features available though.

One is support for language variants. The signatures for the Map and MapCollection methods have been changed to accept an optional culture code (e.g. "en-GB"), and, if provided, the mapping will use the content from the language variant indicated by the culture code.

    mapper.Map(CurrentPage, model, "en-GB");

The related second addition is the support of fallback methods, so we can ask the mapper to retrieve content from a fallback language if the property value requested has no content (in addition to falling back recursively, via the ancestors in the content tree, as was available before). This can be passed either using a dictionary in the mapping operation:

    mapper.Map(CurrentPage, model, "it",
        new Dictionary<string, PropertyMapping>
                { "HelloText", new PropertyMapping 
                    FallbackMethods = Fallback.ToLanguage.ToArray() 

Or by decorating the view model with an attribute:

    public class MyViewModel
        [PropertyMapping(FallbackMethods = new[] { Fallback.Ancestors })]
        public string HelloText { get; set; }

As it's an array, you can even make use of more complicated fallback logic, supported by Umbraco, so you could retrieve content from the fall-back language, and if that fails, via the parent node:

    public class MyViewModel
        [PropertyMapping(FallbackMethods = new[] { Fallback.Language, Fallback.Ancestors })]
        public string HelloText { get; set; }

Wrapping Up

Hopefully this new version provides useful to anyone already using the package and migrating to Umbraco 8, or considering using it for a new project. We'll likely get to put it through it's paces at Zone with some upcoming projects. In the meantime, if anyone does find any issues, please feel free to report on the forum or issue tracker.


  1. I've had a quick look and managed to get things mapping again in my new Umbraco 8 project which is great! Really appreciate the effort you put in to this package Andy and getting a version compatible with Umbraco 8 out so quickly.

  2. Nice, Looking forward to giving it a spin.


Post a Comment