The CLI itemres command

Abstract

Description of the DevEx CLI itemres command that creates an item package in a resource file with configurable options.

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 4.0.0

Note

This command is available from CLI 4.0 or later.

Usage

You can use the command as follows:

dotnet sitecore itemres [subcommand] [options]

Subcommands

You can use the following subcommands:

  • The create subcommand - creates a resource package.

  • The unicorn subcommand - creates a Unicorn resource package.

  • The cleanup subcommand - 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 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

Required?

Description

-o, --output <OUTPUT>

Yes

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

--overwrite <OVERWRITE>

No

Overwrite an existing package.

-i, --include <INCLUDE>

No

Include module configurations. Wildcards and multiple values are allowed.

-e, --exclude <EXCLUDE>

No

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

-c, --config <CONFIG>

No

Path to the root sitecore.config directory. Default: current working directory.

-v, --verbose

No

Report additional diagnostic and performance data.

-t, --trace

No

Report additional diagnostic and performance data.

-?, -h, --help

No

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 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 may 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 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

Required?

Description

-p, --path <INCLUDE>

Yes

Path to unicorn serialization.

-o, --output <OUTPUT>

Yes

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

--overwrite <OVERWRITE>

No

Overwrite an existing package.

-c, --config <CONFIG>

No

Path to the root sitecore.config directory. Default: current working directory.

-v, --verbose

No

Report additional diagnostic and performance data.

-t, --trace

No

Report additional diagnostic and performance data.

-?, -h, --help

No

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 cleans up database items contained in .dat files if the item data in both entries are equal.

Note

This subcommand is available for CLI 4.1 or later.

You can use the following options with the cleanup subcommand:

Option

Required?

Description

-c, --config <CONFIG>

No

The path to the sitecore.json configuration file. Default: cwd.

-n, --environment-name <ENVIRONMENT_NAME>

No

Named Sitecore environment to use. Default: 'default'.

-v, --verbose

No

Report additional diagnostic and performance data.

-t, --trace

No

Report additional diagnostic and performance data.

-?, -h, --help

No

Help for the command.

You can use the following options with 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 'web' database. Removed: 19 item(s).
Cleanup of resource items is finished for 'webpreview' database. Removed: 17 item(s).
Cleanup of resource items is finished for 'core' database. Removed: 3 item(s).