Create retail deployable packages

Important

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

This topic explains how to create a Retail deployable package (which is a package that contain all the extensions) for the following Retail components and deploy the package to your environment by using Microsoft Dynamics Lifecycle Services (LCS):

  • Commerce runtime (CRT)
  • Retail proxy
  • Retail Server
  • Modern POS
  • Cloud POS
  • Hardware station
  • Channel database scripts
  • Payment connector
  • Retail Store Scale Unit
  • Hybrid app (IOS and Android POS app)

Retail deployable package

A retail deployable package is one combined package that contains all your customizations together with all the metadata that is required for deployment. You can use this retail deployable package to deploy your customizations to various environments. You can do the deployment by using the automated flow in LCS, or you can do it manually by using the scripts that are provided inside the package. This topic guides you through the process of generating the retail deployable package.

Important

All customizations for the Retail components are packaged as a single retail deployable package. Separate packages for individual Retail components, such as Modern POS, Cloud POS, Retail Store Scale Unit, CRT, and Retail Server are not supported. You must package all extensions as a single retail deployable package, even if you must merge or combine extensions from independent software vendors (ISVs) or various partners.

If your customizations were built and packaged as individual Retail component packages by using a version of the Retail software development kit (SDK) that is older than application version 7.1.1541.3036, the packages are no longer supported for deployment in LCS. You must uptake the hotfix in KB 4015062, and then rebuild and repackage your customizations.

For detailed information about the Retail SDK, see Retail software development kit (SDK) architecture.

Steps to create a retail deployable package

There are two ways to generate a retail deployable package. You can use the Retail build automation, or you can generate the package manually by using the build tools in the Retail SDK. This topic focuses on the manual method.

  1. Customize or add functionality to the Retail stack.
  2. Use the build tools to identify the customized installation package, code-sign it, and specify the customized CRT, Retail Server, and Hardware station assemblies, and customized database scripts.
  3. After all the settings have been specified in the Customization.settings file in the ...\Retail SDK\BuildTools folder, run msbuild /t:rebuild on the root of the Retail SDK folder. You can use either the MSBuild build tool or the Microsoft Visual Studio developer command-line tool to generate the retail deployable packages. Before you build the package, put all the customized assemblies in the ...\Retail SDK\References folder. Additionally, put the modified configuration files, such as CommerceRuntime.Ext.config, CommerceRuntime.MPOSOffline.Ext.config, HardwareStation.Extension.config, and RetailProxy.MPOSOffline.ext.config, in the ...\Retail SDK\Assets folder.

Retail SDK build tools – Customization settings

Most of the configuration values that the Retail SDK uses to build and package customizations are set in the BuildTools\Customization.setting files. These values define metadata that controls how binaries, components, and packages are named, versioned, and code-signed. After you define this metadata, the Retail SDK build system uses it to identify the customization assets and package them for all the Retail components.

The following configuration settings are available in the 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 to sign the assembly during the build.

  • DelaySign – Specify True to delay signing of the assets during the build.

  • AssemblyOriginatorKeyFile – Specify the strong name key to use to sign the assembly.

  • ModernPOSPackageCertificateKeyFile – Specify the Personal Information Exchange (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# proxies).

    For 7.1 and earlier versions, you must specify the name of the Retail Server assembly here.

    For 7.2 and later versions, use the commerce generator tool for proxy generation. However, if you're using the proxy on the e-commerce client side, specify the assembly name here.

  • The ItemGroup section includes the following settings:

    • ISV_CommerceRuntime_CustomizableFile – Specify the details of all the customized CRT and dependent assemblies. You can have multiple entries, one for each assembly.

Note

If the extension depends on Newtonsoft.Json.Portable or some other assemblies, then explicitly include it. Don’t assume that these assemblies will be included by default in the packaging or Retail server folder because the out-of-band (OOB) Retail server or CRT is using this. In the future, if the OOB functionalities don’t use these assemblies, it could be removed. As a result, you should always explicitly include all of the extension dependent assemblies in order to package and place them in the correct folder.

Example

        ISV_CommerceRuntime_CustomizableFile Include="$(SdkReferencesPath)\MyCrtExtension.dll"
  • ISV_RetailServer_CustomizableFile – Specify the details of all the customized Retail Server assemblies. You can have multiple entries, one for each Retail Server assembly.

Example

        ISV_RetailServer_CustomizableFile Include="$(SdkReferencesPath)\MyRetailServerExtension.dll"
        ISV_RetailServer_CustomizableFile Include="$(SdkReferencesPath)\MyRetailServerExtension2.dll"
  • ISV_RetailProxy_CustomizableFile – Specify the details of all the customized Retail proxy assemblies. You can have multiple entries, one for each Retail proxy assembly.

Example

        ISV_RetailProxy_CustomizableFile Include="$(SdkReferencesPath)\MyRetailProxyExtension.dll"
  • ISV_HardwareStation_CustomizableFile – Specify the details of all the customized Hardware station assemblies. You can have multiple entries, one for each customized Hardware station assembly.

Example

   ISV_HardwareStation_CustomizableFile Include="$(SdkReferencesPath)\MyHardwareStationExtension.dll"
  • ISV_CustomDatabaseFile_Upgrade_Custom – Specify the details of all the customized database scripts.

Example

    ISV_CustomDatabaseFile_Upgrade_Custom Include="$(SdkRootPath)\Database\Upgrade\Custom\SqlUpdatev1.sql"

Important

Before you start the build process, you must put extension assemblies in ...\Retail SDK\References and custom database scripts under ...\RetailSDK\Database\Upgrade\Custom.

Database scripts

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, to run the scripts in a specific order, you must name them accordingly. The CRT.RETAILUPGRADEHISTORY table tracks the scripts that are already applied to the database. Therefore, the next package upgrade runs only the upgrade scripts that don't have an entry in the CRT.RETAILUPGRADEHISTORY table.

For more details about Channel database extensions, see Channel database extensions.

Update the extension configuration files

If you have any new extensions in CRT, Retail Server, Hardware station, or proxy, you should register the details of the extension assemblies in the <composition> section of the relevant extension configuration file. You can find all the extension configuration files in the ...\RetailSDK\Assets folder. Because all extensions are loaded based on the information in the extension configuration files, you must register your assemblies there.

Before you do the package, you must update the following configuration files if you have any customization in that area:

  • CommerceRuntime.Ext.config – Register all your CRT extensions and dependent assemblies. Also this is where you need to include the Retail Server extension dependent assemblies.

Note

If the extension depends on Newtonsoft.Json.Portable or some other assemblies, then explicitly include it. Don’t assume that these assemblies will be included by default in the packaging or Retail server folder because the out-of-band (OOB) Retail server or CRT is using this. In the future, if the OOB functionalities don’t use these assemblies, it could be removed. As a result, you should always explicitly include all of the extension dependent assemblies in order to package and place them in the correct folder.

Example

   <?xml version="1.0" encoding="utf-8"?>
   <commerceRuntimeExtensions>
       <composition>
           <!-- Register your own assemblies here. -->
           <add source="assembly" value="my custom library" />
       </composition>
   </commerceRuntimeExtensions>
  • CommerceRuntime.MPOSOffline.Ext.config – Register all your CRT extensions and dependent assemblies.

Example

```C#
<?xml version="1.0" encoding="utf-8"?>
<commerceRuntimeExtensions>
    <composition>
        <!-- Register your own assemblies or types here. -->
        <add source="assembly" value=" my custom library" />
    </composition>
</commerceRuntimeExtensions>
```
  • HardwareStation.Extension.config – Register all your Hardware station extensions.

Example

    <?xml version="1.0" encoding="utf-8"?>
    <hardwareStationExtension>
        <composition>
            <! -- Register your own assemblies or types here. -->
            <add source="assembly" value=" my custom library" />
        </composition>
    </hardwareStationExtension>
  • RetailProxy.MPOSOffline.ext.config – Register all your retail proxy extensions.

Example

```C#
<?xml version="1.0" encoding="utf-8"?>
<retailProxyExtensions>
    <composition>
        <!-- Register your own proxy extension assemblies. -->
        <add source="assembly" value=" my custom library" />
    </composition>
</retailProxyExtensions>
```

Retail Server extension assemblies

Before you start the package, you must add an entry for the Retail Server extension assemblies in the <extensionComposition> of the Retail Server web.config file, so that the assemblies are loaded and used. You can find the web.config file in the Retail SDK\Packages\RetailServer\Code folder.

The following illustration shows an example of a Retail Server web.config file.

Retail Server web.config file

Shared Hardware station web.config

If you are not using the legacy payment connector, then comment the legacy payment connector and enable the non-legacy connector in the web.config file. By default, the legacy payment connector is enabled in the shared hardware station web.config.

Example To disable the legacy connector, open the web.config file from \RetailSDK\References\Microsoft.Dynamics.Retail.HardwareStation.WebHost.x.x.x.x\Pkg\bin and comment the legacy connector. Enable the non-legacy connector under the composition section, as shown in the following sample code.

Note

x.x.x.x in the web.config folder path (\RetailSDK\References\Microsoft.Dynamics.Retail.HardwareStation.WebHost.x.x.x.x\Pkg\bin) is the version number. This will vary based on your Retail SDK version number.

    <composition>
      <!-- Defaulting to legacy payment devices.
 <add source="assembly" value="Microsoft.Dynamics.Commerce.HardwareStation.Peripherals.Legacy.PaymentDeviceAdapter"/>
      -->
      <add source="assembly" value="Microsoft.Dynamics.Commerce.HardwareStation.Peripherals.PaymentDeviceAdapter" />
    </composition>

Note

Do not add or change any custom settings in the above mentioned example or in any of the channel config files. The only supported modification is to add custom assemblies details in the composition section.

As part of your extension or package, do not edit any of the following config files. These config files will be updated with the latest file from core Microsoft package during deployment and your changes will be lost.

  • CommerceRuntime.config
  • dllhost.exe.config
  • HardwareStation.Dedicated.config
  • HardwareStation.Shared.config
  • workflowFoundation.config
  • Hardware station - Web.config

Install NuGet.exe

Some of the dependency packages and references have moved to NuGet packages to minimize the file merge and the size of the SDK. These are available for download from the NuGet.org. When you build the Retail SDK these dependencies are automatically pulled from the NuGet.org based on the packages.config file. For this to work, you need to install the NuGet command line interface and add the nuget to the Windows path after downloading nuget.exe from NuGet.org. The following steps show how to add the nuget to the Windows path:

  1. Open the Windows menu and type Path. The Edit the system environment variables will be available.
  2. In that menu, click Environment variables on the lower right.
  3. In the next window, under System variables, select Path and click Edit.
  4. Add an entry for the folder where you would like to store the nuget.exe file or store the nuget.exe file in a folder that is already listed.

Generate a retail deployable package

To generate the retail deployable package, open the MSBuild build Command Prompt window. (On the developer virtual machine, search for msbuild on the Start menu.) Then run the following command.

msbuild /p:Configuration=Release

You can also run the same command in the Microsoft Visual Studio 2015 developer command-line tool.

Packages

After the build is completed, retail deployable packages are generated as a zip file (RetailDeployablePackage.zip) in the Retail SDK\Packages\RetailDeployablePackage folder.

Note

There won't be separate packages the various Retail components. All the packages will be combined into one bundle package that is named RetailDeployablePackage.

Deploy the retail deployable packages

For information about how to deploy the packages either manually or by using the automated flow in LCS, see Apply a deployable package and Install a deployable package.