Use the Fully Qualified Name When Using a Sitecore MVC Controller Sitecore Best Practice

The Best Practice for using a Sitecore MVC Controller is to use the Fully Qualified Name and Assembly for the Controller. Hopefully Sitecore will add this to the Sitecore MVC Developer’s Reference Guide (requires a SDN account).

I started working with a new customer on a Sitecore 7.2 MVC project and they were trying to utilize a Controller from a separate “shared” assembly. After much searching with no luck, I then started down the path that every developer typically jumps to, too quickly, and was looking into a code based solution. My initial thoughts was that it was going to require something similar to the Usercontrol renderings in a Sitecore MVC website (aka Web Forms for Marketers v2.3 MVC fix). Then out of the blue, I found two articles that helped lead me down this simple NO CODE solution!

First, I stumbled across the comments of @KevinPBuckley on this blog post about using MVC Areas in Sitecore

“You can use a fully qualified path to you your controller. That helps to allow duplicate controllers and actions in different areas. Sample : Sample.Areas.SampleArea.Controllers.AccountController,Sample”

Then I happened to see this blog post from my esteemed colleague Zac Malmquist regarding Sitecore MVC and Duplicate Controller Names on my companies own blog of all places.

There were two things that bothered me. First, that these simple solutions to using a controller from a different assembly was so hard to find in my searching. I wasn’t using the right magic keyword combinations. In my defense, these two blog posts provide even deeper and more specific solutions than just “using a Controller from a different assembly”. Second, that I even went back and looked at the Sitecore MVC Developers Documentation at least three or four times and it didn’t mention any of this or provide any useful examples.

In my opinion, not only should this have been documented, it should be a “Best Practice” instead of what the documentation shows as simply “Controller — Specifies the name and action of a controller”. In fact, the best practice should be worded exactly as Zac worded it with a couple of adjustments and one little extra sentence:

“Do not use simple controller names in controller and view renderings, but instead use the fully qualified path to your controller. That means instead of – ControllerX use the fully qualified path of – ProjectA.Controllers.ControllerX, ProjectA(.dll) . This will guarantee uniqueness with all your controller references and allow using controllers from a different assembly.”

This will also help avoid the error message:
The controller for path '/XXX was not found or does not implement IController.

Description: An unhandled exception occurred during the execution of the current web request. Please review the stack trace for more information about the error and where it originated in the code.

Exception Details: Sitecore.Mvc.Diagnostics.ExceptionWrapper: The controller for path '/XXX was not found or does not implement IController.

Source Error:

An unhandled exception was generated during the execution of the current web request. Information regarding the origin and location of the exception can be identified using the exception stack trace below.

The wrong way to enter Controller information for Controller Rendering (while it will work in some environments, it has risks as described above):

The right way to enter Controller information for Controller Rendering:

The wrong way to enter Controller information for View Rendering (while it will work in some environments, it has risks as described above):

The right way to enter Controller information for View Rendering:

Again, ideally Sitecore will one day add these details into the Sitecore MVC Developer’s Reference Guide, so that at least this risk and the solution is readily found for everyone. As I have seen from experience that it will and should be a very common occurrence while developing enterprise solutions with an enterprise platform such as the Sitecore Experience Platform.

(In my humble opinion, as a minimum, this should be used in more examples and easier to find.)