Adding custom assemblies

✖
Copy to clipboard

When customizing or extending Xperience, developers often need to add code files (classes). Classes are required when integrating custom services (interface implementations) and components, such as scheduled tasks or modules.

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

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 Kentico.Xperience.Libraries package.
    3. Install the package into the project (the version must match your MVC live site project’s Kentico.Xperience.AspNet.Mvc5 package and the exact hotfix version of your Xperience administration project).
  4. Reference the project from your web projects (live site and/or administration).

You can now add your custom classes under the new project.

Custom code added to the Xperience administration application does not automatically apply to your live site application and vice versa. For every customization, you need to consider which applications should be affected and deploy your custom assemblies accordingly.

See: Applying customizations in the Xperience environment

Enabling 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. Edit your project’s AssemblyInfo.cs file (in the Properties folder)

  2. Add the AssemblyDiscoverable assembly attribute:

    using CMS;

[assembly:AssemblyDiscoverable]

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