Xperience Manager (xman)

⚠️ This repository has been moved here

This tool simplifies the process of installing and managing Xperience by Kentico instances by providing step-by-step wizards with default options provided.

Installing the tool

Run the following command from a command prompt such as Powershell:

dotnet tool install Xperience.Xman -g

Updating the tool

Run the following command from a command prompt such as Powershell:

dotnet tool update xperience.xman -g

Getting started

This tool can be run from anywhere, as long as the directory contains the configuration file. If there is no configuration file, a new one will be created when you run the tool. When you install a new instance, a new profile is created in the configuration file, allowing you to manage multiple installations without changing directory.

Configuration file

The xman.json file contains information about the tool, your default options, and profiles. This file will be automatically created if it doesn't exist when you run a command like xman p.

{
  "Version": "3.1.0.0",
  "Profiles": [
    {
      "ProjectName": "28dev",
      "WorkingDirectory": "C:\\inetpub\\wwwroot\\28dev"
    }
  ],
  "CurrentProfile": "28dev",
  "DefaultInstallOptions": {
    "Version": null, // Version cannot have a default value
    "Template": "kentico-xperience-sample-mvc",
    "ProjectName": "myproject",
    "InstallRootPath": "C:\\inetpub\\wwwroot",
    "UseCloud": false,
    "DatabaseName": "xperience",
    "ServerName": "my-server",
    "AdminPassword": "mypassword"
  },
  "CDRootPath": "C:\\inetpub\\wwwroot\\ContinuousDeployment"
}

You can edit this file to change the DefaultInstallOptions used when installing new Xperience by Kentico projects, and the location of the Continuous Deployment files.

Usage

The following commands can be executed using the xman tool name:

• ?, help
• i, install
• u, update
• m, macros
• b, build
• g, generate
• s, settings
• ci <store> <restore>
• cd <store> <restore> <config>
• p, profile <add> <delete> <switch>

Managing profiles

Certain commands such as update are executed against the installation indicated by the current profile. The profile command shows you the current profile, and allows you to switch profiles. If you only have one profile, that is automatically selected.

To switch profiles, run the profile command from the directory containing the configuration file:

xman profile

You can add or delete profiles using the corresponding commands. This can be useful to register Xperience by Kentico installations that weren't installed using the tool.

xman p add
xman p delete

Installing a new project

When installing a new project, a new folder will be created in the InstallRootPath of the configuration file, or in a custom directory that you specify in the installation wizard. After installation, a new profile is created for the instance.

1. Run the install command from the directory containing the configuration file which will begin the installation wizard:

   xman install

Updating a project version

1. (optional) Select a profile with the profile command

2. Run the update command from the directory containing the configuration file, which will begin the update wizard:

   xman update

Modifying appsettings.json

This tool can assist with changing the CMSConnectionString, supported configuration keys, and the headless API.

1. (optional) Select a profile with the profile command

2. Run the settings command from the directory containing the configuration file, which will begin the settings wizard:

   xman settings

Re-signing macros

See our documentation for more information about macro signatures and the available options.

1. (optional) Select a profile with the profile command

2. Run the macros command from the directory containing the configuration file, which will begin the macro wizard:

   xman macros

Building projects

1. (optional) Select a profile with the profile command

2. Run the build command from the directory containing the configuration file to build the current profile's instance:

   xman build

Generating code for object types

See our documentation for more information about code file generation.

1. (optional) Select a profile with the profile command

2. Run the generate command from the directory containing the configuration file which will begin the generation wizard:

   xman generate

Running Continuous Integration

You can use the ci command to serialize the database or restore the CI repository to the database. Your project must have been built at least once to run CI commands.

1. (optional) Select a profile with the profile command

2. Run the desired command from the directory containing the configuration file to begin the CI process:

   • xman ci store
   • xman ci restore

Running Continuous Deployment

This tool can help you manage a local Continuous Deployment environment. For example, if you are self-hosting your website and you have DEV and PROD Xperience by Kentico instances, the tool simplifies the process of migrating database changes from lower environments to production.

You can customize the location of the CD files by changing the CDRootPath property in the configuration file:

{
    "CDRootPath": "C:\\XperienceCDFiles"
}

Your project's CD configuration file is automatically created when you run the cd command and can be manually edited to fine-tune the CD process. You can also run the config command to edit the configuration file using a wizard. For example, you may want to change the RestoreMode before restoring CD data to the database.

1. Select a profile with the profile command. This determines which configuration file is modified

2. Run the config command from the directory containing the configuration file, which will begin the configuration wizard:

   xman cd config

When you are finished development and wish to serialize the CD data to the filesystem, use the store command:

1. Select a profile with the profile command. This determines which project's database is serialized

2. Run the store command from the directory containing the configuration file:

   xman p # switch to DEV profile
   xman cd store # serialize DEV database

To migrate the changes from development to production, run the restore command:

1. Select a profile with the profile command. This determines which project's database is updated

2. Run the restore command from the directory containing the configuration file. The tool will display a list of profiles to choose as the source for the restore process (in this example, the DEV profile):

   xman p # switch to PROD profile
   xman cd restore # restore DEV CD files to PROD database