-->

This topic 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.

Retail Pro® 2009 PA-DSS/PABP Guide Retail Pro International, LLC 400 Plaza Dr., Suite 200 Folsom, CA 95630 USA USA 1-800-738-2457 International +1-858-550-3355.

  • For over 25 years, RPI has innovated retail software solutions to help retailers optimize business operations and have more time to focus on what really matters - cultivating customer engagement and capitalizing on retail's trends. Retail Pro is the chosen software platform for omni-channel strategy by retailers in 130+ countries.
  • Jul 05, 2018 Downloading. Thank you for using our software portal. The legal way for you to obtain the program is to contact the developer for purchasing information. We wish to inform you that, in this case, the program you are trying to download is commercial and not free, which means that no freeware or function-restricted version is.
  • SID Retail PRO SP3 V 5.0.0 is a program developed by software-id.com. The software installer includes 30 files and is usually about 35.19 MB (36,896,377 bytes). In comparison to the total number of users, most PCs are running the OS Windows XP as well as Windows 7 (SP1).
  • Monitorian is a Windows 7, 8, and 10 application designed to simplify multiple monitors' brightness. MajorGeeks Windows Tweaks contains 216 files including registry, PowerShell, Visual Basic, shortcuts, and batch files to enable tweaks and hidden features in Windows 10, 8, and 7 for any skill level.

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).

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:RetailSDKUpdate 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 runtimes:

    • TypeScript version 2.2.2

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.

Sid

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.

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 (RetailSDKdirs.proj or RetailSDKCodedirs.proj) contains all the details that are required to build the full SDK.

Note

Starting in Retail SDK version 10.0.18 or later, by default the retail SDK MSBuild will check whether the SDK prerequisites are installed, if not it will show the error message and scripts to run to install the prerequisites. You can skip the prerequisites check by passing the parameter MSBuild /p:CheckVSDependencies=false.

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 fileDescription
AssetsThis 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.
BuildToolsThis folder contains scripts, sample certificates, and a Customization.settings (packaging metadata) file. Don't change any files in this folder, except Customization.settings.
DatabaseThis folder contains shared database scripts. Extensions must copy the extension scripts to the DatabaseUpgradeCustom folder.
DocumentsThis folder contains instructions for running some of the samples.
OnlineStoreThis folder contains the end-to-end sample e-Commerce storefront solution that was built by using the Retail proxy.
PackagesThe Retail deployable package that is generated after the SDK build for packaging will be copied to this folder (PackagesRetailDeployablePackage). The Retail deployable package is deployed to different environments (test, sandbox, and production) by using LCS.
PaymentExternalsExtension 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.

PaymentsThe folder contains the sample Payment Connector project for E-Commerce Add-in for Dynamics 365 Commerce.
pkgsThis folder contains all the NuGet packages (reference libraries) that are required to build the extension projects and tools for packaging and Retail proxy generation.
POSThis 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.
ReferencesThis 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.
SampleExtensionsThis 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.projThis project file directs the build order.
Microsoft-version.txtThis 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 RetailSDKSampleExtensions folder can be changed for extension purposes. No other files or projects/scripts in the Retail SDK should be changed.

Client (POS)

ScenarioExtend the POS for user experience (UX) changes, client logic, workflows, and simple validations.
Commerce SDK referenceRetailSDKPOS

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.

TechnologyTypeScript, HTML, and CSS
DocumentationRun the point of sale (POS) samples

CRT

ScenarioExtend CRT to add or change business logic (for example, logic for calculating tax, prices, or discounts).
Commerce SDK referenceRetailSDKSampleExtensionsCommerceRuntime

Open the CommerceRuntimeSamples.sln file.

TechnologyC#
DocumentationCommerce runtime (CRT) and Retail Server extensibility

Headless Commerce APIs

ScenarioCreate a Headless Commerce API extension to expose new Commerce APIs to the client.
Commerce SDK referenceRetailSDKSampleExtensionsRetailServer

Open any of the sample extensions inside the RetailServer folder.

TechnologyOpen Data Protocol (OData) and C#
DocumentationCreate a new Retail Server extension API (Retail SDK version 10.0.11 and later)

TypeScript proxy

ScenarioA TypeScript proxy is required if new Headless Commerce API extensions must be consumed in the POS or E-Commerce clients.
Commerce SDK referenceRetailSDKSampleExtensionsRetailServer

Open any of the sample extensions inside the RetailServer folder.

TechnologyOData and C#
DocumentationCreate a new Retail Server extension API (Retail SDK version 10.0.11 and later)

Hardware station

ScenarioA Hardware station is required to add or change logic that is related to peripherals.
Commerce SDK referenceRetailSDKSampleExtensionsHardwareStation

Open the HardwareStationSamples.sln file.

TechnologyC#
DocumentationIntegrate POS with a new hardware device

Payment connector

ScenarioIntegrate the POS with a new payment connector.
Commerce SDK referenceRetailSDKSampleExtensionsHardwareStationExtension.PaymentSample

Open the HardwareStation.Extension.PaymentSample.sln file.

TechnologyC#
DocumentationCreate an end-to-end payment integration for a payment terminal

Best practices for naming

Software

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 BuildToolsCustomization.settings file with the correct name by using the ModernPOSPackageCertificateKeyFile element.

The BuildToolsCustomization.settings file holds most of the configuration values for the Retail SDK.

Retail

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.

Retail

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.

Download Software Sid Retail Products

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 BuildToolsMicrosoft.Dynamics.RetailSDK.Build.props file is a good place to add them. Likewise, the BuildToolsMicrosoft.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

Download Software Sid Retail Pro Software

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.

Download Software Sid Retail Product

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.