Επεξεργασία

Κοινοποίηση μέσω

Migrate to the Commerce SDK

Note

The Retail Interest Group by Dynamics 365 Commerce has moved from Yammer to Viva Engage. If you don't have access to the new Viva Engage community, fill out this form (https://aka.ms/JoinD365commerceVivaEngageCommunity) to be added and stay engaged in the latest discussions.

Important

Support for the Retail SDK ended in October 2023. Please use or migrate to the Commerce SDK, which provides several benefits including a simplified development and update experience, and improved performance.

This article explains how to migrate to the Microsoft Dynamics 365 Commerce software development kit (SDK).

The Microsoft Dynamics 365 Commerce software development kit (SDK) and sealed installers simplify the Commerce developer and upgrade experience. The new Commerce SDK minimizes the effort that is involved in upgrades, and helps reduce the time and effort that must be spent on the upgrade process. Additionally, integration with Git, Microsoft Azure DevOps, and Visual Studio Code brings the .NET development experience to the Commerce SDK.

The main difference between the Commerce SDK and the older (legacy) Retail SDK is that you can independently develop and deploy extensions. This process reduces the upgrade and deployment time. The new sealed installers separate the extension from the base installers. Therefore, you can independently install and service the base and extension installers. You don't need a code merge or combined packaging.

In the Retail SDK, you need the Core POS app projects to develop a Point of Sale (POS) extension. Extensions must use those projects to develop extensions. If multiple independent software vendor (ISV), partner, or customer extensions are involved, you must merge them all to the Core POS app extension project. That project integrates into one build pipeline to generate the combined package or installers that include the Core POS app and the extension. If the new Microsoft upgrade for POS is available, you must merge the extensions with the Core POS app to generate the combined installers. This process is time consuming, involves development effort, and must be repeated for every upgrade.

The Commerce SDK and sealed installers address the preceding issue by isolating the base app and extensions. You can independently develop extensions by consuming the packages that are available in a public feed. They don't require any of the Core POS app or core classes from the Commerce runtime (CRT) or Retail Server.

You can develop an extension as an add-in. The new sealed installer framework enables it to be independently developed and deployed. Extensions can create their own headless installers for extension code. You can install multiple extensions separately, except Microsoft–hosted Cloud Scale Unit extension packages. In a self-hosted Cloud Scale Unit, you can independently install and deploy multiple extensions.

The Commerce SDK samples and packages are published on GitHub and in a public feed, for easier consumption. You don't have to access Microsoft Dynamics Lifecycle Services (LCS) to get the latest update. It can take several hours to download the latest update of the SDK through LCS. However, the new approach lets you download the latest SDK or packages in just a few steps. The GitHub repository (repo) is a sample repo. Therefore, you don't have to clone it to create your extension development. All extensions can be developed by consuming the packages from the public feed.

Benefits of the Commerce SDK

The Commerce SDK provides these benefits:

  • The update experience is seamless. You can independently update the core application and extensions without a code merge. You don't have to update extensions to update the core applications. This new process reduces the time spent on updates.
  • Performance is improved. If you migrate extensions to the Commerce SDK and .NET Standard 2.0, you can upgrade the Cloud Scale Unit to the new ASP.NET Core 3.1, which provides better application programming interface (API) performance.
  • Extensions are published to GitHub and a public feed. You can download the SDK within minutes instead of hours.
  • The new sealed installers are headless (that is, there's no user interface). Sealed installers work great for mass deployment.
  • Separate headless installers for extensions use the new installer framework.
  • Packaging and configuration of CRT and Hardware station extensions for Store Commerce Modern POS are automated.
  • Build times are improved.
  • The developer experience is improved. You can develop CSU extensions by using Visual Studio Code, Git for source code management, and Azure DevOps for build automation.

Comparison of the Commerce and Retail SDKs

Component Commerce SDK (new) Retail SDK (legacy)
Samples Samples are published on GitHub. Samples are published in the \Sample extension folder in the Retail SDK.
Getting the SDK The SDK is available on GitHub and in a public feed. The SDK is available on the LCS development virtual machine (VM).
Packages or reference libraries Packages are published to the public feed and can be consumed via NuGet. Reference libraries and packages that are required for Commerce development are available in the /Pkgs folder in the Retail SDK.
Deployable packages There are separate packages and installers for Cloud and on-premises components. You don't have to update any configuration files for extensions. Configuration files are automatically generated. You can generate packages by consuming the packages in the public feed. There's no dependency with any samples or projects on GitHub. There's one combined deployable package. You must update several configuration files to generate that package.
Installers There are separate installers for core applications and extensions. The Commerce SDK uses the new sealed installer framework to generate the installers. It works only with the new sealed installer. You can generate installers by consuming the packages in the public feed. There's no dependency with any samples or projects on GitHub. There are combined installers for extensions and core applications. For example, there's one combined Modern POS installer for Core POS and extensions.
Build pipeline You can use sample YAML files that are available on GitHub to set up the pipeline. However, the Commerce SDK is designed to work with your own Azure DevOps pipeline setup. The build pipeline is based on the dirs.proj file that's available in the Retail SDK.
Updates To update the extensions, consume the latest package that's available in the public feed. You must do updates from LCS. You must follow the LCS update process.

Migration steps

  1. Set up your local development environment, or configure the LCS development environment.

  2. Uninstall the Store Commerce app, Hardware Station, and Cloud Scale Unit - Self-hosted that you installed by using the legacy installers. Then install the required application by using the new sealed installers.

  3. Migrate the CRT, API, channel database, proxy, POS, and Hardware Station extensions by using the Commerce SDK.

    Most of the code that you wrote by using the Retail SDK can be easily migrated. You don't have to rewrite it. For example, you can update the CRT extension by changing the project to NET standard 2.0 and updating the reference package so that it's consumed from the public feed. You can update the API extension by using new interface and removing the EDMModel extender code, because it's automated in the back end.

  4. Package the extensions for Cloud or on-premises by using the new installer and packaging framework.

  5. Deploy the extensions.

How to migrate

Developer environment changes

The LCS 10.0.21 developer VM doesn't have Visual Studio 2017. Therefore, manually install Visual Studio 2017 and the dependencies as described in the "Prerequisites" section of Retail software development kit (SDK), or set up a local development environment. Microsoft recommends that you set up a local development environment. Eventually, Commerce components won't be available on the LCS VM. You can either manually install those components on the LCS developer VM or use your own local development machine.

CRT extensions

In the Retail SDK, CRT extensions use the packages or reference libraries from the \Pkgs folder. However, in the Commerce SDK, all the required packages are published to the public feed, and CRT samples are available for reference on GitHub.

Your extension code must use the packages from the public feed instead of the Retail SDK \Pkgs folder, and you must update the project to .NET Standard 2.0. If you followed the best practices, you don't need to make any changes to the core business logic or contracts. The packages in the public feed don't include any services or workflow classes. Your extension must not consume those classes.

Edit your project file, and manually add the package reference or use the NuGet manager to consume the packages, as shown in the following XML example.

<PackageReference Include="Microsoft.Dynamics.Commerce.Sdk.Runtime" Version="$(CommerceSdkPackagesVersion)" />

You can find packages that are available in the public feed for extensions to consume on GitHub.

Why we made this change to CRT extensions

This new implementation simplifies the upgrade and development process. To download the latest version of the packages, you no longer have to use LCS to upgrade the SDK. That upgrade process can take several hours. Instead, select the latest version in your package management solution (for example, NuGet).

Development of Commerce extensions for CRT is more streamlined and follows the standard best practices for .NET development.

Reference package difference between legacy Retail SDK and Commerce SDK

Legacy SDK package Commerce SDK (new)
Microsoft.Dynamics.Commerce.Runtime.Services, Microsoft.Dynamics.Commerce.Runtime.TransactionService, Microsoft.Dynamics.Commerce.Runtime.Workflow, Microsoft.Dynamics.Commerce.Runtime.Services.Messages, Microsoft.Dynamics.Commerce.Runtime.Data Microsoft.Dynamics.Commerce.Sdk.Runtime
Microsoft.Dynamics.Commerce.Runtime.Services.PricingEngine Microsoft.Dynamics.Commerce.Runtime.Services.PricingEngine.Contracts

Sample code to migrate the helper classes consumed in legacy SDK to Commerce SDK

Legacy SDK helper methods Commerce SDK (Request/Response)
TransactionServiceClient

TransactionServiceClient transactionService = new TransactionServiceClient(request.RequestContext); transactionService.InvokeExtensionMethod("getSalesOrderDetails")		 InvokeExtensionMethodRealtimeRequest extensionRequest = new InvokeExtensionMethodRealtimeRequest("getSalesOrderDetails ") InvokeExtensionMethodRealtimeResponse response = await request.RequestContext.ExecuteAsync<InvokeExtensionMethodRealtimeResponse>(extensionRequest).ConfigureAwait(false);
LoadSalesTransactionForReturn var request = new GetSalesOrderDetailsByTransactionIdServiceRequest(transactionIdToLoad, SearchLocation.Local); response = await context.ExecuteAsync<GetSalesOrderDetailsServiceResponse>(request).ConfigureAwait(false);
GetProductsInCartLines var serviceRequest = new GetProductsInCartLinesServiceRequest(request.CartLines); var serviceResponce = await request.RequestContext.ExecuteAsync<GetProductsInCartLinesServiceResponse>(serviceRequest).ConfigureAwait(false); return new GetProductsInCartLinesResponse(serviceResponce.ProductsByRecordId);
LoadSalesTransaction var getCartRequest = new GetCartRequest(new CartSearchCriteria(cartId, cartVersion), QueryResultSettings.SingleRecord, includeHistoricalTenderLines: false, ignoreProductDiscontinuedNotification: ignoreProductDiscontinuedNotification); var getCartResponse = await context.ExecuteAsync<GetCartResponse>(getCartRequest).ConfigureAwait(false);
SaveSalesTransaction var saveTransactionRequest = new SaveSalesTransactionDataRequest(transaction); await request.RequestContext.Runtime.ExecuteAsync<NullResponse>(saveTransactionRequest, request.RequestContext).ConfigureAwait(false);
CartWorkflowHelper.PerformSaveCartOperations var saveCartRequest = new SaveCartRequest(cart, calculationModes: null, isGiftCardOperation: isGiftCardOperation, isTransactionResume: true); saveCartRequest.SalesTransaction = transaction; cart = (await request.RequestContext.ExecuteAsync<SaveCartResponse>(saveCartRequest).ConfigureAwait(false)).Cart;
CartWorkflowHelper.ConvertToCart ConvertSalesTransactionToCartServiceRequest serviceRequest = new ConvertSalesTransactionToCartServiceRequest(salesTransaction); return (await context.ExecuteAsync<UpdateCartServiceResponse>(serviceRequest).ConfigureAwait(false)).Cart;
RuntimeReceiptLocalizer.GetLocalizedString var request = new GetLocalizedTextsDataRequest(cultureName, textId, QueryResultSettings.SingleRecord); var response = isAsync ? await requestContext.ExecuteAsync<EntityDataServiceResponse<LocalizedText>>(request).ConfigureAwait(false) : var result = response.PagedEntityCollection; if (!result.IsNullOrEmpty()) { LocalizedText text = result.FirstOrDefault(); return text.Text; }
DataCacheAccessor DataCacheAccessor is internal. Use .NET memory cache or a similar approach.
PricingEngine Extensions shouldn't call PricingEngine directly and instead should use CalculatePricesServiceRequest, CalculateDiscountsServiceRequest.
PricingDatabaseAccessor Obsolete since version 10.0.1, use the relevant CRT data requests.
InventoryAvailabilityServiceDataRetriever.GetUnpostedQuantities GetProductWarehouseInventoryUnpostedQuantityServiceRequest request = new(productWarehouses); ICollection<ProductWarehouseInventoryUnpostedQuantity> unpostedQuantities = (await context.ExecuteAsync<GetProductWarehouseInventoryUnpostedQuantityServiceResponse>(request).ConfigureAwait(false)).UnpostedQuantities;

Retail Server or Headless Commerce API extensions

In older versions of Retail SDK extensions, you must use the packages from the Retail SDK \Pkgs folder and extend from the CommerceController class to create new API extensions. In the Commerce SDK, an extension uses the packages from the public feed and extends the API controller class from the IController interface. For more information, see Create a Retail Server extension API (Retail SDK version 10.0.11 and later).

Why we made this change to the API extensions

This change removes the need to create the EdmModel factory and extender. It was complex for the extensions to add this factory and extender, and to set appropriate attributes. The whole Entity Data Model (EDM) process is now automated, and you don't have to generate a separate offline proxy library. The API extension library can be used directly offline, and the proxy generation process is simplified.

Channel database

No changes are required in the offline database scripts that are created for extensions. However, you must create a channel database project and include the script in it for packaging. The sample project can be found on GitHub.

Offline

Previously, you had to create a separate Modern POS C# proxy library to consume the API and CRT extensions. However, in the new API extension model, you can directly use the Headless Commerce API.

Hardware Station

In older versions of Retail SDK extension, you must use the packages from the Retail SDK \Pkgs folder and extend from the HardwareStationController class to create new Hardware Station extensions. When you use the Commerce SDK, an extension must use the packages from the public feed and extend the Hardware Station controller class by using the IController interface. For more information, see Integrate the POS with a new hardware device and generate the extension installer.

New sealed installers

You can download the new sealed installers from LCS by going to the Shared Asset Library and selecting Retail Self-service package as the asset type. Uninstall the legacy installers or the apps (Hardware Station, Cloud Scale Unit - Self-hosted) before you install the new sealed installers. The Commerce SDK for POS works only with the sealed installers.

POS

In the Commerce SDK, a few improvements that are made to the development process for POS extensions require changes when you migrate existing extensions. The following table summarizes the most important changes. For a complete list of changes and steps to migrate an extension, see Migrate a POS extension to the independent packaging model.

Change Description Purpose
Removal of POS app code from the SDK In older versions of the Retail SDK, the POS extension solution contains both Microsoft-developed code and the extensions. In the Commerce SDK, we changed this model. The extension solutions now include only the POS extensions code. This change simplifies the update process by removing the need for a code merge. It also enables the POS main package to be updated independently from the extension packages. Finally, it enables POS to support multiple extension packages without requiring a code merge.
POS API updates

In addition to the packaging changes, we made two main changes to the POS API:

  • We removed all references to knockout.js from the POS public contracts. As part of this change, we enabled an extension's user interface to use common POS controls through a new set of APIs under PosApi/Consume/Controls. The availability of these new APIs made the Pos.UI.Sdk library obsolete. Therefore, that library isn't found in the Commerce SDK.
  • We introduced a simplified API to create custom views.
 The removal of references to the knockout.js library from the POS public contracts enables us to iterate and improve the POS control implementations without the risk of breaking any extensions. This capability is especially important because the upgrade process no longer requires that the POS main package and extensions be recompiled together. Nevertheless, extensions can still use knockout.js. For more information about how to use knockout.js with the Commerce SDK, see Consume external or partner libraries like Knockout.js in POS extensions.

Build pipeline

For information about how to set up the build pipeline for the Commerce SDK, see Set up a build pipeline for the independent-packaging SDK. To simplify the setup, YAML and script files are added as a sample. Additionally, steps for using the certificate from Azure Key Vault and signing the build artifacts are added.

Package deployment

A new packaging type separates the self-service components from the Cloud Scale Unit extensions. The new ScaleUnit package contains only the Cloud Scale Unit components. You can upload the self-service components to LCS by using the build pipeline. Alternatively, you can manually upload and sync them to the back office.

If you use the Retail SDK to generate the package, you must update the Customization.Settings file and the extension configuration files. In the Commerce SDK packaging, all these steps are automated. Therefore, you don't have to include or update the configuration files.

For more information, see Generate a separate package for Commerce Cloud Scale Unit (CSU).

FAQ

Do I have to migrate?

The Commerce SDK provides several benefits that the Retail SDK doesn't provide, such as a simplified development and update experience, and improved performance. The Retail SDK and installers are deprecated in October 2023, and all extensions must be migrated before then. After October 2023, the Retail SDK isn't released or supported.

When do I have to migrate?

Migrate extensions to the new Commerce SDK and new installers by October 2023.

  • Last updated on