Retail software development kit (SDK) architecture


This topic applies to Dynamics 365 Retail and Dynamics 365 Commerce (Preview).

This topic provides general information about the Retail SDK. The Retail SDK includes code, code samples, templates, and tools that you can use to customize retail functionality.


The Retail software development kit (SDK) includes code, code samples, templates, and tools that you can use to add new or customize existing retail functionality. The SDK supports rapid development, full MSBuild integration, package generation, and code separation.


The Retail SDK supports TLS (Transport Layer Security) 1.2 standard, any customization build using the Retail SDK should follow TLS 1.2 standard.

Download the Retail SDK

The Retail SDK is available in development environments, and in hotfix packages in a Retail SDK folder. For more information see:

  • If you get the SDK from a development instance, it is immediately ready for configuration and use. For more information, see Access instances.
  • If you get the SDK from a hotfix, it is included in the hotfix package as a zipped folder. Retail hotfixes are cumulative and includes all other fixes.

We recommend that you put the SDK in a source control system such as Visual Studio Online.

Rapid development

The main focus of the Retail SDK is to help you write customizations efficiently and correctly. The SDK lets you run applications directly in a single-computer demo environment by using the F5 functionality (run and debug) in Microsoft Visual Studio. All the required "deployment chores" are done for you. Therefore, you don't have to copy any files.

Full MSBuild integration

The Retail SDK is a build system. A simple MSBuild command from the root of the SDK builds everything. This behavior eliminates guesswork about how and where to build from, and guarantees consistency and reproducibility. Therefore, the Retail SDK can easily be used together with any application lifecycle management (ALM) system, even Microsoft Visual Studio Online. This integration includes automation of the build.

Creation of final update packages, and better and explicit control over the customization

The Retail SDK includes tools that generate new packages that include everything that is required in order to deploy a service. For example, if the commerce runtime is extended with a new custom service dynamic-link library (DLL), the SDK automatically includes the new DLL in all appropriate packages (RetailServer and MPOSOffline). Or, if the database is extended, the upgrade script is automatically included in both RetailServer and MPOSOffline packages, because these are the packages that must (potentially) run the channel database update. Files that are shared exist only one time in the SDK. The packaging projects are set up in such a way that they pull in the right files for the package. Therefore, you edit a commerceruntime.config file in only one place. The same applies for deployment-related script files, even though these files rarely require customization.

Better code separation

If the Retail SDK needs to be updated, a potential code merge is required. This requirement applies to existing code samples or templates that have been changed. Some features in the implementation and in the folder structure of the SDK help to provide an easy way to separate customized code from sample code. You can expect to see additional improvements to code separation in future releases.

Real-world implementation samples

In addition to the source code of some of the Retail implementations, the Retail SDK includes sample code that illustrates how certain scenarios should be implemented.

Retail SDK deep dive


  • To code or build your customization, you must have the following tools:

    • Microsoft Visual Studio 2015 with Typescript 1.5 (an LCS developer topology is acceptable)
    • ASP.NET MVC 4.0 (an LCS developer topology acceptable) (required only by StoreFront)
    • A minimum of 150 MB of available disk space (an LCS developer topology is acceptable)

    This list of requirements is very short and lets developers be productive on simple laptops. There is no longer a prerequisite for a validation utility.

  • To run your customization, the normal prerequisites to run Retail apply. We recommend that you run the customizations on a single-box developer topology (either LCS cloud-hosted or downloaded) during development.

Retail SDK contents

The following folders and files are part of the Retail SDK at the top level.


The folder structure and description above are applicable only for the Retail July 2017 update (7.2). In the Retail 7.3 release, we sealed the Retail proxy and Hardware station projects. Therefore, in the Retail 7.3 release, you will see only samples for Hardware station and retail proxy. The proxy can be generated by following the new extensibility pattern.

Folder/file Description
Assets Contains shared items such as scripts and configuration files (commerceRuntime.config, dllhost.exe.config, and so on). The configuration files should be customized and edited in this location. The projects that use them will pick them up appropriately.
BuildTools Contains anything that is related to the MSBuild and global configurations. Customization.settings is the main file that is used to set up the build system. The following list shows the items that this file controls and that customizers will likely change:
  • Prefix for all built assemblies (AssemblyNamePrefix)
  • Assembly version for all binaries (CustomAssemblyVersion)
  • File version for all binaries (CustomVersion)
  • Name of the customization (CustomName)
  • Description of the customization (CustomDescription)
  • Publisher (CustomPublisher)
  • Code signing (SignAssembly, AssemblyOriginatorKeyFile)
  • Modern POS certificate path (ModernPOSPackageCertificateKeyFile)
  • Files that are related to the customization (RetailServerLibraryPathForProxyGeneration, ISV\_\*)
CommerceRuntime Contains a Visual Studio solution file (CommerceRuntime.sln) and related C# projects (CommerceRuntime, PricingEngine).
Database Contains shared database scripts. The full script CommerceRuntimeScripts\_Create.sql is used only to create a new base database. The Upgrade folder includes incremental scripts from both Microsoft and the customizer. The existence of the database or the version in the database during a deployment controls which full or incremental scripts will be run. Only scripts that haven't been run before will be run.
HardwareStation Contains a Visual Studio solution file (HardwareStation.sln) and related C# projects (HardwareStation libraries and Webhost).
OnlineStore Contains a Visual Studio solution file (OnlineStore.sln) and related C# projects (Ecommerce SDK).
Packages Contains multiple projects for package creation. These packages are used to deploy via LCS. These packages also include the final web.config files.
PaymentExternals Contains all the payment-related assemblies. 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 CSS files that are required in order to enable the payment accepting page. 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 Point of Sale (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 Contains a Visual Studio solution file (PaymentSDK.sln) and related C# projects (PaymentSDK connectors, samples and functional test).
POS Contains files for POS:
  • CloudPos.sln
  • ModernPos.sln
  • Folder Core – Low-level shared POS code
  • Folder ViewModels – Shared POS view models
  • Folder SharedApp – Shared POS views
  • Folder App – Modern POS–specific views and other items
  • Folder Web – Cloud POS–specific views and other items
Proxies Contains two Visual Studio projects that are referenced by others. These projects contain interfaces and generated code that serves as a proxy client of Retail Server. Proxies.Retail.TypeScript is the TypeScript proxy, and RetailProxy is the C# proxy. They are used by Modern POS/Cloud POS and the ECommerce SDK.
References The single place where all binaries live. The location is used to resolve any project's binary references. The list of files includes external non-Retail binaries and also Microsoft Retail binaries. Additionally, this directory serves as the global drop location for any binaries that are built from the Retail SDK.
SampleExtensions Contains sample extensions.
dirs.proj The top-level MSBuild file that directs the build order.
Microsoft-version.txt A file that includes the Microsoft version of the Retail SDK. Don't edit this file.

The C# source code in the SDK uses the Contoso namespace. Therefore, it's easier to distinguish Microsoft types and your own types, because Microsoft uses Microsoft.Dynamics. If you're referencing a type from the Microsoft binary, reference it by using Microsoft.Dynamics. That way, you'll know that it's not from the Retail SDK but from a referenced binary.

Code sample to reference a type

Dependencies, build order, and full build

The following illustration shows a high-level logical dependency tree within the Retail SDK. It doesn't show the references to all Microsoft files or assets. To see these, look at the Visual Studio project and solution files in more detail.

Diagram of high-level logical dependency tree

Consider the following important points:

  • The RetailServer API is consumed by a few projects by means of automatically generated client proxy code. This behavior allows for more rapid development, and reduces opportunities for errors and bugs. By default, the Retail SDK uses the official Microsoft DLL to generate the client code. Customizers can switch to their own DLL (in Customization.settings) and therefore automatically generate the proxy code for their customized RetailServer API. After switching the DLL, a developer might have to change some implementations inside the RetailProxy project. The reason is that Modern POS in offline mode must communicate directly with the commerce runtime, and that code must be implemented. However, no guesswork is required. The C# compiler will force it.
  • The packaging projects generate the deployment packages in the way that LCS expects them. By default, these projects will ship only the Microsoft assets (non-customized) and the proxy DLLs. Anything else that should be included must be explicitly named in Customization.settings. This behavior is by design. It reduces the deployed custom code and allows for binary patches. For example, a customization adds a new CommerceRuntime service and a new RetailServer controller. In this case, two new DLLs are registered for inclusion in the packages and are automatically included in all relevant places. The packages will not have all recompiled binaries from the SDK.
  • There is no single Visual Studio solution that includes all projects. Because there are few couplings between the various Visual Studio projects, you can open multiple projects or solutions side by side, and can compile the appropriate project after a change.
  • Even if you didn't customize every component, the easiest way to get the final deployment packages is by building the whole Retail SDK. To do this, open an MSBuild Command Prompt for VS2015 window, and enter msbuild (or msbuild /p:Configuration=Release for a non-debug version).

Screenshot of MSBuild command prompt

This command will build all projects. This approach also provides a great way to verify that there are no implementation or code bugs. If there are any bugs, the build will fail, and the Command Prompt window will show what failed (this output resembles what Visual Studio would show).

Screenshot of MSBuild command prompt with sample code

For detailed help for MSBuild, see

The binaries that the build creates are automatically copied to the SDK's References folder. The References folder also includes all the other binaries. Notice that no DLLs are overwritten, because they are all prefixed with a name (in this case, "Contoso") that you can define in Customization.settings.

Screenshot of Retail SDK's Reference files

Minimal required configuration

Do you just want to quickly build the Retail SDK, or to run POS in the debugger on a demo machine? For Modern POS only, you must create an app package signing certificate in order to build correctly. Alternatively, you can use Cloud POS. Follow the instructions at to create a PFX file. Then copy the PFX file to the BuildTools folder, and update the BuildTools\Customization.settings file with the correct name (ModernPOSPackageCertificateKeyFile). At this point you have everything that you require in order to build individual solutions, projects, or the whole Retail SDK (by using MSBuild).

Normal configuration/code signing

BuildTools\Customization.settings holds most of the configuration values for the SDK. The highlighted items in the following illustration are the global values. These values control how built binaries, components, and packages are named, versioned, and code-signed.

Screenshot of code for BuildTools Customization settings

It's good practice to sign your assemblies with a strong name, even though this isn't required. To learn how to create your own key file if you don't already have one, see To build correctly, you must create an app package signing certificate. Follow these instructions at to create a PFX file. Both the strong name key file and the app package signing certificate can be stored inside the BuildTools folder. The RetailServerLibraryPathForProxyGeneration property can be used to set a different RetailServer DLL for proxy generation. Customization.settings is also the place to define your new customization assets, such as binaries, configuration files, and SQL update scripts. After you specify your extensions, binaries, and assets here, the files will be added in the deployable package that is created.

Screenshot of code for additional files

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 in order to get versioning, code signing, uniform assembly naming, automatic dropping to the References folder, and other tasks for free.

Screenshot of code for adding new projects

Changing the build order or adding to the build

The whole directory tree of the Retail SDK is built with the help of MSBuild traversal files (dirs.proj files). 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 very similar to traversal files. Both "direct" the MSBuild engine to process other build scripts.

Screenshot of code for changing build order or adding to build

After new code is added, most of it should be located in a new folder (for details, see "Best practices of code implementation"), and you must add it to the traversal structure by adding to one or multiple dirs.proj files. The Extensions folder appears highlighted on line 10 in the previous illustration. 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.

Build script customization

When you must implement new build steps, keep in mind that the existing scripts might be updated by a Retail SDK update later. Best practice is to minimize the editing of any file, or add new files instead. If you require new global MSBuild properties, BuildTools\Microsoft.Dynamics.RetailSDK.Build.props is a good place to add them. Likewise, BuildTools\Microsoft.Dynamics.RetailSDK.Build.targets can be used to add new build processing targets. If only one project requires special handling, it is better to explicitly make the change there. If you require new local MSBuild properties, add a new file that is named local.props in the same directory. Alternatively, add a local.targets file if you require local build processing targets.

Developer productivity

As shown in the architecture diagram earlier in this article, several things depend on the RetailServer interface. It is likely that someone will change this interface. On a developer topology machine, someone might want to immediately try out a change. In this case, any CommerceRuntime and RetailServer extension DLLs must be copied into the bin folder of the locally installed RetailServer web application. A user 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.

Screenshot of code to automatically add new DLLs

Application lifecycle management

A good ALM solution provides version control, builds, automated builds, planning tools, tracking tools, dashboards, customization, and more. The Retail SDK is organized in such a way that it supports these tasks.

[Azure DevOps](/Azure DevOps/) is a great tool and is recommended.

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 done in the past, you must have 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.

Diagram of branching and merging

Retail SDK mirror branch

A very important point to emphasize is 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 (these versions might be cumulative updates or hotfixes). Only a simple merge of all changes (additions, changes, and deletions) should be done. No other development work should occur in this branch. The Retail SDK has its own version. All Retail binaries and packages that are included have the same version. The version can also be found in the root of the Retail SDK in a file that is named Microsoft-version.txt.

Customization branch

After development can start, a new branch should be started (customization branch). At the beginning of the initial branch-out, this branch will be an exact copy of the Retail SDK mirror branch. This is the branch for a team's development. The version of the customization branch must be incremented at least every time that a build is created for testing, or it can even be incremented daily. The file version to increment is defined in Customization.setting file by using the CustomVersion property. If you update it and rebuild, all binaries, packages, manifest files are updated accordingly. Note that the CustomAssemblyVersion property should be updated only when the update isn't backward compatible and/or for major new releases. In other words, this update should very rarely. For example, Microsoft's assembly version stayed the same for the multiple CTP releases for the current version. Because there are both Microsoft assets and your own changes in the same branch, the branch essentially has two file versions. The first version is the Microsoft version of the Retail SDK that the current branch is based on, and the second version is the version that is set by the CustomVersion 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 (based on 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 increment the version (or create a source control label).