Download Commerce SDK samples and reference packages from GitHub and NuGet

This article describes to how to download Microsoft Dynamics 365 Commerce software development kit (SDK) samples from GitHub and reference packages.

The Commerce SDK includes the code, code samples, templates, and tools that are required to extend or customize Dynamics 365 Commerce functionality. The SDK is published in different repositories (repos) in GitHub, depending on the extension components.

The Commerce SDK supports rapid development, full MSBuild integration, and package generation. The following image shows the relationship between the development environment and the cloud components.

Extension components in Dynamics 365 Commerce

The following tables provide information about the components in the Commerce SDK that can be customized for different scenarios.

Client (Store Commerce)

Commerce Runtime (CRT)

Headless Commerce APIs

TypeScript proxy

Hardware station

Payment connector

Best practices for naming

The C# source code in the Commerce 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 generate deployment packages to deploy into test, sandbox, and production environments. For more information, see Create deployable packages.

The following sample repositories contain code samples, templates, and tools that are required to extend or customize existing Commerce functionality. Samples are published to repositories in GitHub based on the Commerce extension components. You don't have to close these repositories, instead, you can download and use the samples and template projects.

Dynamics365Commerce.ScaleUnit repository

The Dynamics365Commerce.ScaleUnit repository contains the sample code for customizing the Commerce runtime (CRT), Retail Server, and channel database.

The samples in the repository are organized by Dynamics 365 Commerce application release. Each branch in the repository points to an application release of Dynamics 365 Commerce. Use the release branch that matches your go-live version. You don't have to clone this repository, instead, you can download and use the samples and template projects.

Extension repository (Dynamics365Commerce.ScaleUnit)

You can download and use the samples and templates from microsoft/Dynamics365Commerce.ScaleUnit. The repository contains nuget.config, repo.props, CustomizationPackage.props, and a build pipelines script. Together they provide guidance on how the extension can set up the repository metadata files.

Dynamics365Commerce.ScaleUnit repository folders and projects

Samples for in-store components like the Store Commerce app, Store Commerce for web, Hardware station and Cloud scale unit – Self hosted are published in the Dynamics365Commerce.InStore repository.

The readme.md files in the Commerce Runtime, ChannelDatabase and ScaleUnit folders contain more details on how to run the samples.

Dynamics365Commerce.InStore repository

The Dynamics365Commerce.InStore repository contains the sample code for how to customize POS, Hardware station, Commerce runtime (CRT), headless Commerce APIs, and the channel database.

The samples in the repository are organized by Dynamics 365 Commerce application release, each branch in the repository points to an application release of Dynamics 365 Commerce. Use the release branch that matches your go-live version. You don't have to clone this repository, instead, you can download and use the samples and template projects.

Extension repository (Dynamics365Commerce.InStore)

You can download and use the samples and templates from microsoft/Dynamics365Commerce.InStore. The repository contains nuget.config, repo.props, CustomizationPackage.props, and a build pipelines script. Together they provide guidance on how the extension can set up the repository metadata files.

Dynamics365Commerce.InStore repository folders and projects

More samples for CSU – self hosted, Commerce Runtime, and headless Commerce APIs are published in the Dynamics365Commerce.ScaleUnit repository.

The readme.md files inside the project folder contain more details on how to run these samples.

Dynamics365Commerce.Solutions repository

The Dynamics365Commerce.Solutions repository contains a sample that demonstrates how to perform E2E business scenario customization in Commerce. There might be scenarios where you need to customize POS, e-Commerce, or the headless commerce engine.

Download reference packages for creating APIs, and for consuming messages, request, entities, and contracts

Commerce contracts, messages, entities, and request packages are published in this public feed for Commerce extension code that consumes and customizes existing functionalities, or builds new functionalities for the Dynamics 365 Commerce application.

Use the packages from index.json. You can add the package source location in the nuget.config file of your extension project file, as shown in the following code example:

<packageSources>
    <add key="dynamics365-commerce" value="https://pkgs.dev.azure.com/commerce-partner/Registry/_packaging/dynamics365-commerce/nuget/v3/index.json" />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    </packageSources>

Reference packages that are available in the public feed

Package versioning

An extension project can consume the correct version if you add the package reference to the project and include the full version number. Alternatively, to make the extension project always get the latest version, use a wildcard character. We recommend that you use the full version number, and that you update the version, based on your go-live version. There are two options:

• Without a wildcard character:

  <PackageReference Include="Microsoft.Dynamics.Commerce.Sdk.Runtime" Version="9.28" />;
  

• With a wildcard character:

  <PackageReference Include="Microsoft.Dynamics.Commerce.Sdk.Runtime" Version="9.28.*" />;
  

For every hotfix and new application release, a version of the package will be published in the same public feed, consume the right package version based on the version required for your go-live version. Consuming the higher version of the package than your go-live application version may result in runtime and deployment failures.

Set up an Azure pipeline for build automation and package generation

To set up an Azure pipeline, see Set up a build pipeline for the independent-packaging SDK.

Best practice and branching strategies

For detailed information about the Git branching strategy, see Git branching strategy.

The following branching strategies are based on the way that Microsoft uses Git. For more information, see How we use Git at Microsoft.

Keep your branch strategy simple. Build your strategy from these three concepts:

• Use feature branches for all new features and bug fixes.
• Merge feature branches into the main branch using pull requests.
• Keep a high quality, up-to-date main branch.

Create a new feature branch for development and bug fixes

Create a new feature main branch for your extension, following the naming convention in Git branching doc for sample naming convention.

Create a new development branch

To create a new development branch, follow these steps:

1. Create a private branch for development.

   - git checkout -b private/{username}/{feature/description}
   

2. Add and commit the changes to the development branch. For example:

   git -add . 
   git commit -m "commit message"
   

3. After the development is completed, tested, and validated, push the changes to the main branch. For example:

   git push <remote> <branch>
   

   Or:

   git push origin {private branch name}
   

Create a release branch after development

To create a release branch after development, follow these steps:

1. After the development changes are pushed into the main branch, create a new release branch, and create the deployable packages from the release branch.

   - Git checkout -b release/x.x.x
   

2. Merge the changes from the release branch back to main branch if any changes were made in the release branch. For example:

   - git checkout main git merge release/x.x.x
   

Extension hotfix branch

1. Create a hotfix branch for extension from the main branch. For more information, see Create a release branch after development.
2. Release the fix.
3. Merge the changes back to the main branch.

Merge a new release branch to main and development branch

After a new version of the samples released, if necessary, merge your development branch with the new branch. The repository contains only samples, so it's not required to get the updated changes from the branch. For example:

- git checkout main git merge release/x.x.x