Troubleshooting in Kentico

When you're developing solutions in Kentico, things can go wrong. There might be something strange happening, and you're not sure how to fix it. Here, I'm going to outline my usual troubleshooting steps and some common problems I've encountered during my time developing in Kentico. 

My troubleshooting steps

At a basic level, I'll do the following things:

• Check the EventLog
• Debug through your custom code in Visual Studio to catch any errors that were not logged or were hidden from the browser. Double check that the result of your queries are returning what you expect. If your breakpoints aren’t being hit, the result of your code may be cached.
• Clear the cache. Both the browser and System > Clear cache. Kentico caches a lot under the hood, and can sometimes lead to unexplained behaviour where webparts aren’t updated.
• Check the Kentico database to see if there are any inconsistencies in the data.
• Clean and rebuild your Visual Studio solution
• Restart Visual Studio
• If I'm facing a problem that a restart won't fix, I'll move on to checking what I can do. First, I check Kentico's available methods and extensions to see if there is something I've missed.
• If it still doesn't work, at this point I will check what Kentico does in similar scenarios. I like to look at Kentico's aspx pages, webparts and transformations to see if I can determine the right way to do something.
• My best advice for solving problems is "Try everything". Even if it seems small and silly, try everything.

Common problems

Your custom code isn't loading, or your event handlers aren't triggering 

It’s generally best to put your custom modules, providers and event handlers in a separate assembly. You may find that when you start doing this, your custom code might not run. e.g. event handlers you set up in a custom module don’t get triggered, initialisation code never runs, or your custom version of a default provider is not loaded. This could be because your class library needs the [assembly: AssemblyDiscoverable] attribute included in your "AssemblyInfo.cs" file. After you do that, you can check that your custom code is being run by adding breakpoints to it. If they get hit when you’re debugging, your module or custom provider is being loaded by Kentico.

using System.Reflection;

using System.Runtime.CompilerServices;

using System.Runtime.InteropServices;

using CMS;

// Marks this assembly discoverable by Kentico

[assembly: AssemblyDiscoverable]

// General Information about an assembly is controlled through the following

// set of attributes. Change these attribute values to modify the information

// associated with an assembly.

[assembly: AssemblyTitle("MySite.Common.Kentico")]

...

 'I can't see my custom admin'

Always check that the role that needs to use your custom admin can see it by logging in, or impersonating a user with just that role. There could be many reasons why you can't see your new module UI in the admin. I like to check the following things.

• Have you refreshed the whole page?
• Your module should be assigned to the site
• In “Modules > {Your module} > Permission names”, there needs to be a “Read” and “Modify” permission
• The role you’ve created to access the module needs to have your module’s “Read” and “Modify” permission assigned to it
• Make sure you have a UI element in Modules > {Your module} > User Interface and that it points to the correct file or URL of your custom admin page. 
• In the Roles > UI Personalization > Administration area, confirm that you've checked all the boxes leading up the tree from your custom UI
• If you are using a custom .aspx page, have you added an assembly attribute that refers to the namespace of your UI element as defined in Modules > {Your module} > User Interface on the “General” tab? E.g. [UIElement("MyCustomModuleCodeName", "MySite.MyModuleName.MyUIElementName")]

Document queries and object queries not returning expected results

When selecting nodes and objects in Kentico using Kentico’s providers, you’ll be writing document queries and object queries. If your custom queries aren’t returning the results you expect, the easiest way to figure out why is to run them in debug in Visual Studio.  Here is some general advice when troubleshooting document and object queries.

• Split up your query to check the result at each step.
• Make good use of C#’s Immediate and Watch windows to check results during run time.
• Remove query clauses one by one to find which part is causing the problem
• Calling ‘.ToString()’ on the clause at any time gives you the SQL statement being run. Copy the SQL statement, replace the parameters with actual values and run them against the Kentico database in SQL Server Management Studio.
• Always use ‘OnCurrentSite()’ in document queries, especially if you are calling your query from a console app or a scheduled task with no explicit site context.
• Consider if you are expecting the current published version (this is selected by default), or want to include unpublished pages and the latest edit using ‘.Published(false)’
• Are you querying for a particular culture? Are your pages are in a different culture because you’ve forgotten to change the default culture when you set up your website?

Another ‘gotcha’ we’ve come across in Kentico is that setting a ‘default’ value on a page or custom table field does not necessarily mean that the value gets set in the database, so be aware of null values in columns with ‘default’ values.

Unusual content rendered from webparts and widgets 

When there is unexpected website behaviour, the first thing we check is whether there are any 'Macro Security Errors' in the Event Log. Macro security errors show us that certain macros on the site are not running. 

When those macros are used to set a dynamic property on a widget or webpart, it could cause content to render strangely, or not at all. We fix these errors by resigning all of our macros under the ‘Global Administrator’ account. To do this, log in to the CMS as the default 'Global Administrator', go to System > Macros > Signatures, check the Old salt: "Sign all macros" and click "Update macro signatures".