Sitecore Serialization: Upgrading Unicorn 2 to Unicorn 3

 We've been using Unicorn for a while now with no small amount of success. For our purposes, it simplified the options available and allowed a developer to easily sync all of the latest Sitecore content without hunting and pecking through the content tree.

If you're not familiar with Unicorn, it's worth taking a look. Installing it for the first time is as simple as installing a NuGet package and modifying a config file.

In Unicorn 2, syncing was as simple as clicking the "Sync All Configurations Now" button, which automagically got all the content in the right places. Every now and then, there would be a content sync issue that could usually be resolved by reserializing the tree at the point of the offending node using Sitecore Rocks.


Unicorn 3 brings with it better performance, a new serialization engine/format, and a slicker UI:

One of the key benefits of the new format is the omission of the content-length property, which gave some of our front-end devs fits when they were trying to modify content or content items using Macs.  Since the line endings are different between Mac and PC, the content-length was always different and that sometimes caused items to not sync properly.

The YAML for a folder now looks like this (as compared to a 242 line .item file that Sitecore's format uses):

---
ID: e5f1aaf6-bc99-4b44-b110-0cf8f940661e
Parent: b29ee504-861c-492f-95a3-0d890b6fca09
Template: 0437fee2-44c9-46a6-abe9-28858d9fee8c
Path: /sitecore/templates/User Defined/Base Templates
Languages:
- Language: en
  Versions:
  - Version: 1
    Fields:
    - ID: 25bed78c-4957-4165-998a-ca1b52f67497
      # __Created
      Value: 20150424T210157Z
    - ID: 5dd74568-4d4b-44c1-b513-0af5f4cda34f
      # __Created by
      Value: sitecore\admin

The upgrade process

Since this is in NuGet, the process of upgrading is fairly straightforward, and Kam (the creator) details it out very well on his blog: https://github.com/kamsar/Unicorn/wiki/Upgrading-to-Unicorn-3.
Once you upgrade, you'll need to run an initial sync for Unicorn to pick everything up and convert it to the new format, but then you're off to the races!

One notable inclusion in the new version of Unicorn is Transparent Sync, which is less of a sync than just looking at the serialized items first. It has the side effect of you not needing to explicitly run a sync, which can be nice when you are developing locally.

Troubleshooting


If you get this, you need to add names to your include nodes. Our old Unicorn 2 setup didn't have them, but it's as simple as changing something like this
<include database="master" path="/sitecore/layout/Layouts/User Defined"/>
to this:
<include database="master" name="User Layouts" path="/sitecore/layout/Layouts/User Defined"/>

Once I do that, Unicorn neatly packages all my content into YAML (.yml) files within folders matching the names of my Include nodes:

Popular Posts