Upgrading to Unicorn 3

Unicorn 3 is a pretty major upgrade from v2. A significant amount of the default configuration has changed with new and different dependencies. The good news is that most of the commonly used configuration remains the same.

Starting out

Because Unicorn 3 uses a new serialization format and filesystem organization, you will need to reserialize ALL items that are stored in Unicorn. Before starting the upgrade, make sure you've got a master copy of the latest serialized items synced into your database and ensure that no other developers are making item changes until you're done upgrading and have committed the new items.

There are also some engine changes that you should be aware of:

• Unicorn 3 uses Rainbow's Serialization File System trees by default. These trees are rooted on disk at the root item selected in Sitecore, as opposed to the root in Sitecore. For example if you included /sitecore/content/foo, in master, Unicorn 2 would put this in $(serializationRoot)/master/sitecore/content/foo.item, whereas Unicorn 3 creates a tree for each include so $(serializationRoot)/foo/foo.item (you can change the name of the foo folder by adding a name attribute to your predicate entry).
• SFS trees are "solid," meaning that you cannot have any tree nodes that do not have a serialized item. This is generally not a problem, but be aware that it means that the predicate only supports path-based includes and excludes. Unicorn 2 supported item ID and template ID-based predication as well.
• Unicorn 3's default configuration filters out the following fields from being serialized: Last run field on Schedule template, __Originator, __Revision, __Updated, __Updated by. This is generally appropriate for serializing development artifacts but may be undesirable if you're versioning any user content.

Sound good? Let's start the upgrade.

Upgrading

1. Make sure you have synced the latest serialized items from Unicorn 2 into your database, and freeze item changes by others
2. Upgrade the Unicorn NuGet package to 3.0. This will pull in the dependencies (Rainbow, Rainbow.Storage.Sc, and Rainbow.Storage.Yaml)
3. Run a build of your solution in Visual Studio, to ensure the updated Unicorn assemblies are deployed
4. Unicorn 3 uses a new configuration setup, where its config files reside in App_Config/Include/Unicorn. Review the Unicorn.config file and transfer your settings from the old Serialization.config into it - specifically, your configuration(s). A diff tool such as Beyond Compare is great here. If you've customized dependencies other than the predicate in your configurations, or have customized default dependencies, review each one to see if it is compatible with Unicorn 3's dependency model as a number of namespaces have changed. If you're wondering where something went, tweet @kamsar and I'll help you out. NOTE: you may need (or want) to add unique name attributes to your predicate includes after the upgrade for disambiguation. An error will warn you if this is required.
5. Take special note in your config of what the targetDataStore's physicalRootPath is set to, because its semantics are different from the Unicorn 2 rootPath. It is not recommended to use the Sitecore default serialization location (`$(dataFolder)\serialization') for Unicorn 3, because of the different format. Choose a root path that makes you happy.
6. Delete the old Serialization.config, as it is no longer used. Take note also of the other config files in the Unicorn folder as well, as you should remove some in deployed scenarios or if you don't want the feature they provide - there are comments to help you decide.
7. Open the Unicorn control panel (/unicorn.aspx by default) and perform a reserialization of all configurations
8. Remove your old v2 serialized items from the disk as they are no longer used
9. Perform any required alterations to your build and deploy process that may be required (e.g. if you moved your root path, want to remove the data provider during deployment, etc)
10. Commit your changes and you're done!