The CLI itemres command

Version:

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:

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

Usage

You can use the command as follows:

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:

"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:

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:

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.

Warning

This command triggers a full cache cleanup, and it can cause performance degradation. It should be executed during a maintenance window.

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. Tip This option can be used to determine whether an item would be overridden, and to identify its storage location.
`-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.

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

Command: Result
dotnet sitecore itemres cleanup: Output:


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: Output:


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/item1 (3d8f6795-1c4e-462d-8a81-be27b1aec5bd)
Cleanup of resource items is finished for 'core' database. Removed: 1 item(s).
[core] [D] /sitecore/content/item1 (3d8f6795-1c4e-462d-8a81-be27b1aec5bd)

dotnet sitecore itemres cleanup --what-if: Output:


What if mode is active. No changes will be made.
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 'core' database. Removed: 0 item(s).

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


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 'core' database. Removed: 0 item(s).

If you have suggestions for improving this article, let us know!