Description

When developing a module for Sitecore CMS that is going to be shared with a wider public or customizing the Sitecore functionality, the following implementation specific questions may arise:

• What are the common rules for module implementation?
• How to avoid most typical architecture mistakes?
• How not to mix up the module parts with other Sitecore components?

This article provides some basic and generally suggested practices to cover these and some other questions that Sitecore developers may have.

Best Practices

Architecture

• Avoid using web services for communication between instances because they might be protected by firewalls that don't allow inbound or outbound connections. Use the EventQueue mechanism instead.
• Keep in mind the performance of your module in case of a high load, perform load testing. This should guarantee the stability of your module on production instances.
• Make your module culture independent because there is always a chance that it will run in a context of a different culture.

Code

• Use Sitecore naming conventions for assemblies, namespaces, classes, methods, properties, and fields. This will make the module look and feel native.
  For example:

  Sitecore.<ModuleName>.Pipelines.HttpRequest.ProductResolver, Sitecore.<ModuleName>

• Use the Sitecore.Diagnostics.Assert class for asserting method arguments, variables and any other data before using them. This will help to troubleshoot your module if any issues appear.
• Use .NET Framework 3.5 if possible because there are many sites using Sitecore CMS 6.x that run on this version of .NET Framework.
• Avoid using private, internal, static and not-virtual methods as this makes customization and patching more difficult.
• Introduce pipelines and factories to make your module customizable.
• Always keep Sitecore customization to minimum because it makes your module more fragile and Sitecore version dependent.
• When needed, use Reflection to access private or internal Sitecore components rather than copy-paste their decompiled source code because there is a lower chance that a class name or class member name will change.
• Always use the Sitecore.Context.Database and Sitecore.Content.ContentDatabase properties to access the "web" and "master" databases as these databases might have different names on different solutions.
• Keep in mind possible failures of your module and wrap the code in try/catch blocks to prevent the entire Sitecore malfunctioning.
  Always provide the detailed error information in case of failures, e.g. provide all the information available in the exception object in case of exceptions:

  try 
  {
    ... 
  }
  catch (Exception ex)
  {
    Log.Error("<ModuleName> caused an unhandled exception", ex, this); 
  }

• When using fields and properties in classes that represent pipeline processors be aware that the same processor instance might be reused by different requests.

Items

• Place module specific layout items as well as views, renderings and sublayouts in /sitecore/layout/Layouts/Modules/<ModuleName>.
• Store module specific templates in the /sitecore/templates/Modules/<ModuleName> item-folder.
• Avoid modifications of default Sitecore items and templates unless absolutely necessary.
• If you need to extend the Standard Template with custom fields, do it according to the steps below:
  1. Create a section template beneath the /sitecore/templates/System/Templates/Sections item and set {00000000-0000-0000-0000-000000000000} as a base template.
  2. Add necessary fields to the section template.
  3. Add the section template to the list of base templates for the /sitecore/templates/System/Templates/Standard template.

Settings

• The settings that are supposed to be relatively constant and changed only by developers/administrators should be stored in configuration files.
• Use the /App_Config/Include/Sitecore.<ModuleName>.config file to store module specific settings and to patch the Sitecore configuration.
• Settings that are going to be changed often or contain links to Sitecore items should be stored in items to make use of the Links Database and the Broken Links report.
• Settings items should be located in the /sitecore/system/modules/<ModuleName> item-folder.
• Site-specific settings in multisite solutions should be stored in either the <site name="website" ... /> configuration element or the /sitecore/content/website/<ModuleName>Settings item referenced by the <site name="website" <moduleName>Settings="/sitecore/content/website/<ModuleName>Settings" /> element.

Package

• Avoid using post step install actions that interact with a user, as it prevents a module from being installed automatically with script.
• Avoid using post step install actions for installing nested or dependent Sitecore Packages as it prevents control of conflict situations.