The CLI itemres command

Current version: 10.3

The Sitecore Items as Resources plugin includes an itemres command. This command creates an item package in a resource file with configurable options.

To install the Items as Resources plugin, run the following code:

RequestResponse
dotnet sitecore plugin add -n Sitecore.DevEx.Extensibility.ResourcePackage --version <version>

Usage

You can use the command as follows:

RequestResponse
dotnet sitecore itemres [subcommand] [options]

Subcommands

You can use the following subcommands:

  • create - creates a resource package.

  • unicorn - creates a Unicorn resource package.

  • cleanup - cleans up database items contained in .dat files if the item data in both entries are equal. This subcommand is available for CLI 4.1 or later.

The create subcommand

The create subcommand creates a new items and resources package. The CLI names the package based on the convention items.{databaseName}.{providedName}.dat.

You can use the following options with the create subcommand:

Option

Description

-o, --output <OUTPUT>

Required.

Package path to output (extension added if not provided).

--overwrite <OVERWRITE>

Overwrite an existing package.

-i, --include <INCLUDE>

Include module configurations. Wildcards and multiple values are allowed.

-e, --exclude <EXCLUDE>

Explicitly exclude module configurations. Wildcards and multiple values are allowed.

-c, --config <CONFIG>

Path to the root sitecore.config directory.

Default: current working directory.

-v, --verbose

Report additional diagnostic and performance data.

-t, --trace

Report additional diagnostic and performance data.

-?, -h, --help

Help for the command.

The following are examples of using the create subcommand:

Command

Result

dotnet sitecore itemres create -o TestPackage

Creates the items.{databaseName}.TestPackage.dat file. The file includes all modules.

dotnet sitecore itemres create -o test/TestPackage

Creates the items.{databaseName}.TestPackage.dat file in the test folder. The file includes all modules.

Attempt to create TestPackage with a duplicated name:

dotnet sitecore itemres create -o TestPackage

Does not create the package and returns with the following message:

RequestResponse
"The output path items.{databaseName}.TestPackage.dat already existed, but Overwrite was false."

Attempt to create TestPackage with a duplicated name:

dotnet sitecore itemres create -o TestPackage --overwrite

Creates and overwrites the package.

dotnet sitecore itemres create -o TestPackage -i Project.Content.Test

Creates the package and includes only the Project.Content.Test module.

dotnet sitecore itemres create -o TestPackage -i Project.Content.Test, Project.Content

Creates the package and includes only the Project.Content.Test and Project.Content modules.

dotnet sitecore itemres create -o TestPackage -i *Test

Creates the package and includes only the Project.Content.Test module; found with a wildcard prefix.

dotnet sitecore itemres create -o TestPackage -i *Test*

Creates the package and includes only the Project.Content.Test and Project.Content.Test1 modules; found with surrounding wildcards.

dotnet sitecore itemres create -o TestPackage -i Project*

Creates package and includes the Project.Content, Project.Content.Test, and Project.Content.Test1 modules; found with a wildcard suffix.

dotnet sitecore itemres create -o TestPackage -e Project.Content.Test

Creates package and includes only the Project.Content and Project.Content.Test1 modules, excluding the Project.Content.Test module.

dotnet sitecore itemres create -o TestPackage -e Project.Content.Test, Project.Content

Creates package and includes only the Project.Content.Test1 module, excluding the Project.Content and Project.Content.Test modules.

dotnet sitecore itemres create -o TestPackage -e *Test

Creates package and includes only the Project.Content and Project.Content.Test1 modules, excluding the Project.Content.Test module with a wildcard prefix.

dotnet sitecore itemres create -o TestPackage -e *Test*

Creates package and includes only the Project.Content module; excluding the Project.Content.Test and Project.Content.Test1 modules with surrounding wildcards.

dotnet sitecore itemres create -o TestPackage -e Project*

Creates package and excludes the Project.Content, Project.Content.Test and Project.Content.Test1 modules with wildcard suffix.

dotnet sitecore itemres create -o TestPackage -i Project* -e Project.Content.Test

Creates package and includes the Project.Content and Project.Content.Test1 modules with a wildcard suffix and excludes the Project.Content.Test module.

dotnet sitecore itemres create -o TestPackage -i Project.Content.Test -e Project.Content.Test

Does not create the package and returns with the following message:

RequestResponse
The include and exclude options contain the same modules at the same time

Attempt to create TestPackage from the samples folder:

dotnet sitecore itemres create -o TestPackage

Does not create the package and returns with the following message:

RequestResponse
error: Couldn't resolve a root configuration file (sitecore.json) in the current or any parent directory. Looks like the command might have been executed outside a Sitecore project?

Attempt to create TestPackage from the samples folder:

dotnet sitecore itemres create -o TestPackage -c Prototype/

Creates the package in the samples folder.

dotnet sitecore itemres create -o TestPackage -v

Creates additional diagnostic and performance data, such as a root config path or count of nodes with performance, for example, 73ms (8.1ms/node).

dotnet sitecore itemres create -o TestPackage -t

Creates additional diagnostic and performance data, such as FSIndex: Loaded filesystem indices in, for example, 70ms (9 metadata) or created package of 1 trees in, for example, 1983ms (9 items; 220.3ms/node).

The unicorn subcommand

The unicorn subcommand creates a new items and resources package from Unicorn serialization with the specific name format items.{databaseName}.{providedName}.dat.

You can use the following options with the unicorn subcommand:

Option

Description

-p, --path <INCLUDE>

Required.

Path to unicorn serialization.

-o, --output <OUTPUT>

Required.

Package path to output (extension added if not provided). Multiple values are allowed.

--overwrite <OVERWRITE>

Overwrite an existing package.

-c, --config <CONFIG>

Path to the root sitecore.config directory.

Default: current working directory.

-v, --verbose

Report additional diagnostic and performance data.

-t, --trace

Report additional diagnostic and performance data.

-?, -h, --help

Help for the command.

The following are examples of using the unicorn subcommand:

Command

Result

dotnet sitecore itemres unicorn -p "testItem" -o "TestPackage

Creates the items.{databaseName}.TestPackage.dat file.

The cleanup subcommand

The cleanup subcommand cleans up database items in .dat files if the item data in both entries are equal.

You can use the following options with the cleanup subcommand:

Option

Description

-f, --force

Force items cleanup without field comparison. Available from version 5.1.28.

-w, --what-if

Simulate items cleanup without deleting items. Available from version 5.1.28.

-p, --path

Sitecore Item path or GUID to cleanup. Required for Sitecore 10.3 if using the --force or --what-if options.

-r, --recurse

Recursively cleanup all items under the specified path.

-c, --config <CONFIG>

The path to the sitecore.json configuration file.

Default: cwd.

-n, --environment-name <ENVIRONMENT_NAME>

Named Sitecore environment to use.

Default: 'default'.

-v, --verbose

Report additional diagnostic and performance data.

-t, --trace

Report additional diagnostic and performance data.

-?, -h, --help

Help for the command.

Note

The --path and --recurse options are available for Sitecore 10.3 and later. The --force and --what-if options can be used in combination with --path for Sitecore 10.3 and later. Using --force and --what-if without specifying the --path is possible only in XM Cloud.

The following table shows an example of using the cleanup subcommand:

Command

Result

dotnet sitecore itemres cleanup

Output:

RequestResponse
Starting cleaning up databases. 
Processing...
Cleaning up databases is finished:
Cleanup of resource items is finished for 'master' database. Removed: 13 item(s).
Cleanup of resource items is finished for 'core' database. Removed: 3 item(s).

dotnet sitecore itemres cleanup --force

The command will not perform any action. You must provide a path with the --path option.

dotnet sitecore itemres cleanup --what-if

The command will not perform any action. You must provide a path with the --path option.

dotnet sitecore itemres cleanup --path /sitecore/content/ItemResCleanUpContent --force

Output:

RequestResponse
Starting cleaning up databases.
Processing...
Cleaning up databases is finished:
Cleanup of resource items is finished for 'master' database. Removed: 1 item(s).
[master] [D] /sitecore/content/ItemResCleanUpContent (6f0a7dcd-5a69-409f-bf58-8ee64eda4515)
Cleanup of resource items is finished for 'web' database. Removed: 0 item(s).
Cleanup of resource items is finished for 'core' database. Removed: 0 item(s).

Do you have some feedback for us?

If you have suggestions for improving this article,