Xperience Manager (xman)

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 Kentico.Xperience.Manager -g

Updating the tool

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

dotnet tool update Kentico.Xperience.Manager -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": "5.0.0.0",
  "Profiles": [
    {
      "ProjectName": "xbk29",
      "WorkingDirectory": "c:\\inetpub\\wwwroot\\xbk29"
    }
  ],
  "CurrentProfile": "xbk29",
  "DefaultInstallProjectOptions": {
    "Version": null, // Version cannot have a default value
    "Template": "kentico-xperience-sample-mvc",
    "ProjectName": "my-project",
    "InstallRootPath": "c:\\inetpub\\wwwroot",
    "UseCloud": false
  },
  "DefaultInstallDatabaseOptions": {
    "UseExistingDatabase": false,
    "DatabaseName": "xperience",
    "ServerName": "my-server"
  },
  "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
d, delete
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.

The installation wizard will automatically generate an administrator password for you, but you can enter your own password during installation if needed.

Run the install command from the directory containing the configuration file which will begin the installation wizard:
```
xman install
```

Installing a new project automatically includes a database as well. If you want to only install a database and not the project files, use the db parameter: xman install db.

Updating a project version

(optional) Select a profile with the profile command
Run the update command from the directory containing the configuration file, which will begin the update wizard:
```
xman update
```

Deleting a project

⚠️ The delete command will drop the database and delete the files. Use with caution!

(optional) Select a profile with the profile command
Run the delete command from the directory containing the configuration file:
```
xman delete
```

Modifying appsettings.json

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

(optional) Select a profile with the profile command
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.

(optional) Select a profile with the profile command
Run the macros command from the directory containing the configuration file, which will begin the macro wizard:
```
xman macros
```

Building projects

(optional) Select a profile with the profile command
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.

(optional) Select a profile with the profile command
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.

(optional) Select a profile with the profile command
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.

Select a profile with the profile command. This determines which configuration file is modified
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:

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

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:

Select a profile with the profile command. This determines which project's database is updated
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
```

Support

This project has Kentico Labs limited support.

See SUPPORT.md for more information.

For any security issues see SECURITY.md.