Setting Up Unicorn for Sitecore Projects: a Practical Guide

Sitecore Unicorn setup practical guide

This article is about working with Sitecore Unicorn. It will explain how to get started with Unicorn, look at the build and deployment workflow, and outline the specific features of the tool. It will also provide a quick overview of existing alternatives to Unicorn and summarize the ways content can be serialized in Sitecore.

What Is Sitecore Unicorn?

Let’s start with the definition. Unicorn is a utility for content serialization in Sitecore-based projects. In simple words, this tool allows developers to automatically move content items (templates, layouts, renderings, etc.) between instances and store them as part of source control.

How Is Unicorn Set Up?

Generally, three things are needed to set up Unicorn:

  • Sitecore and content to sync
  • A folder under the source control to store the serialized items as files
  • Unicorn itself to do the job

I will assume you already have the Sitecore instance and need to set up the folder and Unicorn.

Unicorn installation is very simple.

  • If you are following Helix architecture, you need to add a project for Serialization under the Foundation layer. Then, install Unicorn packages as shown in the screenshot below.

Setting up Sitecore Unicorn

Note: the demo project in the screenshot is available with source code on my github.

  • Select a Unicorn package and additionally Unicorn Users/Roles if you need to serialize users or roles and install packages.

Once you are ready with the new project and packages, the next important thing is setting Base configuration and defining the folder on the disk to store the serialized files.

How to set up Sitecore Unicorn

In my demo project, the folder is defined in Demo.Unicorn.Base.config. This config file is used as basic and inherited by others.

If you have different folders for your environments, you can use config transformations to define appropriate paths for them.

Set up Unicorn for SItecore projects

Setting up Sitecore Unicorn

As you can see in the screenshot, Unicorn allows you to define multiple configurations, giving you a lot of flexibility: you can serialize items to different places on the disk, set up groups that can be synced separately, and override any aspect of Unicorn in each configuration. Configurations may also define dependencies between each other.

In my example, you can see four configuration files:

  • Base — contains basic configuration with a folder under the source control to store the serialized files.

Three other files are inherited from the base file. This is the approach to take when you define a separate config for each database (and probably useful for legacy projects).

  • Core — used to serialize items from the Core database
  • Master — used to serialize items from the Master database
  • MasterContent — used to serialize custom content that should sometimes be synced with environments; e.g., labels that need to be created once if they don’t already exist

The Helix-based approach is more modern, of course.

Sitecore Unicorn setting up

In the screenshot, you can see an example from the Habitat solution. In fact, there is a basic configuration for all layers as well as one for each layer individually. When you create your custom layer, you simply inherit it from the relevant configuration depending on layer type — Project, Foundation, or Feature.

Basic configurations contain a general list of items to serialize. If you need to serialize something else — for example, something specific to your Feature — add item paths into your new custom configuration. In the screenshot above, you can see three files.

If you sync custom content that can be edited by a customer, you should be careful not to override already existing content.

set up Sitecore Unicorn

With Unicorn, you can achieve this by using NewItemOnlyEvaluator to create content once only, if it doesn’t already exist. Thus, you will only deploy new items in the environment.

Okay, so you are ready with the Project, you’ve installed Unicorn and set up custom configuration. Once you deploy it, you should be able to open the Unicorn admin page.

Introduction to Unicorn

Here you can see each config as a separate group that can be synced independently. When you do production deploy, you can open this page and click the SYNC buttons for configurations. This is how you make the items on the disk appear in Sitecore.

Automated Deployment

If you want to automate the process, Unicorn provides the tools to do this.

Unicorn has an automated tool API whereby you can invoke actions in the Unicorn control panel from a script, for example, invoking sync after code deployment.

Another option is Transparent Sync. When this tool is used, the items on the disk magically appear in Sitecore without syncing. Transparent Sync looks simpler, but personally, I prefer to control sync manually. So during deployment, I use the Unicorn admin page to sync content.

If you are interested more in how serialization works in Unicorn and who actually does it, you should see Unicorn.DataProvider.config. This class is responsible for the Sitecore content serialization on the disk.

Alternatives to Unicorn

TDS

Working with Unicorn, you probably have to deal with TDS too. Sitecore TDS and Unicorn share a similar functionality: they can serialize Sitecore items to the file system and store them in source control.

The difference between Unicorn and TDS is that Unicorn forces all the merging to be done on the disk, so you never have to manually select what to update when you’re running a sync operation or remember to write changed items to the disk.

Moreover, Unicorn is free while Sitecore TDS is licensed per developer and available as an annual subscription for $399. Still, TDS is worth the price.

SCS

Another alternative is the most exciting new feature in Sitecore 10 — Sitecore Content Serialization (SCS), a tool for serializing, sharing, version control and deployment of content items.

I can recommend SCS as a new progressive tool that can be used instead of TDS and Unicorn and that combines the best of both.

SCS has a Visual Studio plugin to manage content and a Sitecore command-line interface (CLI).

The CLI tool can be used for serialization, creating item packages and publishing. No license is required — just install and start using it.

Visual Studio plugin can push and pull changes, show differences between disk and database content, and sync items.

The only requirement for using the VS plugin is to have an appropriate Sitecore TDS license. Installing this plugin will add an additional window called Sitecore Module Explorer to VS.

Internally, CLI and VS plugin both use a Sitecore GraphQL endpoint to interact with the Sitecore instance to retrieve item information.

Conclusion

We’ve discussed how to get started with Unicorn, configure and deploy it. We also compared three possible ways to serialize content in Sitecore.

Unicorn

  • A free, open-source, powerful serialization tool
  • Can be used with Sitecore 10
  • Can sync users
  • Requires complex configurations that are challenging for non-expert users
  • Has community support

TDS

  • Available by subscription
  • Backed by dedicated enterprise support

Sitecore Content Serialization (SCS)

  • A new progressive tool
  • Combines the best of TDS and Unicorn

All of these tools are great at doing the work they were built for. It’s up to you to decide which one to choose. Hopefully, you’ve found the information in this article helpful. If you have any questions, feel free to contact me via LinkedIn or Twitter.

Rating: 5.0/5. From 3 votes. Show votes.
Please wait...

About the author

Raman Khalupau
Raman Khalupau

Raman Khalupau is a talented, certified Sitecore Lead developer who helps transform routine projects into extraordinary pieces of IT art. Aimed at non-stop self-improvement, Raman also manages the internal Sitecore community and helps less experienced developers become true experts. Find him on LinkedIn.

5 Comments

Leave a comment
  • Thanks that you took the time to share your knowledge in this article, I’m sure that it helped many developers, including me.

  • I needed to set up Unicorn for the first time and came across your tutorial, it was of great help!

  • In my opinion, Unicorn is the most comprehensive tool for managing items in Sitecore as of now. Thank you for this overview.

  • I use Unicorn for content serialization for quite a long time and can say that this tool is really convenient.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>