Install a specific version of Xperience by Kentico
During the creation of an Xperience by Kentico instance, when you install Kentico.Xperience.Templates without any further specification, the .NET CLI will automatically pull down the newest version.
While this is typically the desired behavior, you may encounter situations where you need to install an older version. For example, your company already uses a given version or has a lengthy approval process.
This guide demonstrates installation of an exact version of Xperience by Kentico, using the boilerplate project. We’ll work with version 29.6.1 as an example, though you can substitute any valid version number and simply use this guide as a reference.
See the list of all valid version numbers in the documentation’s Changelog page.
Before you start
To follow along with this guide, we recommend your machine has the following installed:
- .NET 8.0
- Microsoft SQL Server 2022 (or compatible version, such as the free SQL Server Express Edition)
- an IDE that supports ASP.NET Core development, such as Visual Studio or Visual Studio Code
Check your existing template versions
In the .NET CLI, the dotnet new command is used to install NuGet template packages, such as Kentico.Xperience.Templates.
Running this command’s uninstall argument without specifying what to uninstall brings up a list of the currently installed template packages.
dotnet new uninstall
If you have previously installed multiple versions of Kentico.Xperience.Templates, you’ll notice that all of them appear in the list, but only the most recently installed one includes a Templates subsection with a list of specific template names. This is the version the system is currently actively using. For example:
To clean up and uninstall all templates from your machine you can run:
dotnet new uninstall kentico.xperience.templates
Install the required version of templates
Run the following command in your terminal to install the 29.6.1 version of Kentico.Xperience.Templates:
dotnet new install kentico.xperience.templates::29.6.1 --force
The --force parameter will ensure the target version is installed correctly, in case you have other Xperience templates on your machine (for example after playing around with the latest version).
If you already have the desired version of Kentico.Xperience.Templates installed (in this case 29.6.1), feel free to skip this step.
Now, with the proper template package installed, you can create projects using the Xperience templates.
Create a project
Creating the project also relies on the .NET CLI, which will fill the provided folder with project files for the presentation layer of your site.
Navigate to the folder that you want to hold this project’s repository.
Add a src folder within it, and a TrainingGuides.Web folder within the src directory.
Open a command window in the TrainingGuides.Web directory and create a new project called TrainingGuides.Web.:
dotnet new kentico-xperience-mvc -n TrainingGuides.Web
This project will be the top-level MVC project, responsible for the site’s presentation, but it will not be the only project in the solution.
Agree when prompted to run a restore command.
After the run is successful, you will see a new .NET project generated in your TrainingGuides.Web folder. Navigate one level up and create a new folder called License in the src directory.
Add a file called license.txt with the content of a valid license key.
Getting your license key
You can obtain the license key from your agency, supervisor, or team lead.
Alternatively, you can create an account at the Client Portal, and generate a temporary key valid for 30 days.
Learn more about licensing in our documentation.
Add a solution to the project. This will allow other projects to be created to work in tandem and keep things organized.
Some IDE’s, like Visual Studio Code with the C# Dev Kit extension, will generate the solution file automatically after you open the project. We recommend saving the solution directly in the src folder, one level up from TrainingGuides.Web.
If you are using Visual Studio:
- Open TrainingGuides.Web.csproj in Visual Studio, and highlight the auto-generated solution in the solution explorer.
- Click on File, and choose Save TrainingGuides.Web.sln as from the dropdown.
- Navigate to the src folder, and rename the file to TrainingGuides.sln, then click Save.
Connect the database
For the next step, let’s install the database.
Remember to replace the <sql_server_name> placeholder to match your SQL server before you run the following command.
dotnet kentico-xperience-dbmanager -- -s "<sql_server_name>" -a "TrainingGuides123*" -d "Xperience.TrainingGuides" --hash-string-salt "59642433-67b2-4230-9c5b-ad98d02b0c72" --license-file "..\License\license.txt"
Note the information specified with each parameter, which you can change if you are using this as a reference rather than following along.
-s- The SQL server where the database should be installed
-a- The password for the administrator account when accessing the administration interface
-d- The name given to the database in the SQL Server
--hash-string-salt- The CMSHashStringSalt value is used for signing macros stored in the database
--license-file- The path to a text file containing your license key
For more details about parameters and configuration options, visit our documentation.
Once the database finishes installing, run the site and visit the /admin path. Log into your Xperience by Kentico instance with the username administrator and the password specified in the command above.
Site not configured message
When the site loads, you should see a message that says something like this:
The TrainingGuides.Web site has not been configured yet.
This is okay; you can still access the administration interface. You can remove this message later when you add content and develop page templates.
After successful login, the app will navigate you to the Xperience administration dashboard, the interface content editors use to perform their daily tasks. As a developer, you will use the administration dashboard to configure and customize Xperience by Kentico according to your company’s business needs.
What’s next?
Now you have a fresh boilerplate project running on your specified version, so you can get started with development!
Check out also our Xperience Manager (xman) tool, which can help you simplify installing and managing Xperience by Kentico instances in future projects.