Setup Sitecore Content Serialization

Cet article en francais

One of the most exciting new features in Sitecore 10 is the Sitecore Content Serialization (SCS), a tool for serializing, sharing, version controlling and deploying content items. It replaces external tools like TDS or Unicorn.

In this article, I’ll walk you through how to easily configure SCS to start serializing your items in no time. I’ll show you how to serialize items outside a Visual Studio project, so you’ll see that you don’t need any external tools to do it. Of course, the serialization can be done as a part of a VS solution, and the setup is exactly the same.

I have installed locally the Sitecore Commerce 10 Storefront demo, so we have a lot of items to serialize.

The local CM server is https://sc10sc.dev.local

The local identity server is https://scidentityserver.dev.local

Aside from a Sitecore 10 instance, you’ll need to have .Net Core 3.1 installed on your server.

The setup is done in three steps:

  • Install Sitecore Management Service
  • Install Sitecore Command-Line Interface (CLI)
  • Log in to your instance and serialize your items

Install the Sitecore Management Service

You must install the Sitecore Management Service package to your local Sitecore CM instance in order to support SItecore Command-Line Interface.

  • Download the Sitecore Management Services Module Zip Package from the Sitecore Downloads
  • Install this package from the Control Panel

Install Sitecore Command-Line Interface (CLI)

Open the Powershell console and change directory to a new folder. As I wrote before, we will configure this serialisation outside any other projects or tools. But if you want the serialization to take place inside a Visual Studio solution, you can change the directory to the root of your solution.

Install the Sitecore CLI as a local project tool by typing the following instructions:

 cd d:\
 mkdir Serialization
 cd Serialization
 dotnet new tool-manifest
 dotnet tool install Sitecore.CLI --add-source https://sitecore.myget.org/F/sc-packages/api/v3/index.json 

Work with your items

You need now to initialize your project and create the root file for serialization: sitecore.json

In your Powershell console, type

dotnet sitecore init

A new file is now created, sitecore.json

{
   "$schema": "./.sitecore/schemas/RootConfigurationFile.schema.json",
   "modules": [
     "./TODO/*.module.json"
   ],
   "serialization": {
     "defaultMaxRelativeItemPathLength": 100,
     "defaultModuleRelativeSerializationPath": "serialization"
   }
 }

In the “modules” element, you will indicate which Sitecore modules you want to serialize. You can point to many modules, either separately or with wild characters. It uses the folder structure of your solution. If you are in a Helix-based solution (with sources for each module placed under the folder “src/Foundation|Feature|Project/$ModuleName$”), you will probably end up with a value like “src/*/*/*.module.json”. This will tell the serializer to search for every .module.json in the folders three steps under the source folder “src”.

For the sake of our article, and to see how to switch Sitecore DB, lets presume we want to serialize two different types of items:

  • The content items under /sitecore/content/Sitecore/Storefront/Home (master DB)
  • The items under /sitecore/client/Applications/MarketingAutomation (core DB)

We create two folders under our d:\Serialization

cd d:\Serialization
mkdir content
mkdir client

In each folder, let’s create a json file: content.json and client.json

These files fill be the instructions files with the paths and information SCS needs for each part. The content and possible values for the variables in these files are explained in the Sitecore documentation

content.json

{
  "namespace": "Content",
  "references": "",
  "items": {
    "includes": [
      {
      "name": "content",
      "path": "/sitecore/content/Sitecore/Storefront/Home",
      "allowedPushOperations": "createUpdateAndDelete",
      "scope": "itemAndDescendants"
      }
    ]
  }
}

client.json

{
  "namespace": "Client",
  "references": "",
  "items": {
    "includes": [
      {
      "name": "client",
      "path": "/sitecore/client/Applications/MarketingAutomation",
      "allowedPushOperations": "createUpdateAndDelete",
      "scope": "itemAndDescendants",
      "database": "core"
      }
    ]
  }
}

My sitecore.json is now

{
   "$schema": "./.sitecore/schemas/RootConfigurationFile.schema.json",
   "modules": [
     "./client/client.json",
     "./content/content.json"
   ],
   "serialization": {
     "defaultMaxRelativeItemPathLength": 100,
     "defaultModuleRelativeSerializationPath": "serialization"
   }
 }

All the files are set. Now we need to connect to our Sitecore instance. In the Powershell console, type

cd d:\Serialization
dotnet sitecore login --authority https://sc10identityserver.dev.local --cm https://sc10sc.dev.local --allow-write true

A browser opens and asks you to log in to your Sitecore CM instance and you need to accept to grand the permissions to Sitecore API and Offline access.

Click on “Yes, Allow” and close this browser window.

Now you’re all set and you can begin importing your sitecore items with the command:

dotnet sitecore ser pull

Sitecore CLI lists all the items that will be serialized and create a “serialization” folder under each module with the descriptions of each Sitecore item in Yaml. You can use json serialization if you configure it in the App_Config\Sitecore\CMS.Core\Sitecore.Serialization.config file

If you want to change an item and deserialize it back to Sitecore, use the following command

dotnet sitecore ser push

The different commands from the Sitecore CLI are:

SITECORE LOGIN
sitecore login Logs in to a Sitecore instance.
SITECORE INIT
sitecore initInitializes a project configuration in the
current folder.
SITECORE PUBLISH
sitecore publishPublishes all content from the Master
database to the Web database.
SITECORE SER or
SITECORE SERIALIZATION
sitecore ser diffCompares the content items of two Sitecore
instances.
sitecore ser explainExplains whether a content item path is
included and why.
sitecore ser infoShows serialization configuration information.
sitecore ser packageLists serialization package commands.
sitecore ser package createCreates a package of serialized content items.
sitecore ser package installInstalls a package of serialized content items
in a Sitecore instance.
sitecore ser pullSerializes content items from a Sitecore
instance to your file system.
sitecore ser pushPushes serialized content items from your file
system to a Sitecore instance.
sitecore ser validateChecks serialized content items for validity.
Can fix common issues with the --fix 
argument.
sitecore ser watchMonitors changes to content items in a Sitecore
instance and automatically serializes
the changes to your file system.
From https://doc.sitecore.com/developers/100/developer-tools/en/sitecore-command-line-interface-reference.html

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: