Simplifying item serialization in Sitecore with Sitecore CLI

Item serialization is an important process during continuous integration as it helps ensure the consistency and reliability of the build and deployment process. It assists developers in sharing items and speeding up development. If a new feature requires a content page, it can be included within the project. Other developers can work with the same items, without having to recreate them.

It is also great to have items included to be shared across different environments. Templates, designs or themes for example. During a deployment, these items can be updated and published, and the new features or updates will be directly available to the Sitecore instance.

In this post we will talk about the Sitecore CLI (Sitecore Command Line Interface), how to set it up and how to use it.

First things first: Setting up Sitecore Serialization

Since Sitecore Serialization is not available for earlier versions, make sure you are using Sitecore version 10.0 or later. Next to that, you also need to have .Net Core 3.1 installed on your server.

How to configure and use Sitecore CLI

In the past, most projects used either Hedgehog TDS or Unicorn to support item serialization. But now, starting from Sitecore version 10.0, a new tool has made its entrance: Sitecore CLI (Sitecore Command Line Interface).

Sitecore CLI lets you define module. JSON files in which you can specify for your module which items need to be serialized. The module files can be set in two ways: per feature of your solution or in general for your entire platform. By keeping these files relevant per feature, it is easier to understand what the module is meant to do.

The module defines a set of item paths and what needs to be serialized with Sitecore.

Configure JSON for serialization

The module.JSON files make it easier to specify what exactly it is you want to serialize. Using the properties and examples below, you can configure all your desired serializations.

Properties for JSON file:

• name
  • Unique name for serialisation
• path
  • Path of the item to serialize
• scope
  • Define what content to serialize
    • SingleItem: Only the item specified from the Path
    • ItemAndChildren: Item specified in path with immediate children
    • ItemAndDescendants: Item specified in path including all the descendant items
    • DescendantsOnly: Only the descendent items specified form the path
    • Ignored: All children and descendants will be ignored, unless in previously matched.
  • database
    • Selected database to sync. This can be “master” or “core”
  • maxRelativePathLength
    • Specify how long the path may be, by default this is 130 characters
    • If the length has been reached it will create a new hashed folder in the root of the directory
  • allowedPushOperations
    • Define how content can be serialized
      • CreateOnly: This will only create the item, if it already exists it will be ignored.
      • CreateAndUpdate: Creating and updating items. If it already exists but is modified, it will update the item. This setting will not remove items.
      • CreateUpdateAndDelete: Items will be created, updated and removed.

Example structure of module.JSON serialization file

Using Sitecore CLI to synchronize items

There are multiple ways you can use the CLI synchronization.

Installing Sitecore Command Line Interface

In order to use CLI, first download a package to install the Sitecore Management Services. You need the Sitecore Management Services to support Sitecore CLI and Sitecore for Visual Studio.

Download the package from Sitecore here: https://dev.sitecore.net/Downloads/Sitecore_CLI.aspx

Once the package installation is complete, you can move forward with the following steps:

• Open a terminal with administrator privileges.
• Run the following command to install CLI:
  
• Initialize your project
  
• Install the Publishing and Serialization plugins:
  
• Verify if Sitecore CLI works
  
  
  • The output of this command should look like:
    

Using CLI from PowerShell

First, login into Sitecore. You can do this by running the command in PowerShell and navigate to you Sitecore Project folder:

A browser will open, and you can enter your Sitecore Credentials. Once this is done you can close your browser.

These are the most frequent commands:

• Pulling the Sitecore items from your instance to local disk
  
• Pushing items from your local disk to Sitecore instance
  
• Publishing items to web database
  

Using Visual Studio

Sitecore for Visual Studio plugin gives you a graphical user interface. If you are used to Sitecore TDS, this plugin works similar. After installation, you can access the plugin within Visual Studio by going to Views à Other Windows à Sitecore Module Explorer.

Once you have installed and have the right license configured you will be able to create your sitecore.json file.

An example of this file:

This sitecore.json file loops through all your module.json files. Then, once you open the Sitecore Module Explorer, it will contain all your modules.

You can pull or push each individual module, or you can do this for all items on Sitecore Configuration Root level.

Using Sitecore CLI during deployment pipeline

With Sitecore CLI, it is easy to create your serialization step within your deploy pipeline.

In order to make this happen follow these steps:

• During your build steps include a Create CLI package step
• During the deployment to your CM environment include a Deploy CLI package

Deployment of your CLI package is only required on your CM environment for the items will be published if specified to the CD environment.

Creating your CLI package

This is an example of the PowerShell script to create your package:

First, include the nuget source from Sitecore. Second, install the Sitecore.CLI tool.

Then you can call the serialization to create your package.

Deploy your CLI package

During your deployment step, you can then use the following example to serialize your package:

Once again, begin with the installation of the Sitecore.CLI tool.

By calling the serialization to install the package, you can choose to use an automated publish or skip the publish and do this manual afterwards.

Sitecore CLI: our final conclusions

The Sitecore CLI is a great tool to get everything within Sitecore shared across multiple developers and environments.

The option to choose between the command line and graphical Visual Studio plugin gives every developer the freedom to select their preferred way of working.

Using the Sitecore CLI makes it easy and quicker to get your features deployed to all Sitecore environments having the right templates or settings items that it needs.

We hope this article has given you some great ideas on how to use Sitecore CLI.

Do you want to more information what we can accomplish together? Let's talk!