Creating a Custom Pipeline Task

You will learn how to create a custom pipeline task. This is useful for when you would like to execute custom code as part of one of the Ucommerce pipelines (eg. Basket Pipeline, Checkout Pipeline)

In Ucommerce the majority of the functionality is executed as pipelines. You can read a full overview of our pipelines.

In this example, we'll create a pipeline task that will get executed as part of the Checkout pipeline. The purpose of this task is to notify the store administrator every time an order goes through the system. To achieve this we first need to:

• Create a Visual Studio project
• Create a class that implements IPipelineTask<PurchaseOrder>
• Build and deploy the assemblies
• Configure the task in the configuration file

On to the Code

Below is the OrderCompletedTask pipeline task which implements IPipelineTask. In the constructor, it takes everything needed for sending an email. If you have dependencies that are not part of the core platform, just makes sure to configure them in your configuration file in your app folder in Ucommerce/Apps/MyApp, just like we'll do for this task later.

    namespace UCommerceCodeSamples.Pipelines
    {
    	public class OrderCompletedTask : IPipelineTask<PurchaseOrder>
    	{
    		
    		private readonly CommerceConfigurationProvider _provider;
    		private readonly IEmailService _emailService;
    		private readonly ICatalogContext _catalogContext;
    
    		public OrderCompletedTask(CommerceConfigurationProvider provider,
    								IEmailService emailService,
    								ICatalogContext catalogContext)
    		{
    			_provider = provider;
    			_emailService = emailService;
    			_catalogContext = catalogContext;
    		}
    		

The next step to achieve this is to implement the method Execute which Ucommerce will be responsible for calling, whenever the Basket Pipeline is executed.

    public PipelineExecutionResult Execute(PurchaseOrder subject)
    {
    	var localization = new CustomGlobalization(_provider);
    	localization.SetCulture(new CultureInfo(subject.CultureCode));
    
    	var queryStringParams = new Dictionary<string, string>();
    	queryStringParams.Add("orderguid", subject.OrderGuid.ToString());
    	queryStringParams.Add("orderid", subject.OrderId.ToString(CultureInfo.InvariantCulture));
    	var emailProfile = _catalogContext.CurrentCatalogGroup.EmailProfile;
    
    	_emailService.Send(localization, emailProfile, "Orders", new MailAddress("[email protected]"), queryStringParams);
    	
    	return PipelineExecutionResult.Success;
    }
    

Register the Task

To make Ucommerce use the task we've just created we need to register it as a component. Here's what the component registration looks like for our example:

    
    <configuration>
    	<components>
    		<component 
    			id="ToCompletedOrder.SendOrderCompletedMail"
    			service="UCommerce.Pipelines.IPipelineTask`1[[UCommerce.EntitiesV2.PurchaseOrder, UCommerce]], UCommerce"
    			type="UCommerceCodeSamples.Pipelines.OrderCompletedTask, UCommerceCodeSamples" />
    	</components>
    </configuration>
    

Put this file in /Ucommerce/Apps/MyPipelineTask where it will be automatically picked up when the application starts up.

Interested in more details about components? Please see Register a Custom Component.

Once added it must be added to the pipeline you want it to be executed as part of.

Configure the Pipeline

Partial components enable you to configure just the changes to the list of tasks of a pipeline, rather than overriding the entire component or modifying the pipeline files directly as was the case in previous versions.

Here is an example of how to add the new task we created above, as the last task in the "ToCompletedOrder" pipeline.

    
    <configuration>
    	<components>
    		<partial-component id="ToCompletedOrder">
    			<parameters>
    				<tasks>
    					<array>
    						<value insert="last">${ToCompletedOrder.SendOrderCompletedEmail}</value>
    					</array>
    				</tasks>
    			</parameters>
    		</partial-component>
    	</components>
    </configuration>
    

There are some important things to note:

• The id of the partial component must match the id of the pipeline component you wish to modify. In this case, it is the "ToCompletedOrder" pipeline component that is modified.
• The value inserted is using the id of the new custom component added in the previous examples, "ToCompletedOrder.SendOrderCompletedEmail".
• Most important is the attribute "insert" with the value "last". This instructs the configuration to add this task as the last task in the pipeline. In this example, it makes sense to have the send email task as the last one since we only want to perform it, if all other tasks have completed successfully.

The attributes supported are:

• "insert", with value either "first" or "last".
• "insert-before", with a value of the castle service override notation "${COMPONENTID}".
• "insert-after", with a value of the castle service override notation "${COMPONENTID}".
• "remove", with a value of the castle service override notation "${COMPONENTID}".

It is very important to note, that when using "insert-before" or "insert-after", the task is added after every occurrence of the service found in the pipeline. So be aware, that the task can be added more than once. Also note that "remove", will remove all instances of the matching tasks.

In the following example, a custom pipeline task called "MyCustomTask" is added to the basket pipeline after the task "Basket.CleanUp".

    
    <configuration>
    	<components>
    		<partial-component id="Basket">
    			<parameters>
    				<tasks>
    					<array>
    						<value insert-after="${Basket.CleanUp}">${MyCustomTask}</value>
    					</array>
    				</tasks>
    			</parameters>
    		</partial-component>
    	</components>
    </configuration>
    

And an example of removing the "SendConfirmationEmail" task from the "Checkout" pipeline.

    
    <configuration>
    	<components>
    		<partial-component id="Checkout">
    			<parameters>
    				<tasks>
    					<array>
    						<value remove="${Checkout.SendConfirmationEmail}" />
    					</array>
    				</tasks>
    			</parameters>
    		</partial-component>
    	</components>
    </configuration>
    

The configuration file should be placed in Ucommerce/Apps/MyApp folder. It will automatically be picked up when the application starts up.

All there's left to do is build and deploy the assemblies into your Application's bin folder.

We've now extended the ToCompleted pipeline with a custom pipeline task.

Performance measurements of pipelines

Setting the Debug parameter to the value "true" enables the logging of performance measurements for the tasks of pipelines.

Using partial components configuration, enabling debug is very easy.

Simply add this partial component to the custom configuration file to enable debug for, in this example, the basket pipeline:

    
    <configuration>
    	<components>
    		<partial-component id="Basket">
    			<parameters>
    				<Debug>true</Debug>
    			</parameters>
    		</partial-component>
    	</components>
    </configuration>
    

The end result is simply that the default pipeline implementation, if configured with debug enabled like above, is writing the execution time of each task into the log files.