Best practices for creating new Commerce plugin projects
Plugins are the main way to customize Commerce Engine functionality to meet the needs of an e-commerce solution. A Commerce Engine plugin contains all the required classes that make up a piece of functionality. This section provides best practices and tips to help you create new Commerce plugin projects to implement custom functionality.
Create a new plugin in your solution for each new functional area
When you implement custom functionality, you must create a new plugin in your solution for each new functional area, or for each standard functionality that you need to modify to meet specific requirements. For example, if you are modifying existing pipelines or replacing pipeline blocks to change default business logic that the sitecore.commmerce.plugin.catalog plugin provides, create your own plugin for the corresponding functional area. A Commerce solution typically defines its own plugins containing its customization. Name your custom plugin project in a way that reflects the area of functionality you are extending.
Only add artifacts of the same functional area to your plugin project
When you create a new plugin to implement custom functionality, do not include in your plugin elements that belong to different functional areas.
For example, if your custom plugin project extends existing catalog functionality, do not include pipeline blocks that handle operations for promotions in that plugin. Instead, create a different custom promotions plugin project to contain required changes to promotions operations.
Plugin project name and structure
Each new Commerce Engine plugin is defined as a project in Visual Studio. This section provides best practices and guidelines for naming and structuring your custom plugin projects.
Naming convention for your plugin projects
Consider the following conventions and patterns when you name your new Commerce Engine plugin project.
Naming a plugin that implements a new feature or functionality
Use the following convention to name a custom plugin project that implements a new feature:
<CompanyName>.Commerce.Plugin.<FunctionalArea>
Where:
-
<CompanyName>is the name of the company (or client if you are building a site for a client). For example:HabitatCompany. -
Commerce.Pluginindicates the type of project. -
<FunctionalArea>is the new area of functionality or feature. For example:ProductComparison.
For example, the name of a custom plugin implementing a new product comparison feature is : HabitatCompany.Commerce.Plugin.ProductComparison.
Naming a plugin that extends on base functionality
When you create a custom plugin that extends functionality that a base plugin provides by default, include the name of the base plugin you are extending as part of your project name. Use the following pattern to name your custom plugin:
<CompanyName>.Commerce.Plugin.<CommerceDefaultPluginName>
Where:
-
<CompanyName>is the name of the company (or client) for whom you are building the site. For example:HabitatCompany. -
Commerce.Pluginindicates the type of project. -
<CommerceDefaultPluginName>reflects the name of the default plugin you are extending.
For example, the name of a custom plugin that extends functionality provided by the base Commerce.Plugin.Catalog plugin is: HabitatCompany.Commerce.Plugin.Catalog.
Avoiding project names become too long
It is possible that a project name can become too long and unmanageable when strictly following the recommended guidelines for plugin project names.
If the solution name already contains the <CompanyName> (or client name), you can shorten your plugin project name by removing the <CompanyName> and the commerce.plugin segments from your plugin name.
We recommend that the underlying assembly and the default namespace still contain the two segments removed from the plugin name.
For example, to shorten a project named HabitatCompany.Commerce.Plugin.ProductComparison, you can rename it to Plugin.ProductComparison. However, the assembly that the project builds still follows the naming convention, and carries the full name, for example HabitatCompany.Commerce.Plugin.ProductComparison.dll. The default name space remains HabitatCompany.Commerce.Plugin.ProductComparison.
Project structure and namespaces
Consider the following guidelines and best practices when you structure your custom plugin projects to organize plugin artifacts and classes:
-
Create a distinct folder to contain each type of plugin artifacts, so that the folder name is the plural form of the artifact type. For example, if your custom plugin project implements new command and controller classes, then create folders named
CommandsandControllers, respectively. -
Add classes that represent a pipeline block or argument to the
BlocksandArgumentssub-folders, respectively. -
Add a class representing a pipeline or pipeline interface directly in the
Pipelinesfolder.
The Visual Studio project template that is included as part of the Sitecore.Commerce.Engine.SDK provides a good example of the required structure for plugin projects, with the appropriate folder and sub-folder names:
Plugin project references
Consider the following when adding references or dependencies to other components in your project:
-
Add all references to Sitecore plugins via the official Sitecore NuGet feeds.
-
Add all references to third-party assemblies via NuGet where possible.
-
Define all references to custom plugin projects within your own solution as project dependencies in Visual Studio.
Addition of new plugins to the Commerce Engine
When you create a custom plugin, you must register the new plugin assembly in the Commerce Engine executable to make the new functionality available. The following are best practices for adding a custom plugin to the Commerce Engine project executable:
-
Use a project reference to add new plugin projects within the same solution as the
sitecore.commerce.engineproject. -
In more complex build scenarios, you can add new plugin references to the Commerce Engine project via NuGet.