This post assumes you have followed the standard installation scripts and have Sitecore CMS and the commerce engine running under IIS.
There are a few more steps you need to perform to prepare your environment for commerce engine development.
The commerce engine is a stand alone ASP.Net core application. Therefore, you can run the engine directly from Visual studio and have the Sitecore site use your development instance rather than the engine running in IIS.
You can also remove the sample plugins (Habitat and Adventure works) by following this great post by Andrew.
In this post we are going to do the following :-
- Download and extract the commerce engine SDK
- Prepare the environment
- Run and debug
Step 1 – Download and extract the SDK
- Go the dev.sitecore.net and download the installation package from the commerce section, for example, Packages for On Premises 2018.03-2.1.55.
- Extract the commerce package to your install location. For example, C:\Install\9.0.1\Sitecore.Commerce.2018.03-2.1.55\
- Extract the SDK zip file Sitecore.Commerce.Engine.SDK.X.X.X.zip. For example, Sitecore.Commerce.Engine.SDK.2.1.10.zip to here C:\Install\9.0.1\Sitecore.Commerce.2018.03-2.1.55\Sitecore.Commerce.Engine.SDK.2.1.10
Step 2 – Prepare the environment
Generate the development SSL certificates
There is a script that comes with the SDK that generates SSL certificates for you
- Go to the scripts folder under your SDK folder. For example, C:\Install\9.0.1\Sitecore.Commerce.2018.03-2.1.55\Sitecore.Commerce.Engine.SDK.2.1.10\scripts
- Run the script named New-DevelopmentCertificate.ps1. This script will create the certificates that will allow your engine to run under SSL. After it runs you should have two new files localhost.cer and localhost.pfx in your wwwroot folder of your engine. For example, C:\Install\9.0.1\Sitecore.Commerce.2018.03-2.1.55\Sitecore.Commerce.Engine.SDK.2.1.10\src\Sitecore.Commerce.Engine\wwwroot
Prepare the visual studio solution
The SDK is provided as a Visual studio solution
- Open the SDK solution Customer.Sample.Solution.sln . For example, C:\Install\9.0.1\Sitecore.Commerce.2018.03-2.1.55\Sitecore.Commerce.Engine.SDK.2.1.10\Customer.Sample.Solution.sln
- Right click on the Sitecore.Commerce.Engine project and select “Select as startup project”
- Rebuild the solution
Configure the x509 certificate for the Site authentication
The engine must be able to authenticate calls coming from the site.
- Go to your Sitecore sites App_Config\Include\Y.Commerce.Engine folder and open the file named “Sitecore.Commerce.Engine.Connect.config”. For example, C:\inetpub\wwwroot\xp0.sc\App_Config\Include\Y.Commerce.Engine\Sitecore.Commerce.Engine.Connect.config
- Look for the element <certificateThumbprint> copy the value. For example,
77E580A6027FFD27C4445C08B666E46DC5ADF0DB
- Go to you SDK visual studio solution, under the Sitecore.Commerce.Engine project go to wwwroot and open config.json.
- Lookup “Thumbprint” and paste the value you copied earilier i.e. they should match between your config.json and Sitecore.Commerce.Engine.Connect.config.
- Save config.json
Note: You can validate the certificate in the certificate console (mmc snap in) i.e. it should be in your personal certificate store for local machine and be named “storefront.engine”.
Start the solution in console mode
You can now stop the default engines that are running in IIS and start the development engine. A console window will open that displays debug information.
- Stop any sites in IIS that are running the engine i.e. listening on port 5000
- Open your SDK visual studio solution
- Change the debug profile to “Engine” from “IIS express”. You can do this from the main menu in visual studio i.e. next to the green start button. Alternatively, you can do this by right clicking on the Sitecore.Commerce.Engine project, go to properties, go to debug, change the profile in the drop down to “Engine”
- Run the project
- You should see a console window open
- To test if your engine is running correctly go to a web browser and open https://localhost:5000/api/$metadata
Step 3 – Run and debug
As you now have your engine running from visual studio and listening on the same port, 5000, that the Sitecore site is configured to use. Browse the site and you should see all the calls to the engine being logged in the console i.e. the site is now using your engine running from Visual Studio not the one in IIS.
To debug, just add a break point somewhere in the engine code and execute the correct action from the site or postman.
For example, place a break point in the ConfigureServices method of one of the ConfigureSitecore classes and restart the engine.
Dynamics + Sitecore = Commerce 