Skip to main content
Dynamics 365
·
5 min read

AX for Retail 2012 R3: How to deploy customized Commerce Runtime services

We get a number of questions on the exact steps needed to create and deploy customizations to the Commerce Runtime (CRT).  Here is a step-by-step process to get up and running with a very simple customization.  These steps should work with both 2012 R3 and AX7 versions of the Commerce Runtime

Method 1:  total replacement of the CRT services assembly

  • Start Visual Studio and open the Commerce Runtime solution.  By default, this can be found in this location:  C:\Users\Administrator\Documents\Retail SDK CU9\Commerce Run-time\Sdk.CommerceRuntime.sln
  • By default, all seven projects in the solution are configured to be signed with a strong name key which isn’t provided:  strongnamekey.snk.  For purposes of this example, we will create unsigned assemblies and configure the CRT to use them.  As part of your development you will want to sign with your organizations key and update the SDK source files with the UpdateAssemblyIdentities.ps1 script.  Details on that process can be found on this page.  For now, right-click on each project and select properties.  On the Signing tab unmark the Sign the assembly checkbox:

01

  • After saving each project, make sure that the solution compiles before making any code changes.  Select Build > Rebuild solution and make sure you get no errors.
  • The Sdk.Services project points to the Microsoft-signed version of the Runtime.Services.PricingEngine assembly.  This will cause problems when deploying your customized CRT.  To fix this, remove the reference and point it to the PricingEngine project from the solution instead.
    • Expand the Sdk.Services project and then expand the References menu item.  Right-click on Microsoft.Dynamics.Commerce.Runtime.Services.PricingEngine and select Remove.
    • Right-click on References and select Add Reference.  On the Reference Manager form, expand Solution and then select Projects.  Select the Runtime.Services.PricingEngine project and select OK.  Make sure that you actually mark the project using the checkbox (it’s easy to miss).

02

  • Now make your code changes.  An easy one to test out is to make customize a receipt using the ReceiptService service.  Go to the Sdk.Services > Receipt > ReceiptService.cs file and find the GetReceiptForXZReport method.  Near the end of this method is line of code to copy the text of the receipt into the receipt.Body property.   Add an extra line of text to the receipt after this line:

03

  • Re-build your solution to make sure things didn’t break.
  • Now go look for the resulting assemblies.  By default they are saved in the References subfolder of the Commerce Runtime folder.  Sort by date to make them easy to notice. 

04

  • For most customizations, you will be most concerned with the Services.dll and Services.Pricing.dll files.  Copy those (and their corresponding PDBs) to a temporary folder for deployment.
  • Copy the files to your CRT folder.  If you are using Retail Server, they will go in the Package\Bin folder.  If you are using the direct database or offline capability for MPOS, they will go in the Retail Modern POS\ClientBroker folder:

05

07

  • The final step is to tell the CRT to look for your assembly instead of the Microsoft-signed version.  In the same folder you copied your assemblies to, make a backup of the commerceRuntime.config file.  Open the file in a text editor and change the signature information for the Runtime.Services assembly (Version, Culture, PublicKeyToken, and processorArchitecture).  For this example, our assemblies are unsigned so you can remove the entire highlighted text:

08

  • Restart your Retail Server and MPOS and test your changes.  Remember to kill the DLLHost.exe process if using direct database mode.  If everything worked you should immediately see your change the next time you print a receipt:

09

If things don’t work, check your event viewer for any exceptions.  The most common problem that I’ve seen is that the Microsoft-signed version of the PricingEngine attempts to be loaded.  Dropping and re-creating the reference as noted above usually takes care of the issue.

Method 2:  Deploy a service in its own assembly

Replacing the entire Runtime.Services assembly is a relatively easy option and can be used both in development production environments.  But the real power of the CRT architecture shows up when you completely segregate code changes to just the services you are modifying.  Deploying using this methodology is very similar to how you would deploy a service in Enterprise POS.  This also makes thing much easier from a maintenance view:  if the jump between hotfix releases doesn’t change the code in your services, you don’t have to merge code and redeploy your assembly; you can just install the CRT hotfix and leave your DLL in place until it needs to be changed.

The initial setup steps are a bit more involved but once that leg work has been completed, continuing development is pretty simple.

  • Launch a Windows Explorer instance and go to the root of your Commerce Run-time folder.  Right-click on the Services folder and select Copy.  Right-click on white space in the root folder and select Paste.  This will make a folder named Services – Copy.  Rename the folder something like ServicesPartner:

11

  • Go into your new folder and delete all subfolders except for the service you will be customizing.  For this example, we will only keep the Receipt subfolder.  While in the folder, rename the .csproj file as well:

12

  • Open the Sdk.CommerceRuntime.sln solution in Visual Studio.  Using the notes above, change the Signing on the seven projects so the solution will compile.
  • In Solution Explorer, right-click on the top node of your solution and select Add > Existing Project.  Navigate to your new folder and select the .csproj file.  Again, select all folders except Receipt and remove them from your project.

13

  • Expand the References node and remove the reference to the PricingEngine assembly since the Receipt service doesn’t use the pricing engine.  This will help avoid any assembly definition issues.
  • Right-click in your project and select Properties.  On the Library tab, change the Assembly name and Default namespace to match your organization:

14

  • Select the Signing tab either un-mark the Sign the assembly checkbox or sign it with your organization’s strong name key.
  • Make your code changes and rebuild your new project.
  • Navigate out to your References folder again and you should see your new assembly:

15

  • Copy the assembly and its PDB into either the bin folder of the Retail Server or the ClientBroker folder of MPOS.
  • Open the commerceRuntime.config file and add the following line above the line for the Runtime.Services assembly.  If you followed the steps in Method 1, add the signed assembly information back in first (restore from the backup you made).
  • Restart your Retail Server and MPOS and test your changes.   Again, if you’re using direct database or offline for MPOS, kill the DLLhost.exe process so your changes get picked up.

As you can see, the second method really gives you a lot more flexibility on how you develop and deploy customized CRT services and I highly recommend using that approach if possible.

Use the comments below to ask any questions you have on this topic.

Shane Erstad

Related posts