Debugging Sitecore Commerce 9.2 Engine Using Customer.Sample.Solution

Sitecore Commerce(SXC) Engine is an extensible framework to develop new or extend existing commerce services. SXC has this concept of Plugins which can be created to customize it. A plugin is nothing but an atomic and self-maintained module of software which contains Pipelines, blocks and policies.

I setup Sitecore Commerce 9.2 recently and in order to start development using Visual Studio, I had to set up a new VS solution. SXC makes it easier for you as it comes with a sample solution which lives inside Commerce Engine SDK . This sample is called Customer.Sample.Solution. This solution can be used as a boilerplate code to kick off the development. When I started setting up my Visual Studio, I came across a few issues. Purpose of this post is to make it easier for anyone out there facing those problems of having questions How To.

  1. The first step would be to locate the sample solution. During the deployment, when we unzip the WDP package, we get When I unzipped this folder, it contains a few important things for developers. Postman collections, scripts and src. I will talk about these three briefly hereContentSDK

    1. Postman Collections: Are used to call Rest APIs of Commerce Engine. I wouldn’t go to the details of how, but if you have used Postman, you can import these collections like any other collection set and use them.
    2. Scripts: Scripts are really important. All the roles of SXC communicate over SSL. So the Customer.Sample.Solution would also need a self-signed certificate. We can use one of these scripts to generate that certificate.
    3. Src: As the name suggests, this folder contains the source code of certain plugins like Braintree for payment processing.
  2. Once I extracted the content, I opened Customer.Sample.Solution with Visual Studio.
    1. Set Sitecore.Commere.Engine as stratup project.
    2. Selected Engine as the runner
    3. SetEngine
    4. I updated Global.config under Sitecore.Commere.Engine\wwwroot\bootstrap\Global.json to have correct SQL Server credentials.
    5. Updated config.json Sitecore.Commere.Engine\wwwroot\config.json to have correct identityserver/AllowedOrigins/Prefix. It’s better to go through all the settings, don’t worry they are not too many 🙂
  3. stopped the Authoring role which was running on https://localhost:5000  because I want to run Engine on 5000 port from VS.
  4. While doing step 2, I noticed there were some SSL certificate settings in config.json.
        "SslPort": 5000,
        "SslPfxPath": "wwwroot/localhost.pfx",
        "SslPfxPassword": "sitecore"
    and also 
    "Certificates": {
        "Certificates": [
            "Thumbprint": "8D57A663FAA68B8DACF31D12D8A7EE178B314387",
            "DefaultRoles": [
              "sitecore\\Commerce Business User"
        "CertificateHeaderName": "X-CommerceEngineCert"

    Although I knew, I don’t have any certificate like, I still went ahead to run and try 🙂 As soon the engine started, it threw an exception  ”

    Connection id "0WLKFR32HU85A2" bad request data: "Invalid request line: '\x16\x03\x01.................


  5. I went to the scripts folder and ran New-DevelopmentCertificate.ps1 in Powershell. This script generates a certificate for development purpose and also installs it in Intermediate CA store. Habitual, I went and confirmed the certificate was there in the store
  6. I copied the thumbprint of the new certificate and updated config.json(#3)
  7. This time when I ran the project, it ran successfully but Business tools(Bizfx) were not able to connect to this Engine. Commerce engine was blocking the calls from Bizfx with a message like invalid certificate.
  8.  Since Bizfx uses Commerce connect to call Commerce Engine, I found this configuration of commerce engine connect Sitecore.Commerce.Engine.Connect.config  This configuration contains Thumbprint of the certificate as well which we need to change according to the certificate I generated in #5 This config file lives in Sitecore instance @(\App_Config\Include\Y.Commerce.Engine\)CommerceConnect
  9. In 9.2 installation, I also noticed, the Commerce Authoring URL doesn’t have localhost, rather it points to the name of the website e.g. I changed those settings as well.

This time, I was able to run the engine and also the business tools are now talking to the engine runnings from VS. Happy SXC extension 🙂

Leave a Reply