.png?width=667&height=667&ext=.png)
How to Setup Debugging for Custom Event Handlers in Kentico CMS and Visual Studio 2010
This post applies to using Kentico CMS 5.5+ and Visual Studio 2010. It may seem a bit basic to some veteran Kentico developers, but I had to show a few co-workers the ins and outs of setting up a solution the right way. Once they had it, they were able to debug through a local project that contained both the core Kentico code and the extra sample code for creating a custom event handler.
You might have a question on what exactly a CustomEventHandler is for Kentico. Well it is basically an avenue that once you have it setup you can extend and customize Kentico to do things that it can’t do out of the box. There are a multitude of events that your code can subscribe to and give you the ability to do whatever you want on almost any action in the CMSDesk and beyond.
The first part of the process involves installing the base product from Kentico. If you don't have it already, go ahead and grab the download of the Web Installer from Kentico's site. Once you get it downloaded double click on KenticoCMS_5_5.exe. Click Next at the welcome screen and accept the licensing terms, and then you should be asked for a location to extract the download to. I generally leave the default path alone, for the most part it makes sense to put it in Program Files. Click Next after you have chosen your path and it will extract to that location. After that is done we get to the interesting part. You should now be at a screen like:
There are a couple options for how to install the Kentico Product, but for the purposes of this post we are talking about using the ASP.Net Framework version 4.0 and Visual Studio 2010. Choose the first option and click Next.
Next we are asked the location of where we would like the code for Kentico CMS to be installed. For our purposes we want to choose the second option, I want to use the built-in web server in Visual Studio 2010.
The next option is where we would like to place the code that we will be running locally.
After that we are presented with a choice of Full Installation or Custom. Go ahead and pick the Full option, it includes everything, especially the Custom Event Handler starter code that we need.
After clicking next the installation will really kick in and copy all the files you need. Go grab a cup of coffee because this step takes some time. There are a lot of files to copy.
If it all works out, and it should you should finish up at a screen that says complete and has a link to your new solution.
Click that link to open up your solution in Visual Studio 2010. The solution that the web installer created should open up and it should be fairly easy to see that there is one web site already part of the project that contains all the code required to run a Kentico CMS site. Pressing F5 will start the web site up via the built in Visual Studio 2010 web server and start you on your way to debugging.
Now the first time you run the code you will be asked to setup the database for a new installation of Kentico. That is sort of outside the scope of this post, and Kentico has a great support document already created that you can check out for help with if you need it. But at this point we have successfully installed the core product locally and can debug it.
Now that we have the base solution and website ready lets get into the real reason we are here though. And that reason is how do we add on the Custom Event Handler starter code so that we can customize various events inside the Kentico system.
Head back on over to the location of which you installed Kentico to on you drive. If you notice in the root Kentico folder there is a sub folder called CodeSamples. Inside that folder is where our target code lies.
Since I’m a C# guy I will be choosing the project CustomEventHandler in here. That folder contains a class library project that has some starter code for us. Now back to the Visual Studio environment. Go ahead and right click on the Solution named Kentico5-5 in the Solution Explorer and add in an Existing Project. When the browse window comes up choose the CustomEventHandler.csproj file in your CodeSamples/CustomEventHandler folder that we just mentioned.
Now at this point the tricky part comes in with the fact that the Sample Code is a bit old. Hint, hint Kentico devs! Visual Studio will want to convert the project to a .NET Framework version 4.0 project and set the target framework property for you via the Conversion Wizard. Just click Finish and ignore the conversion log.
At this point you are probably saying great, why do I now have like 14 warnings and the thing doesn't look like it will build. That’s because the the reference names are wrong for the sample code.
Just go ahead and right click remove the broken references below
- CMSHelper
- DataEngine
- GlobalEventHelper
- GlobalHelper
- SettingsProvider
- SiteProvider
- TreeEngine
And after that add back in the correct ones from the list below. The files can commonly be found in your new bin directory normally located at C:\InetPub\wwwroot\KenticoCMS-5-5\Bin\
- CMS.CMSHelper.dll
- CMS.DataEngine.dll
- CMS.GlobalEventHelper.dll
- CMS.GlobalHelper.dll
- CMS.SettingsProvider.dll
- CMS.SiteProvider.dll
- CMS.TreeEngine.dll
As you add back in references you will probably get a strange error talking about .NET Framework versions. Answer Yes to that. It will convert the reference to correctly use version 4.0.
After you fix up all the references your complete solution should build.
Next, to be able to debug into the Custom Event Handler code, you will need to add a reference from the output of the class library project to the Kentico website in the solution. So on the bin directory right click it and choose Add a Reference. Then select the Projects tab and choose the only one in there, CustomEventHandler. This will tie the two projects together.
I should mention here that at this point if anything went wrong, like the project still isn't building go ahead and double check the target framework of the class library project (Right-Click Properties on the project) and make sure the Target Framework is set to .NET Framework 4 like below.
Next we need to let the instance of Kentico know that we are using CustomEventHandlers. To do so we need to add an application setting in the root web.config like so:
As Kentico states in the documentation for this key you may change the name of this key also. Check out the docs here for how to do that.
Save and close your web.config and you should be all set with that. There is one last step we need to do, and that is set a break point on some code. One of the most common methods to use in the CustomEventHandler is the OnAfterUpdate method in the CustomTreeNodeHandler class. Add in the two lines below to have something to test with into the method. Set your breakpoint on the second line.
/// Summary
/// Fires after updating tree node in the tree. Performs the additional actions after the tree node is updated.
///
///TreeNode object to update in tree
///TreeProvider object to use
public override void OnAfterUpdate(object treeNodeObj, object tree)
{
// INSERT YOUR CUSTOM AFTER-UPDATE CODE
TreeNode node = (TreeNode)treeNodeObj;
string nodeName = node.NodeName;
}
Set the web site as the Startup Project and then go ahead and hit F5 to run the solution. Since this is the second time you have run the site you should not be prompted to setup a database again. You should go to the default page of the site you first created. Login to the CMSDesk and then edit a page in the Document Tree. As soon as you click the Save button the OnAfterUpdate event should fire on your updating TreeNode and debugger should pick it up.
I hope this tip helps you out. I think my co-worker owes me a beer for writing this all out for him.
