Upgrade Sitecore Glass Mapper from v2 to v3

I recently upgraded a project from Glass Mapper v2 (Glass.Mapper.Sitecore) to Glass Mapper v3 (Glass.Mapper.Sc). I’ve been fortunate enough to be using Team Development for Sitecore (TDS) with most of my projects over the past few years, which really simplifies generating a default set of Glass Models using the T4 Templates which are available from the Hedgehog Codegen repo on GitHub. The upgrade process was simple enough (NuGet FTW!) but thought I would share some issues I came across that took a little bit of time to resolve.

The upgrade was to fix some unrelated issues we were facing, but since the v2 Glass project seems to have disappeared off the face of the earth (annoying that an entire GitHub repo just gets deleted like that rather than left for historical purposes…) it seemed like a good idea to remove this dependency at the same time.

Glass Namespaces

The namespaces have changed. A simple enough process to find and replace Glass.Sitecore.Mapper to Glass.Mapper.Sc throughout your project.

Unblocking T4 files

A simple one, but it popped up on Stackoverflow so thought I would include it. Various types of files which are from the Internet or another computer are blocked from being opened or run, this is a security measure in Vista, Windows 7, and Windows 8. To unblock the files simply right click each of them, select Properties and click Unblock from the popup.

Unblock T4 File

Erroneous carriage return in Header T4 file

Having unblocked the files, you may get another error when trying to generate the models using TDS in Visual Studio:

An error occured while generating code for item '/sitecore/templates'.
T4 Template: D:\Project\XYZ\TDS.Master\Code Generation Templates\GlassV3Item.tt

Compiling transformation: Invalid token 'this' in class, struct, or interface member declaration
Compiling transformation: Method must have a return type
Compiling transformation: Type expected

This was an annoying bug to track down. The issue is an erroneous carriage return which gets added in to the end of GlassV3Header.tt file. If you look at the file on GitHub there is only 70 lines, but if you download a zip of the entire repo this file magically has 71 lines, the last one being empty. You may have the same issue with GlassV3Item.tt file also. It seems that cannot have any literals in T4 templates after the end of the scriptlet, which normally means the <# #> blocks but the same seems to be true for any empty literal.

Obsolete Methods have been removed

A few helper methods seem to have now been removed. These had been marked Obsolete for some time for it’s no real surprise. The main ones which needed to be changed were Editable, RenderLink and RenderImage, but nothing major here, just a slight rework of the method signatures.

Previously we had been passing in the Glass Field like so:

litLogo.Text = RenderImage(customModel.Logo);

Now we have to pass in the Model and project the field, no big deal:

litLogo.Text = RenderImage(customModel, x => x.Logo);

You’ll get errors and warnings about all these in the output window anyway, so it will be clear where you need to tackle these.

Differences in Generated Namespaces

The biggest issue we faced was the the T4 files had changed significantly since they were added to our project. The T4 files were now all self contained and the extension methods had been moved into additional TT files from the old extensions project, which previously required building a Visual Studio project and deploying the resulting DLLs in the Public Assemblies folder usually located in C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\PublicAssemblies. This in itself is a great thing, it allows us to self contain our project and also means it is possible to have different but due to the removal of RemoveUnderscores() extension method it meant that there was a lot of broken references now in the generated code and we were getting a lot of build errors, a few too many throughout the entire project to fix by hand 😦

The simpler fix was to update the supplied T4 files and add the RemoveUnderscores() method back using the same logic as the previous extensions project. You have to go back to the repo to before the 14 June 2014 commit to find the original Extension project and then merge in the differences into the new TT files, or you can just grab the codegen T4 files at that point (and continue using the deployed Extensions project).

public static string RemoveUnderscores(string word)
    return !String.IsNullOrEmpty(word)
        ? word.Replace("_", "")
        : word;

If you are going through this same update process and want to move completely over to the self contained T4 templates then you can use this String Extension T4 file: https://gist.github.com/jammykam/c1f8c82637c0e71be533
Diff the file against the original to see exactly what has changed.

If you work with T4 templates for any period of time then install the T4Tangible extension, it makes working with T4 Templates much nicer.

Other Goodies

There’s some real nice gems in the newer Glass V3 generated models, namely the following are generated as well:
– Template ID
– Template Name
– Field Name
– Field ID

public static partial class IMyCustomTemplateConstants {

    public const string TemplateIdString = "2c4a52ac-6668-43e9-91ea-d4ae8ad179cd";
    public static readonly ID TemplateId = new ID(TemplateIdString);
    public const string TemplateName = "My Custom Template";
    public static readonly ID MenuTitleFieldId = new ID("e13b242d-29f2-4816-a082-38344fb5edc7");
    public const string MenuTitleFieldName = "Menu Title";

    public static readonly ID HideInMenuFieldId = new ID("6a6fe27c-f708-40be-a38f-fc23c275de8c");
    public const string HideInMenuFieldName = "Hide in Menu";


No more checking template id’s in code against strings. This should allow us to remove just a few more of those magic strings and work against a strongly typed, auto-generated model. If a template gets deleted, that “magic string” reference also disappears when the model is regenerated and we get an early build error. The addition of the Field Names and ID’s also really useful. Names have always been easier to type and understand, but ID’s have always been better performance wise. We no longer need to worry about performance vs readability.

And of course, we get all the performance and additional benefit from Glass Mapper v3.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s