Retail software development kit (SDK)

Important

Support for the Retail SDK will end in October 2023. Please use or migrate to the Commerce SDK, which provides several benefits including a simplified development and update experience, and improved performance.

This article provides an overview of the Retail software development kit (SDK). Microsoft Dynamics 365 Commerce provides a rich SDK that developers can use to customize and add new features to the product. The multi-tier architecture of the Dynamics 365 Commerce provides simplified options for customizing and extending the client, business logic, and data layers independently of each other. The Retail SDK includes libraries, NuGet packages, a point of sale (POS) application, code samples, templates, and tools. You can use it to create extensions apps, add features, and change existing functionality of Commerce.

Retail SDK overview

The Retail SDK includes the code, code samples, templates, and tools that are required to extend or customize existing Commerce functionality. The SDK supports rapid development, full MSBuild integration, and package generation. The following image shows the relationship between the development environment and the cloud components.

Commerce components.

Note

The Retail SDK supports the Transport Layer Security (TLS) 1.2 standard. Any customization that you build by using the Retail SDK should follow the TLS 1.2 standard.

Download the Retail SDK

Note

If you are using Dynamics 365 Commerce application version 10.0.18 or later, use the SDK reference packages from the public feed. Also use the sample templates from the following GitHub repository (this is not required to use the SDK from the LCS Development machine).

Commerce Scale unit Sample repo

Commerce Instore components Sample repro

Public feed for reference package

The Retail SDK is available in development environments that are provisioned via Microsoft Dynamics Lifecycle Services (LCS), in the virtual hard disks (VHDs) that are downloaded from LCS, and in hotfix packages that are deployed to the LCS environment. For more information, see Deploy and access development environments and Apply updates to cloud environments.

Note

In release 10.0.21, the development VM in LCS will not include Visual Studio 2017 and other dependencies that are required for Commerce development. Install the prerequisites manually or by running MSBuild from the Retail SDK. Use the developer command prompt for Visual Studio 2019 to run the MSBuild command if Visual Studio 2017 tools are not installed in the VM. This will install all the prerequisites but POS build will not work with Visual Studio 2019 developer command prompt, it will fail with error saying POS doesn’t support Visual Studio 2019 .To fix this issue, after the prerequisites installation is complete, open the developer command prompt for Visual Studio 2017 and run MSBuild. Or, you can use PowerShell to run the checkVS2017Installed.ps1 script in RetailSDK\BuildTools to install the Visual studio tools for 2017 and then use the developer command prompt for Visual Studio 2017 to install the prerequisites and build the SDK.

To access the Retail SDK, sign in to the development virtual machine (VM), and go to the K:\RetailSDK folder. You can obtain new versions of the Retail SDK by applying any Commerce binary hotfix from LCS to the development environment. After hotfix deployment is completed, you can find the new version of the SDK inside the K:\RetailSDK\Update folder.

If the current version of the Retail SDK contains extensions, the configuration files and extension projects must be merged from the previous version of the SDK to the new version after an upgrade. This merge is required only if your previous version of the SDK includes extensions, and those extensions must be migrated to the new version. For more information and detailed instructions, see Upgrade the Retail channel extension to the latest Retail SDK. We recommend that you integrate the SDK with a source control system such as Git or Azure.

Full MSBuild integration

The Retail SDK is a build system. A simple MSBuild command from the root of the SDK folder builds everything. This functionality eliminates questions about how you should build and where you should build from. It also ensures consistency and reproducibility. Therefore, the Retail SDK can easily be integrated with a build pipeline such as Azure Pipelines. For more information, see Set up Commerce SDK build pipeline.

Prerequisites

To develop or build extensions by using the Retail SDK, you must have the following components:

Visual Studio 2017 has TypeScript 3.1 as the default version. You must install version 2.2.2 because the POS app is based on that version. In Visual Studio, select Tools > Get Tools and Features. On the Individual components tab, select the TypeScript 2.2 SDK from SDKs, libraries, and frameworks section, and install it.

If the SDK compilation fails with the following error message, "The current .NET SDK does not support targeting .NET Standard 2.0", try installing the x86 version of the .NET 2.1 SDK and runtime.

Build the Retail SDK

Before you start development via the Retail SDK, you must restore all the packages by using MSBuild to do a full build from the root of the SDK folder.

  1. Open the developer Command Prompt window for Visual Studio 2017 or the MSBuild 15.0 Command Prompt window.
  2. In the Command Prompt window, go to the Retail SDK folder.
  3. Run the msbuild /t:rebuild command from the root of the SDK folder. The dirs.proj file in the root of the SDK folder (RetailSDK\dirs.proj or RetailSDK\Code\dirs.proj) contains all the details that are required to build the full SDK.

MSBuild arguments to skip the prerequisites check

MSBuild will check whether the required dependencies are installed for Commerce development. If the dependencies are not found, then the MSBuild scripts will try to install the missing dependencies. This check will occur every time MSBuild runs. To skip this check, pass the following arguments as false:

MSBuild /p:CheckVS2017Installed=false /p:CheckVSDependencies=false – Build argument added in release 10.0.18

MSBuild /p:InstallDotNetRuntimeSdkdependencies=False – Build argument added in release 10.0.22

Running MSBuild from a Command Prompt window.

Retail SDK components

The following table shows the folders that the Retail SDK contains to help with extension development. The folder structure and descriptions in this table are based on Retail SDK version 10.0.13.

Folder or file Description
Assets This folder contains scripts and configuration files that are required for packaging. Only these configuration files (HardwareStation.Extension.config, RetailProxy.MPOSOffline.ext.config, CommerceRuntime.Ext.config, and CommerceRuntime.MPOSOffline.Ext.config) can be edited so that they include extension binary details for packaging.
  • manifest.json – The SDK binary version.
BuildTools This folder contains scripts, sample certificates, and a Customization.settings (packaging metadata) file. Don't change any files in this folder, except Customization.settings.
Database This folder contains shared database scripts. Extensions must copy the extension scripts to the Database\Upgrade\Custom folder.
Documents This folder contains instructions for running some of the samples.
OnlineStore This folder contains the end-to-end sample e-Commerce storefront solution that was built by using the Retail proxy.
Packages The Retail deployable package that is generated after the SDK build for packaging will be copied to this folder (Packages\RetailDeployablePackage). The Retail deployable package is deployed to different environments (test, sandbox, and production) by using LCS.
PaymentExternals Extension payment assemblies must be copied. The following three subfolders hold various payment files:
  • IPaymentProcessor Assemblies – This folder contains the assembly that implements the IPaymentProcessor interface and its dependent assemblies.
  • Payment Web Files – This folder contains the callback HTML, JavaScript, or Cascading Style Sheets (CSS) files that are required to make the payment accepting page available. Payment connector developers will provide these web files if their payment accepting page requires them.
  • IPaymentDevice Assemblies – This folder contains the assembly that implements the IPaymentDevice interface and payment request handlers, and the interface's dependent assemblies. These assemblies are used in Retail Hardware station and Retail Modern POS to communicate with payment terminal devices.

    Additionally, all extensions that are related to payment connectors should be put in this folder before you create the deployment packages.

Payments The folder contains the sample Payment Connector project for E-Commerce Add-in for Dynamics 365 Commerce.
pkgs This folder contains all the NuGet packages (reference libraries) that are required to build the extension projects and tools for packaging and Retail proxy generation.
POS This folder contains the POS app and extension project:
  • App – Modern POS–specific views and other items.
  • Contracts – Public contracts for POS extensions. Extension can consume only these contracts for POS extensions.
  • Extensions – Sample Extension projects and POS.Extension project that extension can consume.
  • Folder SharedApp – POS views that are shared between Cloud POS and Modern POS.
  • Folder Web – Cloud POS–specific views and other items.
  • CloudPos.sln – The Cloud POS solution file.
  • ModernPos.sln – The Modern POS solution file.
References This folder serves as the single location where all binaries are stored. It's used to resolve every project's binary references. The list of files includes external non-Commerce binaries and also Microsoft Commerce binaries. Additionally, this folder serves as the global drop location for any binaries that are built from the Retail SDK.
SampleExtensions This folder contains the sample projects and templates for extensions:
  • CommerceRuntime – Sample extension projects for business logic extensions (Commerce runtime [CRT] triggers, handlers, and new service extension).
  • HardwareStation – Sample Hardware station extension projects.
  • HybridApp – Android and iOS shell apps for the POS. Extension can build these apps and deploy them to the Android and iOS platforms.
  • OnlineStore – The sample online storefront app.
  • RetailProxy – The sample C# proxy project for POS offline mode. As of version 10.0.11, the C# proxy is obsolete (deprecated). The Headless Commerce extension libraries can be used directly in offline mode. You don't have to have separate proxy libraries.
  • RetailServer – Sample Headless Commerce extension projects.
  • SampleExtensionsTest – The sample project for creating an extension test project.
  • ShoppingApp – The sample mobile app (Retailer shopping app) for users in Android and iOS.
  • TypeScriptProxy – Sample proxy projects that show how to generate TypeScript for the POS.
dirs.proj This project file directs the build order.
Microsoft-version.txt This file includes the Microsoft application version of the Retail SDK.

Extension components in the Retail SDK

The following tables provide information about the components in the Retail SDK that must be customized for different scenarios. Only the sample projects inside the RetailSDK\SampleExtensions folder can be changed for extension purposes. No other files or projects/scripts in the Retail SDK should be changed.

Client (POS)

Scenario Extend the POS for user experience (UX) changes, client logic, workflows, and simple validations.
Commerce SDK reference \RetailSDK\POS

Open the ModernPos.sln or CloudPos.sln file, and add an extension to the POS.Extension project. Don't change anything in the core POS app/web projects.

Technology TypeScript, HTML, and CSS
Documentation Run the point of sale (POS) samples

CRT

Scenario Extend CRT to add or change business logic (for example, logic for calculating tax, prices, or discounts).
Commerce SDK reference \RetailSDK\SampleExtensions\CommerceRuntime

Open the CommerceRuntimeSamples.sln file.

Technology C#
Documentation Commerce runtime (CRT) and Retail Server extensibility

Headless Commerce APIs

Scenario Create a Headless Commerce API extension to expose new Commerce APIs to the client.
Commerce SDK reference \RetailSDK\SampleExtensions\RetailServer

Open any of the sample extensions inside the RetailServer folder.

Technology Open Data Protocol (OData) and C#
Documentation Create a new Retail Server extension API (Retail SDK version 10.0.11 and later)

TypeScript proxy

Scenario A TypeScript proxy is required if new Headless Commerce API extensions must be consumed in the POS or E-Commerce clients.
Commerce SDK reference \RetailSDK\SampleExtensions\RetailServer

Open any of the sample extensions inside the RetailServer folder.

Technology OData and C#
Documentation Create a new Retail Server extension API (Retail SDK version 10.0.11 and later)

Hardware station

Scenario A Hardware station is required to add or change logic that is related to peripherals.
Commerce SDK reference \RetailSDK\SampleExtensions\HardwareStation

Open the HardwareStationSamples.sln file.

Technology C#
Documentation Integrate POS with a new hardware device

Payment connector

Scenario Integrate the POS with a new payment connector.
Commerce SDK reference \RetailSDK\SampleExtensions\HardwareStation\\Extension.PaymentSample

Open the HardwareStation.Extension.PaymentSample.sln file.

Technology C#
Documentation Create an end-to-end payment integration for a payment terminal

Best practices for naming

The C# source code in the Retail SDK uses the Contoso namespace. Therefore, it's easier to distinguish Microsoft types and extension types. If your extension code references a type from the Microsoft binary, use Microsoft.Dynamics for the reference, to distinguish between Microsoft libraries and the libraries from the extension. The extension libraries must not begin with the Microsoft.Dynamics name.

Deployment packages

After extension development (CRT, Retail Server, database scripts, POS, and Hardware station), you can use the Retail SDK to generate deployment packages. Packages can be deployed to test, sandbox, and production environments. For more information, see Create deployable packages.

Dependencies, build order, and full builds

You should build all the extensions and required out-of-box projects. (Use MSBuild to do a full build from the root of the SDK folder.)

  • You should build your extension, POS, and packaging projects, but you don't have to build the sample projects that are included in the Retail SDK. You can edit the dirs.proj file in the Retail SDK to remove unwanted sample projects, but don't remove the packaging and POS projects from the list.
  • Include the extension project in the dirs.proj file of the appropriate folder. In that way, when you run MSBuild from the root of the SDK folder, all the extension and required out-of-box projects are built.
  • The dirs.proj file in the root of the SDK folder is sequenced in the correct order to build all the required projects and then the packaging project. The sequence must be correct. Otherwise, the project and dependencies won't be built correctly.

Regular configuration/code signing

For Modern POS, create an app package signing certificate to build correctly, or use Cloud POS. For information about how to create a PFX file, see Create a certificate for package signing. Then copy the PFX file to the BuildTools folder, and update the BuildTools\Customization.settings file with the correct name by using the ModernPOSPackageCertificateKeyFile element.

The BuildTools\Customization.settings file holds most of the configuration values for the Retail SDK.

<!-- This section is for global settings and code signing. Any build file will inherit these values if applicable.
also use these values during package generation. -->
<AssemblyNamePrefix>MyCompany</AssemblyNamePrefix>
<CustomAssemblyVersion Condition="'$(CustomAssemblyVersion)' == ''">1.0.0.0</CustomAssemblyVersion>
<CustomVersion Condition="'$(CustomVersion)' == ''">1.0.0.1</CustomVersion>
<CustomName Condition="'$(CustomName)' == ''">MyCompany Retail Customization</CustomName>
<CustomDescription Condition="'$(CustomDescription)' == ''">MyCompany Retail Customization</CustomDescription>
<CustomPublisher Condition="'$(CustomPublisher)' == ''">MyCompany Ltd.</CustomPublisher>
<CustomCopyright Condition="'$(CustomCopyright)' == ''">MyCompany (c) 2015</CustomCopyright>

<SignAssembly Condition="'$(SignAssembly)' == ''">true</SignAssembly>
<DelaySign Condition="'$(DelaySign)' == ''">false</DelaySign>
<AssemblyOriginatorKeyFile Condition="'$(AssemblyOriginatorKeyFile)' == '' and '$(SignAssembly)' == 'true'">
    $(MSBuildThisFileDirectory)\StrongNameSigningCert-Contoso.snk</AssemblyOriginatorKeyFile>

<ModernPOSPackageCertificateKeyFile Condition="'$(ModernPOSPackageCertificateKeyFile)' == ''">
    $(MSBuildThisFileDirectory)\ModernPOSAppxSigningCert-Contoso.pfx</ModernPOSPackageCertificateKeyFile>

<RetailServerLibraryPathForProxyGeneration Condition="'$(RetailServerLibraryPathForProxyGeneration)' == ''">
    $(SdkReferencesPath)\Microsoft.Dynamics.Retail.RetailServerLibrary.dll</RetailServerLibraryPathForProxyGeneration>

The following values are the global values. These values control how the build manages binaries, components, and how packages are named, versioned, and code-signed.

  • AssemblyNamePrefix
  • CustomAssemblyVersion
  • CustomVersion
  • CustomName
  • CustomDescription
  • CustomPublisher
  • CustomCopyright
  • SignAssembly
  • AssemblyOriginatorKeyFile
  • ModernPOSPackageCertificateKeyFile
  • RetailServerLibraryPathForProxyGeneration

It's a good practice to sign your assemblies by using a strong name, even though a strong name isn't required. For information about how to create your own key file if you don't already have one, see How to: Create a public-private key pair.

The installer files that are generated for self-service components such as Modern POS, Hardware station, and Store scale unit can be signed by using SignTool.exe.

Both the key file for the strong name and the app package signing certificate can be stored inside the BuildTools folder or in Azure Key Vault. For a password-protected or secured certificate, use Azure Key Vault.

Customizing the build

Adding new projects

It's easy to add new projects to the Retail SDK's build system. You can either clone one of the many existing projects or start a new project. You just have to make some adjustments in a text editor, as shown in the following illustration. The relative path of the Import elements should be adjusted, and the AssemblyName element should use the predefined AssemblyNamePrefix property. These adjustments are required to get various tasks for free, such as versioning, code signing, uniform assembly naming, and automatic dropping to the References folder.

Code for adding new projects.

Changing the build order or adding to the build

MSBuild traversal files (dirs.proj files) are used to build the whole directory tree of the Retail SDK. The following illustration shows the main traversal file of the Retail SDK. Similar files might also exist in subdirectories. Notice that Visual Studio solution files (.sln files) are similar to traversal files. Both types of file direct the MSBuild engine to process other build scripts.

Code for changing the build order or adding to the build.

After new code is added, most of it should be put in a new folder. You must also add it to the traversal structure by adding it to one or more dirs.proj files. In the previous illustration, the Extensions folder is highlighted on line 10. The quickest way to get started with a new dirs.proj file is to copy an existing file, correct the paths in the Import elements, and update the ProjectFiles elements in the ItemGroup element.

Customizing build scripts

When you must implement new build steps, remember that the existing scripts might be updated by a Retail SDK update later. The best practice is to minimize edits to any file, or to add new files instead. If you require new global MSBuild properties, the BuildTools\Microsoft.Dynamics.RetailSDK.Build.props file is a good place to add them. Likewise, the BuildTools\Microsoft.Dynamics.RetailSDK.Build.targets file can be used to add new build processing targets.

If only one project requires special handling, it's better to explicitly make the change there. If you require new local MSBuild properties, add a local.props file in the same directory. Alternatively, if you require local build processing targets, add a local.targets file.

Developer productivity

The CommerceRuntime and RetailServer extension dynamic-link libraries (DLLs) must be copied into the bin folder of the locally installed RetailServer web application. Users can configure the Customization.setting file so that the DLLs are automatically copied into the bin folder of the local RetailServer web application whenever new versions of these files are built from the extension project.

Code for automatically adding new DLLs.

Application Lifecycle Management

A good Application Lifecycle Management (ALM) solution provides version control, builds, automated builds, planning tools, tracking tools, dashboards, customization, and more. The organization of the Retail SDK supports these tasks.

Branching and versioning

To work efficiently in a team, or even just to be able to go back and look at some changes that were made earlier, you must have a good branching strategy and versioning discipline. The following illustration shows a simple branching strategy that might work well for most teams. The version numbers are fictitious. For more information, see, Adopt a Git branching strategy.

Branching and merging.

Retail SDK mirror branch

It's important to emphasize that the non-customized Retail SDK should be stored in your source control. You don't have to store every version, but the versions that your team wants to snap to should be added. (Those versions might be cumulative updates or hotfixes.) Only a simple merge of all changes (that is, additions, changes, and deletions) should be done. No other development work should occur in this branch. The Retail SDK has its own version. All Commerce binaries and packages that are included have the same version. The version can also be found in the root of the SDK folder, in a file that is named Microsoft-version.txt.

Customization branch

For development, a new customization branch should be created. At the beginning of the initial branch-out, this branch will be an exact copy of the Retail SDK mirror branch. It's the branch that will be used for the team's development. The version of the customization branch must be incremented at least every time that a build is created for testing. It can even be incremented every day. The file version to increment is defined by using the CustomVersion property in the Customization.setting file. If you update the version and rebuild, all binaries, packages, and manifest files are updated accordingly.

The CustomAssemblyVersion property should be updated only when the update isn't backward-compatible and/or for major new releases. In other words, you should rarely update this property. In the previous illustration, the current file version of the customization branch is 1.0.2.* (based on Microsoft version 7.0.2200.3). The file version of the first rolled-out release was 1.0.0.40 (based on Microsoft version 7.0.2000.0). When a testing phase is completed, and the final packages are being deployed with that version, it's important that you either increment the version or create a source control label.