Items as resources and Unicorn

Reading time ~2 minutes

How to use Unicorn serialization data to generate items as resources (*.dat)

Unicorn to Items as Resources

Prerequisites

Install or update your Sitecore CLI to version 4 (upgrade guide) then install plugins.

List of required plugins:

Installation

C:\> mkdir sitecore.cli
C:\> cd .\sitecore.cli\
C:\sitecore.cli> dotnet new tool-manifest

C:\sitecore.cli> dotnet nuget add source -n Sitecore https://sitecore.myget.org/F/sc-packages/api/v3/index.json
C:\sitecore.cli> dotnet tool install Sitecore.CLI

C:\sitecore.cli> dotnet sitecore init

C:\sitecore.cli> dotnet sitecore plugin add -n Sitecore.DevEx.Extensibility.Serialization
Successfully installed version 4.0.0 of plugin Sitecore.DevEx.Extensibility.Serialization

C:\sitecore.cli> dotnet sitecore plugin add -n Sitecore.DevEx.Extensibility.ResourcePackage
Successfully installed version 4.0.0 of plugin Sitecore.DevEx.Extensibility.ResourcePackage

Convert Unicorn to Items as Resources

Overview

Currently (version 4.0.0) there are two sub-commands available.

  • unicorn - creates a new resource package from unicorn serialization folder,

    dotnet sitecore itemres unicorn -p "PowerShell" -o "PSPackage"  --overwrite
    
  • create - creates a new resource package from modules

    dotnet sitecore itemres create -o ../_out/output.name --overwrite -i  XA.Reference.*
    

where XA.Reference.* is a wildcard for your module names.

Complete documentation for all the commands and their options can be found here

Generate using modules

Personally, I prefer to use create command. Here are some pros and cons:

✅ you’ve got complete control on what goes into the resource file when using unicorn you cannot control it (filter certain items, split them into smaller modules)

❌ you have to synchronize modules definition (convert unicorn serialization configurations into modules)

Follow the examples below to convert your serialization configuration files into modules:

  • define the location of your module in sitecore.json
1
2
3
4
5
"modules": [
    "modules/*/*.module.json",
    "modules/*.module.json",
    "modules/*/*/*.module.json"
]
  • convert Unicorn serialization configuration to CLI modules

    Unicorn serialization file

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
    <sitecore>
        <unicorn>
            <configurations>
                <configuration name="XA.Reference.Project.Blog" description="" dependencies="XA.Reference.Project.Common" patch:after="configuration[@name='Foundation.Serialization']">
                    <targetDataStore physicalRootPath="$(sourceFolder)\Project\Blog\serialization" type="Rainbow.Storage.SerializationFileSystemDataStore, Rainbow" useDataCache="false" singleInstance="true" />
                    <predicate type="Unicorn.Predicates.SerializationPresetPredicate, Unicorn" singleInstance="true">
                        <include name="Content" database="master" path="/sitecore/content/SXA Reference/Blog"/>
                        <include name="Media Library" database="master" path="/sitecore/media library/Project/SXA Reference/Blog"/>
                        <include name="Themes" database="master" path="/sitecore/media library/Themes/SXA Reference/Blog"/>
                        <include name="Templates" database="master" path="/sitecore/templates/Project/SXA Reference/Blog"/>
                    </predicate>
                </configuration>
            </configurations>
        </unicorn>
    </sitecore>
</configuration>

CLI Module

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
    "namespace": "XA.Reference.Project.Blog",
    "items": {
        "path": "~/../src/Project/Blog/serialization",
        "includes": [
            {
                "name": "Content",
                "database": "master",
                "path": "/sitecore/content/SXA Reference/Blog",
                "scope": "ItemAndDescendants"
            },
            {
                "name": "Media Library",
                "database": "master",
                "path": "/sitecore/media library/Project/SXA Reference/Blog",
                "scope": "ItemAndDescendants"
            },
            {
                "name": "Themes",
                "database": "master",
                "path": "/sitecore/media library/Themes/SXA Reference/Blog",
                "scope": "ItemAndDescendants"
            },
            {
                "name": "Templates",
                "database": "master",
                "path": "/sitecore/templates/Project/SXA Reference/Blog",
                "scope": "ItemAndDescendants"
            }
        ]
    }
}

Automatic module generator

It’s not production-ready (not all the cases are handled) but it makes conversion a lot easier.

It takes as an input serialization file and creates a module for it.

You can find it here

Usage:

Get-ChildItem -Path '..\..\src\Foundation' -Recurse -Filter "*.Serialization.config" | % {
    .\Generate-Modules.ps1 -filePath $_.FullName -outputFolder "..\modules\Foundation"
}

Summary

If you are using Unicorn for serialization and want to deliver items as resource packages you can make it happen with minimal effort.

Sitecore Extensions version 3.4 released

Sitecore Extensions stands for Google Chrome extension for Sitecore CMS. It enhances CMS with extra addons which improve productivity and usability. Continue reading

Sitecore Extensions version 3.3 released

Published on April 16, 2020

SXA - Scaffolding debugging

Published on December 03, 2019