Retail SDK packaging
This topic applies to Dynamics 365 for Retail and Dynamics 365 for Finance and Operations.
This topic explains how to package customizations for the following artifacts.
- Commerce runtime (CRT)
- Retail Server
- Modern POS
- Cloud POS
- Hardware station
- Channel database scripts
- AOS payment connector
Customizations for the above artifacts are packaged as a single retail deployable package.
If your customizations were built and packaged using Retail SDK prior to application version 7.1.1541.3036 as individual retail component packages, these are no longer supported for deployment in LCS. You must uptake the following update and re-build and re-package your customizations for retail components.
- KB 4015062
For detailed information about the Retail software development kit (SDK), see Retail SDK overview.
Retail deployable package
Retail deployable package is an asset that can be consumed by the LCS deployment service or it can be deployed manually to service or install a customization.
Steps to create a Retail deployable package
There are two ways to generate the Retail deployable package. One is using the Retail build automation or manually using the build tools in Retail SDK. In this topic we will focus on the manual way.
- Customize or add functionality to the Retail stack.
- Use the build tools to give an identity to the customized installation package, code-sign it, and specify the customized CRT, Retail Server, customized Hardware station assemblies, and customized database scripts.
- After all the settings have been specified on Customization.settings file under Retail SDK\BuildTools folder, run msbuild /t:rebuild on the root of the Retail SDK folder using the VS dev command prompt tool to generate the retail deployable packages. Before building the package, place all the customized assemblies to Retail SDK\References folder and also place the modified config files like commerceruntime.config, CommerceRuntime.MPOSOffline.config, dllhost.exe.config to the Retail SDK\Assets folder.
Retail SDK build tools – Customization settings
BuildTools\Customization.setting files is where most of the configuration values for the Retail SDK are set for build and packaging. These values control how binaries, components, and packages are named, versioned, and code-signed. After you define this metadata, The Retail SDK build system uses it to give an identity to the assets, and to package the customization assets for all the Retail components.
The following list of configurations is available in Customization.Settings file:
- AssemblyNamePrefix – Specify the prefix name for the assembly. When you build the Retail SDK, all the assemblies are prefixed with this name.
- CustomAssemblyVersion – Specify the custom assembly version for all assemblies that are built by using the Retail SDK.
- CustomVersion – Specify the custom file version for all assemblies that are built by using the Retail SDK.
- CustomName – Specify the custom name for the assembly.
- CustomDescription – Specify the description for the assembly.
- CustomPublisher – Specify the publisher for the assembly.
- CustomPublisherDisplayName – Specify the copyright for the assembly.
- SignAssembly – Specify True if you want to sign the assembly during the build.
- DelaySign – Specify True if you want to delay signing of the assets during the build.
- AssemblyOriginatorKeyFile – Specify the strong name key to use to sign the assembly.
- ModernPOSPackageCertificateKeyFile – Specify the PFX file to use to sign Modern POS and Hardware station.
- RetailServerLibraryPathForProxyGeneration – Specify the customized Retail Server assembly to use for proxy generation (both TypeScript and C# proxy).
- In the ItemGroup section:
- ISV_CommerceRuntime_CustomizableFile – Specify all the customized CRT assembly. You can have multiple entries, one for each customized CRT assembly.
- ISV_RetailServer_CustomizableFile – Specify all the customized Retail Server assembly. You can have multiple entries, one for each customized Retail Server assembly.
- ISV_HardwareStation_CustomizableFile – Specify all the customized Hardware station assembly. You can have multiple entries, one for each customized Hardware station assembly.
- ISV_CustomDatabaseFile_Upgrade_Custom – Specify all the customized database scripts.
Retail reployable package
CRT extension assemblies
By default, there is no separate package for individual retail components, because CRT isn't deployed individually, instead, CRT assets are packaged together with other application components, such as Modern POS, Retail Server, and Microsoft Dynamics 365 for Operations HQ. In order for the Retail SDK build tools to package CRT in all the components where it's used, you must make the following configuration entries:
CRT extension assemblies – These will be the new assemblies where you've written CRT extensions. Specify an entry for CRT extension assemblies in Retail SDK\BuildTools\Customization.settings.
CRT commerceruntime.config file – If you have a new CRT assembly, you must add it to the CRT configuration file so that the runtime can load it. Specify an entry for CRT extension assemblies in Retail SDK\References\commerceruntime.config.
Retail Server extension assemblies
Retail Server extension assemblies – These will be the new assemblies where you've written Retail Server customizations. Specify an entry for CRT extension assemblies in Retail SDK\BuildTools\Customization.settings.
Retail Server web.config file – You must add an entry for Retail Server extension assemblies to the Retail Server web.config file, so that they are loaded and used. Specify an entry for Retail Server Extension assemblies in Retail SDK\Packages\RetailServer\Code\web.config.
As a part of a customization, you might have to upgrade a channel database in addition to a Modern POS offline database. Currently, you use upgrade SQL scripts to upgrade the channel and Modern POS offline databases. You can write an upgrade SQL script and put it at Retail SDK\Database\Upgrade\Custom, so that packaging tools can pick it up and include it in the deployable package for the correct components (Retail Server and Modern POS Offline).
Database scripts are packaged together with the Retail Server and Modern POS Offline packages, and are run when Retail Server and Modern POS are installed. If there are multiple custom database scripts, they are run in alphabetical order. Therefore, if you want to run the scripts in a specific order, you must name them accordingly. The CRT.RETAILUPGRADEHISTORY table keeps track of which scripts are already applied to the database. Therefore, the next database upgrade will run only those upgrade scripts that don't have an entry in the CRT.RETAILUPGRADEHISTORY table.
Generate a retail deployable package
The Retail SDK fully supports msbuild. To build the Retail SDK and , open a Visual studio 2015 developer Command Prompt tool window as an administrator, and run msbuild (or, for a non-debug version, run msbuild /p:Configuration=Release).
After the build is completed, retail deployable packages(RetailDeployablePackage.zip) is generated in the Retail SDK\Packages\RetailDeployablePackage folder. Note: There will not be any separate packages for retail, all will be combined and created as one bundle package called RetailDeployablePackage