In the past, in order to build and deploy a commerce scale unit package, we needed to build a retail deployable packaged from the Retail SDK. This has now changed. We now build a commerce scale unit package from a stand alone Visual Studio solution. And we can download that solution from GitHub. In this article I will explain what has changed. Note: If you have a CloudPOS, you still need to apply the Retail Deployable Package to the CSU’s, for now. This is changing in the near future.
Download The ScaleUnit Solution
In the current version, we no longer need the entire Retail SDK to build a commerce scale unit package. We instead can just use a Visual Studio Solution to build the package. I will explain the steps.
First, download the Dynamics365.ScaleUnit solution from github. It is located at this url:
microsoft/Dynamics365Commerce.ScaleUnit at release/9.26 (github.com)
You can pick which version you need. In the ReadMe.md file, it explains what release version relates to what application release version. In this case release version 9.26 relates to application version 10.0.16, which is what I need.
Understanding The Solution
Next, open the ScaleUnit.sln found in the folder you downloaded from github. This will open Visual Studio. In the solution, there are 3 projects. ChannelDatabase, CommerceRuntime, and ScaleUnit. Build this solution to generate the commerce scale unit package. But first, I will explain the purpose of each project.
Channel Database
The ChannelDatabase project contains an example file named Contoso.ExampleTable.ChannelDatabase.sql. This sql file contains tsql code to create new tables, fields, stored procedures, and views in the channel database. If you have custom tables or fields you need to exist in the channel database, you need to create your own .sql file and add it to this project. There are several important things you need to remember when creating your .sql file.
First, write the sql code written such that if the same sql script was run multiple times against the same database, it would not error. The way you do this is to first checks to see if the object exists before making the change. If a table already exists, do not try to run a create script. In the case that a view or stored procedure already exists, first drop the view or stored procedure, then re-create it. When you need to add a field to a table that already exists, use an ‘add column’ command.
Secondly, follow the best practices of extending the channel database. I will not go into all of the details, but at a high level, custom objects should be put into the ext schema. Meaning all custom objects should start with ext.<name of the object>. This ensures that the objects you create and Microsoft creates will not have the same name.
Thirdly, make sure your new sql objects have the correct permissions. To do this, add GRANT statements like the following:
GRANT SELECT, INSERT, UPDATE, DELETE ON OBJECT::[ext].[CONTOSORETAILSTOREHOURSTABLE] TO [DataSyncUsersRole]This grants the proper permissions for the system to sync data to the new table. Look at the sample .sql file for other examples.
Lastly, each time you need to make a change to the channel database on top of what has already been deployed, create a new .sql file. Each time the LCS deploys a package to an environment, the system keeps track of what sql scripts it has already deployed. And so if you add to an existing sql file, instead of creating a new file, the system will not try to rerun the existing sql file.
Commerce Runtime
The Commerce Runtime solution is for placing all of the code that needs to be deployed to the Retail Server website. This includes controllers, request handlers, triggers, and entities. All the code you used to store in a custom retail server solution, now should be migrated to this new solution.
In the past, developers needed to add a lot of references to base Microsoft Commerce Runtime dlls, in their Retail Server projects, to support all of their custom code. In the new solution, this has become so much easier. The CommerceRuntime project has a Nuget Package reference to Microsoft.Dynamics.Commerce.Sdk.Runtime. This contains most of the dll references that a developer would need to support their customizations.
In the past, when Microsoft released a new version of their base Microsoft dlls, a developer would need to update all the file paths of their dll references. Now that the dlls are all part of a nuget package, the developer can just specify the version they wish to reference using the nuget package manager, and all of the updated dlls will be downloaded.
When you work with other ISV’s and they already have Retail Server dlls, you can just add a reference to those dlls from this project.
To make customizations to the base Microsoft functionality, add controllers, entities, request handlers, and triggers to this project.
ScaleUnit
The ScaleUnit project should not be changed. It is responsible for building the commerce scale unit package. It has a Nuget package reference. That reference can be changed to point to a different version of the Microsoft dlls. Or, if it makes sense, you can download the latest release of the ScaleUnit solution from github.
Building The Commerce Scale Unit Package
To build the commerce scale unit package, build the ScaleUnit solution. To locate the package file, go to ScaleUnit/bin/Debug/netstandard2.0
In this folder you will see a folder named CloudScaleUnitExtensionPackage. You will also see a zip file that contains this folder. This is the cloud scale unit package.
Uploading The Commerce Scale Unit Package
Open a browser and go to lcs.dynamics.com. Sign in. Then select your project.
Go to the three lines button, and select ‘Asset Library’. Select the ‘Commerce Cloud Scale Unit’ tab.
Click the plus button and upload the CloudScaleUnitExtensionPackage.zip.
Deploying The Commerce Scale Unit Package
Next, go to main home page of your LCS project. Select an environment that is hosted on the Microsoft tenancy. Click ‘full details’. In this page, Under ‘environment Features’, next to the word ‘Commerce’ click the link ‘Manage’
On this page, select the first Commerce Scale Unit on the left hand side. Then click the ‘Update extension’ button. Select the file the commerce scale unit package file that you just uploaded form the list. Then click Ok to apply the package to the Commerce Scale Unit. Repeat this process for each Commerce Scale Unit that is listed on the left hand side.
Behind the scenes, the system will deploy the CommerceRuntime dlls to the Retail Server website. It will put the files in the bin/ext folder of the website. The system will also run any new sql scripts against the channel database.
There is also an ‘Update’ button on this form. Push this button to select a new base Microsoft package to apply to the Cloud Scale Unit. In the past, both the base Microsoft dlls and the custom dlls needed to be deployed together in a single Retail Deployable Package. Now these dlls can be deployed separate and independently from each other. This potentially allows for the latest Microsoft updates to be applied without the need of a developer. It is still possible that the new Microsoft dlls may not work together with the customizations. In most cases, this should not happen.
CloudPOS
It is important to note, that if you are using the CloudPOS, you still need to build a Retail Deployable Package and deploy this against the Commerce Scale Units in LCS. This package updates the CloudPOS website. Whereas the Commerce Scale Unit Extension package will not update the CloudPOS and actually will remove any extensions that currently exist in the CloudPOS. In the near future, users will be able to update the CloudPOS files independently, but this is not the case yet.
Conclusion
In this article we reviewed the steps for building and deploying a commerce cloud scale unit package. This is a wonderful new process starting in version 10.0.16. It allows developers to create retail server extensions without needing the entire Retail SDK files. And it allows developers to deploy retail server extension files separately from the base Microsoft dlls. Taking in updates is now a whole lot easier.
Can we deploy the commerce scale unit package on tier 1 environment through LCS ?
Please response asap
Thanks
For cloud hosted development environments you would not deploy a commerce scale unit package via lcs. You would typically do a get latest on your source code inside the machine. Then compile the solution. Then copy the commerce runtime dlls and config file to the Retail server website’s bin/ext folder that is running on the machine. You can see the websites by going to windows>start then typing “iis” and opening the internet information services manager. Then expanding the websites node of the left side. You can right click on the Retail Server website and select Explore to go to where the website files. They are on the K drive.
For all tier 2 Microsoft tenancy machines you would follow the normal steps of applying the commerce scale unit package through lcs.
Thanks peter
Hi Peter,
I have read your article and it’s great. I have a question related to the deployment of the commerce scale unit package on Tier-1 / Dev environments. How we can automate the deployment procedure, right now we are creating RetailDeployablePackage and it contains the OOB AXUpdateInstaller executable which we execute manually through a command prompt by following this article (https://docs.microsoft.com/en-us/dynamics365/fin-ops-core/dev-itpro/deployment/install-deployable-package) and it automatically deploys the package but now as we have checked that AXUpdateInstaller is not available in Commerce Scale Unit Package as per new Commerce SDK. So, Is there any other way available like AXUpdateInstaller or do we need to manually deploy the package?
Thanks in advance
Hi Ahsan. Thank you for your question. So if there is a script that can install the retaildeployablepackage to a dev environment I don’t know of it. What you can do is this. You can unzip the package on the dev machine. Then you can copy the files in retailserver/bin/ext to the retailserver website running in iis on that machine. Copy the files to the bin/ext folder.
Then take the .sql files found in the package and run them against the AxDB database to ensure any new fields and tables get created. Then copy the files in the retailCloudPos folder in the package to the retailCloudPos website running in IIS on that machine. Copy them into the Extensions folder.
Those steps are essentially what LCS does with the package. I know that is a lot of steps. But hopefully that helps some.
Hi Peter,
Thanks for this amazing article.
The package generation mentioned here is manual by using it from Visual Studio.
Is there any documentation where We can make it a part of the build pipeline?
Yes. I will try to write article on that topic or add a link to this comment.
Hello,
Thank you for your wonderful article.
I have deployed a cloud hosting environment, but there is no Manage Commerce section in its settings. How can I implement an environment like yours so that there is both the Manage Commerce section in it and access to the machines?
Thank you
The manage commerce link is only available for Microsoft hosted tier 2 or above environments. If you deploy an azure hosted tier 1 environment then the commerce websites will be deployed all on the same machine as D365 headquarters. And so if you need to deploy code to the retail server website or the cloud pos website you can do so directly by copying the files directly into the website instead of deploying the package. Deploying a package essentially just unzips the package and copies the files in it to the right folders in the website. I hope that helps some.
Thank you very much,
I apologize for my lack of information in this regard.
I need to access both the machine (rdp access) and the commerce manager at the same time. Is there such a possibility? With any license?
If the answer is yes, how much will the desired license cost for a few days test?
I think there may be some confusion. If you can rdp into the machine then it won’t have the commerce manager.
If you can click the commerce link then you won’t be able to rdp into the machine. Those are just the limitations on a tier 1 vs a tier 2 box.
You can create a tier 1 box and then separately create a tier 2 box. But then won’t be linked so I’m guessing that is not what you want.
Thank you very much sir
I would appreciate it if you could answer my other question.
In the tier 2 environment, after updating or installing a Scale Unit package, how can I access files or its content? Is this possible through the web?
Unfortunately you cannot remote into the back end of a tier 2 or above box. Microsoft locks those down for security reasons. The only way to deploy files to those machines is by using LCS to deploy a package.
Conversely you can remote into a tier 1 box. If you want to deploy commerce code you have to manually copy dlls into the Extension folder within the cloud POS or Retail Server website.
Thank you for your kindness
I noticed that RDP is only available in tier 1. However, I would like to know when I apply an extension in Commerce Manager after it is successful, how can I see the changes or effects caused by it (other than LCS). For example, the existence of a URL or API that shows the installation of the extension or that leads to the addition of a section to the environment and…
After you apply a customization to the Commerce Scale Unit, if you added some new custom requests there is a URL where you can see a list of the new requests. I don’t remember what that is off the top of my head. But if you added triggers or other extensions to existing code then the base code will just work differently than before.
If you make changes to the score commerce app you can click the settings button and see a screen that shows a list of all extensions installed. But that is changes directly installed with the store commerce app on the point of sale register. Not changes applied to the commerce scale unit.
Hopefully that helps some.
Thank you for your detailed answers. It was great
Hello
I have a question that, considering the level of content that you publish, I guess that I can get a suitable answer here, of course, it has nothing to do with the topic of your article, and I would be grateful if you could guide me if possible.
When I create a package in Solution Management and enter it, no information is displayed in the Trial Environments section.
How can you see information in this section? Does it need a special account or license? Have you ever seen information in this section?
Thank you sincerely
Dear Peter,
Thank you so much for really awesome docs.
About the UI customizing using Typescript codes, how should I develop for that and transfer the package to another environment? Meanwhile, where is the solution? How can I find that?
Thanks in advance
Danial
Hi Peter, Thanks for this article. It’s really helpful.
We have external ecommerce site from which we want to push the retail sales orders to the dynamics using one of the Retail Channel. With this Commerce SDK and Scale Unit, What is the best way to push these orders to Dynamics? Earlier we have been using pushing them using Retail APIs.