Set up a build pipeline for the independent-packaging SDK

Article
08/12/2022

This article explains how to set up a build pipeline for the Commerce software development kit (SDK) so that you can generate the Cloud Scale Unit and self-service deployable packages for extension code (by using the new independent extension model).

This article applies to version 10.0.19 and later of the Commerce SDK. The steps that are described in this article won't work if you're using the previous version of the Retail SDK from the developer virtual machine (VM) in Microsoft Dynamics Lifecycle Services (LCS). The information in this article is applicable if you're using the new independent extension model (that is, if you're consuming the packages from the public feed), and the independent packaging and extension model.

Set up a build pipeline in Azure DevOps to generate a Cloud Scale Unit extension package

Sign in to your Microsoft Azure DevOps organization.
Select Pipeline, and then select New pipeline.
Select the source repository (repo) for your extension code.
Select Existing Azure Pipelines YAML file.
Select or get the build-pipeline.yml file from the Dynamics365Commerce.ScaleUnit GitHub repo.

Note

The YAML file refers to some scripts in the Pipeline/PowerShellScripts directory in the Dynamics365Commerce.ScaleUnit GitHub repo. Be sure to include all those scripts in your repo. If you clone the samples repo, all the scripts are already included.
Select Continue.

Scripts in the YAML file build the whole solution and upload the output (the CloudScaleUnitExtensionPackage.zip package) to the Published Artifacts drop location for the build.

Note

The YAML file looks for a solution file in the repo, builds the solution, and then looks for the CloudScaleUnitExtensionPackage.zip package. Therefore, make sure that your extension and packaging projects are linked to a solution. For information about how to model your extension projects, see the samples in the Dynamics365Commerce.ScaleUnit GitHub repo.
Save your changes, and add the build to the queue.
When the build is completed, you can download the ScaleUnitPackage_(Build.BuildNumber).zip package from Published Artifacts.

Set up a release pipeline for the Cloud Scale Unit extension package

As a best practice, you should set up separate build and release pipelines. If you create a separate release pipeline, you can use the Upload Asset task in LCS to upload the CloudScaleUnitExtensionPackage.zip package to the Asset library. If you want to upload to LCS instead of to a separate release pipeline, you can add the task as part of your build pipeline.

Follow these steps to set up the release pipeline to upload the CloudScaleUnitExtensionPackage.zip package to the Asset library in LCS.

In Azure DevOps, select Releases, select New pipeline, and then select Empty job in the template.
Enter a name for the new release pipeline. The default name is App Pipelines > New release pipeline.
In the pipeline, select Add an artifact.
In the Add artifact dialog box, select your project, and then select the build pipeline that you created in the previous section.
Optional: In the artifact that you just created, you can select the Trigger button (lightning bolt symbol), enable a continuous deployment trigger, and then select your branch, and so on.

Note

The release pipeline also offers other options that let you specify how and when the release is triggered.
Select Save to save your pipeline. If you're prompted for a folder name, enter any folder name.
Select Stages, rename stage 1 Upload Assets to LCS, and then select 1 Job.
In Tasks, select Agent job.
In Add tasks, search for Dynamics Lifecycle Services (LCS) Asset Upload, and select Add.
Set up the upload task by following the steps in Upload assets by using Azure Pipelines. In the task, set the following values:
- Type of asset: CloudScaleUnitExtensionPackage
- File to Upload: $(System.DefaultWorkingDirectory)/_ScaleUnit-CI/drop/ScaleUnitPackage_$(Release.Artifacts._ScaleUnit-CI.BuildNumber).zip
- LCS Asset Name: ScaleUnitPackage_$(Release.Artifacts._ScaleUnit-CI.BuildNumber)
  
  Note
  
  You can change the asset name according to your naming guidelines.
After you've finished configuring tasks, select Save to save the release pipeline.
On the Pipelines tab, select your pipeline, and then select Create release.
In the Create a new release dialog box, select the Cloud Scale Unit artifact, and then select Create to manually trigger the release.

To automate the release pipeline, configure continuous build. For more information, see the Release pipelines documentation.

Set up a build pipeline in Azure DevOps to generate Commerce self-service packages

Follow these steps to generate the Store POS, Hardware Station, and Cloud Scale Unit (self-hosted) installers.

Sign in to your Azure DevOps organization.
Select Pipeline, and then select New pipeline.
Select your source repo.
Select Existing Azure Pipelines YAML file.
Select the YAML file (build-pipeline.yml) from the Pipeline/YAML_Files directory in the Dynamics365Commerce.InStore GitHub repo.

Note

The YAML file refers to some scripts in the Pipeline/PowerShellScripts directory in the Dynamics365Commerce.InStore GitHub repo. Be sure to include all those scripts in your repo. If you clone the samples repo, all the scripts are already included.
Select Continue.

The YAML file has steps to sign the Store POS and Hardware Station installers by using a certificate. The script will look for a certificate file in Azure Key Vault and use that certificate file for signing. To read the certificate from Azure Key Vault, you must provide the application ID, secret, certificate name, and timestamp server details (for signing the certificate by using a timestamp). For more information, see Set and retrieve a certificate from Azure Key Vault using the Azure portal.

To view the details of the key vault and the timestamp server in the pipeline, create the following variables on the Variables tab in your build pipeline, and provide values for them. To help secure the variables, you can select Secret as the variable type.
- ApplicationId
- AzureKeyVaultURI
- CertificateName
- SecretValue
- Timestamp
  
  You can specify any timestamp provider as the value of this variable, such as http://timestamp.digicert.com.
If you aren't storing your certificate in Azure, you can sign the installers by using the Secure task option or other options that Azure Pipelines supports.

If you don't want to sign the installers, you can remove the signing step from the YAML file. In the YAML file, search for the PowerShell@2 task, and remove it.

Scripts in the YAML file build the whole solution and upload the output (the HardwareStation.Installer.exe and ModernPos.Installer.exe packages) to the Published Artifacts drop location for the build.

Note

The YAML file looks for a solution file in the repo, builds the solution, and then looks for the HardwareStation.Installer.exe and ModernPos.Installer.exe packages. Therefore, make sure that your extension and packaging projects are linked to a solution. For information about how to model your extension projects, see the samples in the Dynamics365Commerce.InStore GitHub repo.
Save your changes, and add the build to the queue.
When the build is completed, you can download the HardwareStation.Installer.exe and ModernPos.Installer.exe packages from Published Artifacts.

Set up a release pipeline for Commerce self-service packages

As a best practice, you should set up separate build and release pipeline. If you create a separate release pipeline, you can use the Upload Asset task in LCS to upload the HardwareStation.Installer.exe and ModernPos.Installer.exe packages to the Asset library. If you want to upload to LCS instead of to a separate release pipeline, you can add the task as part of your build pipeline.

Follow these steps to set up the release pipeline to upload the HardwareStation.Installer.exe and ModernPos.Installer.exe packages to the Asset library in LCS.

In Azure DevOps, select Releases, select New pipeline, and then select Empty job in the template.
Enter a name for the new release pipeline. The default name is App Pipelines > New release pipeline.
In the pipeline, select Add an artifact.
In the Add artifact dialog box, select your repo project, and then select the build pipeline that you created in the previous section.
Optional: In the artifact that you just created, you can select the Trigger button (lightning bolt symbol), enable a continuous deployment trigger, and then select your branch, and so on.

Note

The release pipeline also offers other options that let you specify how and when the release is triggered.
Select Save to save your pipeline. If you're prompted for a folder name, enter any folder name.
Select Stages, rename stage 1 Upload Assets to LCS, and then select 1 Job.
In Tasks, select Agent job.
In Add tasks, search for Dynamics Lifecycle Services (LCS) Asset Upload, and select Add.
Fully set up the upload task by following the steps in Upload assets by using Azure Pipelines. In the task, set the following values:
- Type of asset: Retail Self-Service Package
- File to Upload: $(System.DefaultWorkingDirectory)/_CommerceSDK-Signing-EXE/drop/Installer_$(Release.Artifacts._CommerceSDK-Signing-EXE.BuildNumber).exe
- LCS Asset Name: Installer_$(Release.Artifacts._CommerceSDK-Signing-EXE.BuildNumber)
After you've finished configuring tasks, select Save to save the release pipeline.
On the Pipelines tab, select your pipeline, and then select Create release.
In the Create a new release dialog box, select the artifact, and then select Create to manually trigger the release.