Retail software development kit (SDK)

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.

Download the Retail SDK

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.

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 Community, Professional, or Enterprise edition (VM) that has the following components:

  • .NET Desktop development
  • Universal Windows Platform development
  • ASP.NET and web development
  • Azure development
  • Node.js development
  • .NET Core cross-platform development
  • Mobile development with .NET (required for hybrid app development)

• The following SDK and runtimes:

  • sdk-2.1.202-windows-x64-installer
  • sdk-2.1.513-windows-x64-installer
  • runtime-2.0.9-windows-x64-installer
  • runtime-2.1.17-windows-x64-installer
  • .NET Core 3.1 SDK
  • Windows SDK (10.0.10586.0)
  • TypeScript version 2.2.2

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.

• .NET Developer Pack:

  • .NET Framework 4.5.1
  • .NET Framework 4.6.2
  • .NET Framework 4.7.2

• Web Deploy v4.0

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.

• .NET Core 2.1 SDK
• .NET Core 2.1 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

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.

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)

CRT

Headless Commerce APIs

TypeScript proxy

Hardware station

Payment connector

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.

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.

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.

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.

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.