Setup of Unicorn with Sitecore 8.2

09 Nov 2017 - Mike Parker

This guide will show you how to setup Unicorn Sync with Sitecore 8.2. This will allow us to synchronize content and data within a sitecore instance to other instances easily.

What you will need

Visual Studio Logo Visual Studio
(2015 used in this guide).
Sitecore CMS
(8.2 used in this guide).
Octopus Deploy Logo A Sitecore deploy in
Octopus Deploy


Step 1 Installing Unicorn.
Step 2 Configuring Unicorn watched items.
Step 3 Configuring Unicorn DataStore.
Step 4 Auto syncing environments using Octopus Deploy.

Step 1 - Installing Unicorn

This guide assumes you have already set up Sitecore, SQL databases and have it built and up and running. If not, you should refer to the Setup of Sitecore 8.2 on Azure guide for steps on how to do that first. You will only need to follow the steps required to get a local instance up and running.

  1. In Visual Studio, open your Sitecore project.

  2. Right click on the project and select “Manage NuGet Packages…”

  3. In the NuGet window, select the “Browse” tab if it isn’t selected already and search for “unicorn”.

  4. For this guide, I have installed Unicorn v3.3.2 which is the latest version available at this time. It should appear at the top of the list as (image shown below):

  5. Install the package. Your Sitecore instance should now have Unicorn installed.

  6. Build and publish your solution.

  7. To verify Unicorn is up and running, log in to your Sitecore admin and navigate to http://yourinstance/unicorn.aspx (do not click that link, it’s just an example).

Nuget Window showing Unicorn

Step 2 - Configuring Unicorn watched items

As we have installed the full Unicorn NuGet package we will have some useful example configuration files to use as a template to base our actual configuration on. There are however a few little workarounds to do in order to get it working nicely with version control. There may be a better way to do this but for now this is how I have got it to work.

  1. In your solution, open the folder /App_Config/Include/Unicorn. Here you will find the Unicorn configuration files and examples.

  2. Create a copy of Unicorn.Configs.Default.example and change the extension to .config and open the file for editing

  3. The example config is documented very well. Read through and update the values as necessary, my testing config file looked like this:

Unicorn Config File

configuration - The configuration name is used throughout the Unicorn instance so it’s worth giving it a sensible name. The description is purely informative and doesn’t require too much detail as you can view the whole config via the Unicorn dashboard if need be.

predicate - The predicate section is the important part, this is where you specify what will be serialized by Unicorn. For this guide I have set unicorn to monitor important system folders (so settings transfer etc) as well as the Layouts and Templates directories. It is advisable to put the layouts and templates in a folder with the name of  the project, this means you won’t have to write exclusions for system templates and layouts. Other methods may work just as well so use a convention that works for you and the project. The name of the include will also be used as the folder name for the serialized versions of the files.

dataProviderConfiguration - Used to enable / disable transparent sync. For the time being we will leave it set to false and change when the setup is complete.

syncConfiguration - Used to trigger database index updates. This will be useful if we decide to start syncing up content (Sitecore content items).

Important: As mentioned in the example config - the EXCLUSIONS WILL NOT WORK WITH TRANSPARENT SYNC. As the preferred method of updating with Unicorn is to use the transparent sync then ideally we should avoid using exclusions.

Note - Adding the entire settings folder appears to break the Unicorn sync process due to some invalid output. This is caused by the file located at /sitecore/system/Settings/Rules/Definitions/Elements/Engagement Automation/Visibility/GeoIP visibility.

Step 3 - Configuring Unicorn DataStore

In order to version control the serialized data from Unicorn, we will need to store the files within our solution. Because of this the next steps will guide you through configuring Unicorn to export and import the files into the project instead of the published location of the instance. We will then exclude the changes to prevent pushing the config to Azure.

Go to the Unicorn config directory (/App_Config/Include/Unicorn) and create a copy of the file named Unicorn.CustomSerializationFolder.config.example and remove the .example extension.

Open the CustomSerializationFolder config file. Again the file is heavily commented so is worth a read.

Amend your config file so that the targetDataStore is set to your solution data directory opposed to the published Website data directory. See below:

Unicorn config targetDataStore property

targetDataStore - Set to your local instance directory so we can version control the project and not the published version.

settings - I have had to modify the SerializationFolderPathMaxLength to accommodate my project path. If you have the same issue it is best to keep the changes in the same patch file. The default setting is 110.

Important: We will only be publishing this file once to the published version and then excluding it from our project. This file should not be version controlled and will be specific to each developer involved in the project.

Build and publish your solution.

Issue with config? Check this: If your configuration is not taking effect, check that the build setting on the config file is correct. Select your config file in the solution explorer and check that the Build Action is set to Content. For some reason this setting defaults to None.

Navigate to the /unicorn.aspx URL and you should see something like the image shown below.

Unicorn Sitecore page

This indicates that Unicorn is happy with the config that has been set up. If anything is wrong with the setup then this page will tell you what issues exist.

One common issue is that the folders Unicorn is watching in Sitecore do not exist. If this is the case, just jump into your Sitecore instance and create the missing folders.

If everything is up and running, hit the Reserialize option and you will see Unicorn processing the items in Sitecore.

Step 4 - Auto syncing environments using Octopus Deploy

In this step I will be using Octopus Deploy to make a request to the Sitecore instance in order to sync up the data with any new yml files that have been added via Unicorn. There are currently several ways to trigger the update in Unicorn, they are as follows:

  1. Trigger the update manually by logging in to the instance and triggering the Sync process.

  2. Set up the automatic sync of items via Unicorn config.

  3. Using Unicorns MicroCHAP functionality to trigger an update from Octopus Deploy.

  4. Using Unicorns older authentication method to trigger an update from Octopus Deploy.

The first two options are relatively self explanatory and not really in line with the process I am following. Because of this the guide will focus on options 3 and 4.

Option 3 - After several approaches, I could not get the authentication using MicroCHAP to work. The implementation is relatively straightforward but authentication always failed. Not sure if this was due to hosting on an Azure environment but I think this method is definitely worth revisiting in the future.

Option 4 - This method uses very much the same approach as method 3 only with a different method of authentication. See below for the steps. The steps assume you already have a deployment process set up and are only adding the automation as an additional step in the deployment process.

  1. Navigate to the project in Octopus and click “Add Step” to the deployment process.

  2. When selecting a template you will need to find and install a step template. Search for unicorn in the search field and two templates will appear. Select and install the template named “Unicorn - Sync Configuration”. There are currently two Unicorn templates available so be sure to select the correct one.

  3. Complete the template specific fields as follows:

Base URL - The URL of your Azure / Sitecore instance, in my case this is

Configuration Name - This is the name given to your Unicorn configuration in the Unicorn.Config.Default.config file.

Timeout - I have left a default but if you suspect this to take a while then increase as necessary.

Deployment Auth Token - This is the string that you will use to authenticate against Unicorn. You will need to add a field to Sitecores web.config that matches this value and push it to the server. The key needs to be added to the appSettings section of the web.config and must match the token in this field. See below:

Unicorn AppSettings

Basic Auth Username - If basic authentication is enabled enter the username here. Unfortunately the script will encounter an error if this field is left blank so enter a placeholder value if basic auth is disabled on the server.

Basic Auth Password  - If basic authentication is enabled enter the password here. This field will also encounter an error if left blank so enter a placeholder value if basic auth is disabled on the server.

Save the step and run a deployment to test.

Note - This step should be added after a call to the Sitecore URL else you will be a lot more likely to hit the timeout limits.

How can we help?
Get in touch with the innovators at Orange Bus

Thank you, your message has been submitted.