Registering a custom Commerce pipeline or block

Abstract

Guidance to help you define business logic using the ConfigureSitecore class in your custom Commerce plugin.

When you create a custom plugin project in Microsoft Visual Studio, the Sitecore.Commerce.Plugin.Sample project template (provided as part of the Sitecore.Commerce.Engine.SDK) includes the required ConfigureSitecore class. The ConfigureSitecore class is typically located at the root of the plugin project.

To implement the required business logic, you add your custom pipelines and blocks to the ConfigureServices method (a part of the ConfigureSitecore class) and define dependencies with other pipelines blocks. The ConfigureSitecore class lets you register new pipelines and custom blocks to the Commerce Engine and configure the sequence in which the blocks run.

To help you determine and define dependencies on other Commerce pipeline blocks, you can view a log of currently registered pipelines of a running Commerce Engine instance, or use Postman to get registered pipelines.

After you have identified the existing pipelines and blocks your custom plugin depends on, you add the required pipelines to the ConfigureServices method using the .addpipeline method. You configure each pipeline by specifying the function to perform on the relevant pipeline blocks they provide.

The pipeline framework provides support for the following methods and functions:

  • .configure.Replace - use this method to replace an existing pipeline block with a new block. For example:

    services.Sitecore().Pipelines(config => config
                 .ConfigurePipeline<IFormatEntityViewPipeline>(
                        configure =>
                        {
                            configure.Replace<GetEntityViewBlock>, <NewGetEntityViewBlock>();
                        })
          );
  • .configure.Remove - use this method to remove unwanted functionality blocks from an existing pipeline. For example:

    services.Sitecore().Pipelines(config => config
                 .ConfigurePipeline<IFormatEntityViewPipeline>(
                        configure =>
                        {
                            configure.Remove<CalculateCartLinesFulfillmentBlock>();
                        })
          );

The following example shows a pipeline configured to insert a custom block (.Add<AddOrderToServiceBusSendListBlock>) so that the actions it defines take place before the execution of the IPersistOrderPipeline :

.ConfigurePipeline<ICreateOrderPipeline>(configuration => configuration
     .Add<AddOrderToServiceBusSendListBlock>().Before<IPersistOrderPipeline>()
                )

In the following example, the pipeline configuration inserts the custom block .Add<EnsureActions>after the execution of the <PopulateEntityViewActionsBlock> .

.ConfigurePipeline<IFormatEntityViewPipeline>(configuration => configuration
     .Add<EnsureActions>().After<PopulateEntityViewActionsBlock>()
     .Add<EnsurePluginActions>().After<PopulateEntityViewActionsBlock>()             

Sample ConfigureSitecore class

The following shows an example of the sample ConfigureSitecore class that the Sitecore.Commerce.Plugin.Sample project template creates by default in Visual Studio.

namespace Sitecore.Commerce.Plugin.Sample 
{
    using System.Reflection;
    using Microsoft.Extensions.DependencyInjection;
    using Sitecore.Commerce.Core;
    using Sitecore.Framework.Configuration;
    using Sitecore.Framework.Pipelines.Definitions.Extensions;

    /// <summary>
    /// The configure sitecore class.
    /// </summary>
    public class ConfigureSitecore : IConfigureSitecore
    {
        /// <summary>
        /// The configure services.
        /// </summary>
        /// <param name="services">
        /// The services.
        /// </param>
        public void ConfigureServices(IServiceCollection services)
        {
            var assembly = Assembly.GetExecutingAssembly();
            services.RegisterAllPipelineBlocks(assembly);

            services.Sitecore().Pipelines(config => config

             .AddPipeline<ISamplePipeline, SamplePipeline>(
                    configure =>
                        {
                            configure.Add<SampleBlock>();
                        })

             .ConfigurePipeline<IConfigureServiceApiPipeline>(configure => configure.Add<ConfigureServiceApiBlock>()));

            services.RegisterAllCommands(assembly);
        }
    }
}