Integrate custom code

When customizing or extending Xperience, developers often need to add code files (classes). Classes are required when integrating custom services (interface implementations) or other components.

Instead of adding classes directly into the main web project, create the files as part of a separate Class Library project (assembly). Custom assemblies provide a cleaner separation of code and better reusability between different projects.

Group project assemblies within a solution

If you have not yet done so, we recommend creating a solution file for your project. Solutions allow you to track multiple assemblies within a single workspace, and to easily reference, navigate, and structure your codebase.

To create an assembly for custom classes in your Xperience solution:

  1. Open your Xperience solution in Visual Studio.
  2. Create a new Class Library project in the solution.
  3. Add the Xperience API libraries to the project:
    1. Right-click the solution in the Solution Explorer and select Manage NuGet Packages for Solution.
    2. Select the desired package (e.g. Kentico.Xperience.Core).
    3. Install the package into the project (the version must match your main web project’s Kentico.Xperience.WebApp package).
  4. Reference the project from your main web project.

You can now add your custom classes under the created class library project.

Enable class discovery

In many cases, the system needs to detect and process custom classes on application start. For example, this is required for all custom classes registered using an attribute, such as RegisterImplementation, RegisterModule, etc. 

To allow class discovery, you need to add the AssemblyDiscoverable assembly attribute to your Class Library project. We recommend using the following approach:

  1. Create a dummy class within your project, for example, AssemblyAttributes.cs.

  2. Add the AssemblyDiscoverable assembly attribute:

     using CMS;

The attribute ensures that Xperience processes your assembly on application start and discovers all contained custom classes that are properly registered.

Adding the assembly attribute to the csproj file

Adding assembly attributes to code files has advantages, such as proper compilation, warnings about potentially obsolete API, etc. However, if you do not wish to create a dummy class for this purpose, you can alternatively edit your project’s csproj file and add the assembly attribute there:

    <AssemblyAttribute Include="CMS.AssemblyDiscoverableAttribute">