Serialization using Sitecore CLI

Sitecore 10 comes up with lots of new and interesting features like Containers, ASP.NET Core rendering, and Sitecore Serialization. One of the features I am going to explain in this article is Sitecore CLI.

What is Sitecore Content Serialization?

Sitecore Content Serialization (SCS) is a systematic way for serializing, sharing, and deploying content items, moreover keeping them in version control.

It is helpful for the teams of developers that are working on the same Sitecore solution but different machines. It is used to synchronize the database changes between their development environments.

Before Sitecore CLI developers used different tools like TDS, Unicorn, and Sitecore Packages to share the items while working in a team. Sitecore itself also provides a way to serialize items but it stores data in key-value pair (.item files) and very few people use it.

The main benefit of Sitecore Content Serialization using CLI or Visual Studio Plugin is that it is based on JSON configurations and it provides certain options for configuration to include or exclude the items from the Sitecore tree.

Sitecore has combined the best of both TDS (Team Development for Sitecore) and Unicorn to develop Sitecore CLI. It provides easy to use GUI with Sitecore for Visual Studio Plugin, an easier setup than Unicorn, faster deployments than TDS, and easy automation with Sitecore CLI.

Different ways to Serialize

Sitecore for Visual Studio - It is a graphical user interface for Sitecore Content Serialization using Visual Studio.

Sitecore CLI - It is a Command-line tool that helps you to interact with Sitecore Instance.

Working with Sitecore CLI

1. One of the main steps to start with Serialization using Sitecore CLI is that your system must have a 3.1 version of .NET Core installed. If it is not installed then you can download and install it. The link for the same is provided at the end.

2. Now you have to install the Sitecore Management Service (Sitecore CLI) package in your Sitecore Instance. You can download the Management Service package from the Sitecore official download site. The link is provided at the end.

Note: Make sure that you download the version which is compatible with your Sitecore Instance. If you install an incompatible version then your Sitecore will crash.

3. Now create a folder where you want to serialize your Sitecore Content tree items. In my case it is D:\SitecoreSerialization.

4. Now run the PowerShell or Command Prompt in admin mode at the path of the project set up in the 3rd step and run the below commands.

dotnet new tool-manifest

dotnet tool install Sitecore.CLI --add-source https://sitecore.myget.org/F/sc-packages/api/v3/index.json

Note: You can also install Sitecore CLI as a global tool but it is not recommended.

dotnet tool install Sitecore.CLI -g --add-source https://sitecore.myget.org/F/sc-packages/api/v3/index.json

5. Once the installation of Sitecore CLI is done you can verify it using the below command.

dotnet sitecore

6. In the folder created in 3rd step, run the below command to generate the required files for serialization.

dotnet sitecore init

A folder named .sitecore is generated and a file named sitecore.json. Open the sitecore.json file and you will get the below code.

{
  "$schema": "./.sitecore/schemas/RootConfigurationFile.schema.json",
  "modules": [
    "./TODO/*.module.json"
  ],
  "plugins": [
    "Sitecore.DevEx.Extensibility.Serialization@4.1.0",
    "Sitecore.DevEx.Extensibility.Publishing@4.1.0",
    "Sitecore.DevEx.Extensibility.Indexing@4.1.0",
    "Sitecore.DevEx.Extensibility.ResourcePackage@4.1.0"
  ],
  "serialization": {
    "defaultMaxRelativeItemPathLength": 100,
    "defaultModuleRelativeSerializationPath": "serialization",
    "removeOrphansForRoles": true,
    "continueOnItemFailure": false,
    "excludedFields": []
  }
}

Note: The main thing you need to note in this code is the "modules" section. Modules contain the path where your .module.json file is located, which tells Sitecore CLI, what to serialize and what not.

7. Now again at the same path run the below command in Command Prompt or PowerShell in admin mode.

dotnet sitecore login --authority https://sitecore102learnidentityserver.dev.local --cm https://sitecore102learnsc.dev.local --allow-write true

Once the command is successfully run it will open the Sitecore in the browser. When Sitecore is open, log in to Sitecore and then click "Yes, Allow".

Note: Replace https://sitecore102learnidenityserver.dev.local with your Sitecore Instance Identity Server URL. Similarly, replace https://sitecore102learnsc.dev.local with your Sitecore Instance.

8. To serialize the Sitecore Content tree items I have to create a .module.json file mentioned in the 6th step and also modify the sitecore.json file according to my need.

The sitecore.json file is used for controlling the action of Sitecore Serialization. The module in my case contains "src/*/*/*.module.json". It is used to refer to all the modules in my solution in the src folder.

{
  "$schema": "./.sitecore/schemas/RootConfigurationFile.schema.json",
  "modules": [
    "src/*/*/*.module.json"
  ],
  "plugins": [
    "Sitecore.DevEx.Extensibility.Serialization@4.1.1",
    "Sitecore.DevEx.Extensibility.Publishing@4.1.1"
  ],
  "serialization": {
    "defaultMaxRelativeItemPathLength": 130,
    "defaultModuleRelativeSerializationPath": "serialization",
    "removeOrphansForRoles": true,
    "continueOnItemFailure": false,
    "excludedFields": []
  }
}

The default configuration only refers to a single module.

9. Now I will create a .module.json file at D:\SitecoreSerialization\src\Feature\Learning Site and Modules. Below is the code for the json file.

{
	"namespace": "SitecoreItems",
	"references": "",
	"items": {
		"includes": [
		{
			"name": "Content",
			"path": "/sitecore/content"
		}]
	}
}

Note: I have only included content items by specifying the path. Moreover, I have not excluded any items.

You can look for more information about the .module.json file from the link provided at the end.

10. Now to get the .yml files for your Sitecore Content tree items run the below command in PowerShell or Command Prompt in admin mode.

dotnet sitecore ser pull

You can look for more information about the commands for Sitecore Serialization from the link provided at the end.

For other commands or the help section just run the command mentioned below:

dotnet sitecore --help

11. You can now open the Serialization folder created at the path where your .module.json file is located. It will contain all the items you specified for serialization.