Debugging Sitecore Commerce Engine

While working on Sitecore commerce project, at many point of time we would like to debug the commerce part of the application similar to as we used to debug the Sitecore solution. To be able to debug the Sitecore commerce engine, there are couple of key concepts to understand. Which will help you understand the connection and debug commerce engine effectively.

If you are not much familiar with Commerce Engine, please see Getting started with Sitecore Commerce

I have used Sitecore Commerce 9.2 version to perform all these debugging steps.

Authentication

To debug commerce engine, you fist need to know how authentication works for different systems like Business Tools, Storefront, Content Editor, Postman etc.

There are mainly two ways to authenticate

  • Certificate authentication
    • Certificate authentication is used for systems going through Commerce Engine (CE) Connect as mentioned below.:
      • SXA Storefront: All SXA components for Storefront communicates with commerce engine through certificate.
      • Commerce engine commands in Content Editor: Similar to SXA Storefront, commerce commands like Update data templates, Delete data templates, Refresh commerce cache in content editor uses the same certificate approach as it communicates to commerce engine through Commerce Connect.
        ce-commands.png
  • Bearer token authentication
    • Sitecore uses bearer token authentication for systems calling the Commerce Engine directly, without going through CE Connect.
    • The caller must connect to the Sitecore Identity Server, using Sitecore credentials, to obtain a token. Sitecore uses that token as an authorization bearer in request headers.
      • Business Tools: When accessing Business Tools from Sitecore Launchpad, it redirects to identity server login page. Once user successfully logs in, it will redirect user back to Business Tools and will use obtained token for authentication for same session.
        Authorize (http://{{SitecoreIdentityServerHost}}/connect/authorize)
      • Postman/Scripts: Systems like Postman or Scripts getting executed during automated deployment could not login through UI. For these systems to interact with Commerce Engine, there is an endpoint available in identity server using which these system can obtain the token.
        GetToken (http://{{SitecoreIdentityServerHost}}/connect/token)

Debugging

  • Stop your authoring site running on port 5000 from IIS. Generally in development machine, shops and authoring both points to Authoring site.
    You can find this setting in \App_Config\Include\Y.Commerce.Engine\Sitecore.Commerce.Engine.Connect.config

    ce-connect

  • Open your Commerce Engine VS solution which you wanted to debug. If you’re not sure how to setup commerce engine VS solution, see https://medium.com/@siddharaju.s/debugging-sitecore-commerce-engine-custom-plugins-948a6b50e27f. Select Engine profile which is meant for Development and Debug configuration

    vs-profile

    In .Net core, these profiles (environments) are defined in launchSettings.json file.

  • To launch Kestrel with Visual Studio, we must specify launchUrl” in launchSettings.json file. Which should be there by default in your commerce engine solution. For ex: “launchUrl”: “https://localhost:5000/api/$metadata”. Basically this is the URL at which Kestrel server listens to requests. This is the reason we had to stop Authoring site in IIS to debug from Visual Studio.
  • Click F5 to run your commerce engine and you should see something like:

    engine1

  • So, basically it should listen to https://localhost:5000 (which eventually will be converted into https://127.0.0.1:5000) with which your various systems like CM/CD/Business Tools are connected.
    • Q: What if you see it’s overriding listener and listening to https://0.0.0.0:5000 instead of https://localhost:5000
      • engine2
      • With this binding, you may or may not able to connect to your commerce engine running from your visual studio.
      • There is one setting called “UseHttpsInKestrel” in your  config.json file. Default value is true. This settings is being used in Program.cs file of your engine project.

        buildwebhost

        According to above code lines, it’s instructing to listen to any address which is why we are seeing 0.0.0.0:5000 in listener if UseHttpsInKestrel is true.

      • To solve above issue, specify UseHttpsInKestrel to false in config.Development.json. After this change too it wasn’t working for me. Now i was getting message saying it’s listening on https://localhost:5001 and http://localhost:5000.

        engine3

      • To resolve this and listen to https://localhost:5000 which is defined in CM and IdentityServer, i had to specify applicationUrl in Engine profile at launchSettings.json file as mentioned below:

        applicationUrl

These steps are necessary to debug all system which can connect to Commerce Engine like SXA Storefront, Content Editor CE commands, Postman, Business Tools etc.

Let’s see things to consider while debugging Commerce Engine specific to each system connecting along with above steps:

Postman

Once your engine is running from visual studio and listening to https://localhost:5000, you should be able to connect from Postman.

With a new installation of Postman, you must disable SSL certificate verification in order to get a response back from the Commerce Engine. To do this, in Postman, click File, Settings and then turn SSL certificate verification to OFF.

postman

Business Tools

To be able to debug Business Tools when you have used named domains, you need to make sure https://localhost:5000 is present on \Config\production\Sitecore.Commerce.IdentityServer.Host.xml file on your identity server role.

identity

Along with this, You also need to make sure engineUri in \assets\config.json file on your BizFx role points to https://localhost:5000

bizfx

Storefront/Commerce Engine Commands

As we saw earlier, Storefront and CE commands uses Certificate Thumbprint approach to authenticate against commerce engine.

You need to specify the thumbprint associated with localhost.pfx file present in your wwwroot folder of Visual Studio solution which you have generated at the time of setting up VS solution (More info on generating DevelopmentCertificate) for commerce engine into \App_Config\Include\Y.Commerce.Engine\Sitecore.Commerce.Engine.Connect.config file of your CM/CD/Standalone instance you want to debug.

certificate-thumbprint

And if you have used named domains while installing commerce in your local, you also need to make sure shopsServiceUrl and commerceOpsServiceUrl parameters in Sitecore.Commerce.Engine.Connect.config file points to https://localhost:5000

shopsurl

Hope this will help you debug the functionality you wanted before promoting it to higher environments. Quality matters most!

 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s