Commerce SDK への移行

  • [アーティクル]

Commerce ソフトウェア開発キット (SDK) とシールド インストーラーにより、Commerce 開発者およびアップグレード作業簡略化されます。 新しい Commerce SDK は、アップグレードに伴う労力を最小限に抑え、アップグレード プロセスに費やす時間と労力を軽減できます。 また、Git、Microsoft Azure DevOps、および Visual Studio Code と統合することで、.NET 環境開発経験を Commerce SDK にもたらします。

Commerce SDK と以前の (レガシ) Retail SDK の主な違いは、拡張機能を個別に開発および配置できる点です。 このプロセスにより、アップグレードと配置の時間が短縮され、新しいシールド インストーラーは基本インストーラーから拡張機能を分割します。 したがって、基本および拡張機能インストーラーは個別にインストールしてサービスを提供できます。 コード マージや結合パッケージは必要はありません。

Retail SDK では、販売時点管理 (POS) 拡張機能の開発のためにコア POS アプリ プロジェクトが必要です。拡張機能はそれらのプロジェクトを使用して拡張機能を開発する必要があります。 複数の独立系ソフトウェア ベンダー (ISV)、パートナー、または顧客の拡張機能が関係している場合、それらすべてがコア POS アプリ拡張機能プロジェクトにマージされる必要があります。 プロジェクトは、コア POS アプリおよび拡張機能を含む結合パッケージまたはインストーラーを生成するために、1 つのビルド パイプラインに統合されます。 新しい POS の Microsoft アップグレードが利用可能な場合、結合されたインストーラーを生成するために、拡張機能をコア POSアプリにマージする必要があります。 このプロセスには開発作業が伴い、アップグレードごとに繰り返す必要があるため、時間がかかります。

Commerce SDK とシールド インストーラーは、基本アプリと拡張機能を分離して上記の問題に対処します。 拡張機能は、パブリック フィードで使用できるパッケージを消費して独自に開発できます。 Commerce Runtime (CRT) または Retail Server からのコア POS アプリやコア クラスは必要ありません。

拡張機能は、アドインとして開発できます。 新しいシールド インストーラー フレームワークにより、独自に開発および配置できます。 拡張機能は、拡張機能コードの独自のヘッドレス インストーラーを作成できます。 Microsoft にホストされる Cloud Scale Unit 拡張パッケージを除き、複数の拡張機能を個別にインストールできます。 自己ホストの Cloud Scale Unit では、複数の拡張機能を個別にインストールして配置できます。

Commerce SDK のサンプルおよびパッケージは、容易な消費のために GitHub およびパブリック フィードで公開されます。 最新の更新プログラムを取得するために Microsoft Dynamics Lifecycle Services (LCS) にアクセスする必要はありません。 LCS を通して SDKの最新の更新プログラムをダウンロードするには数時間かかる場合があります。 一方で、この新しいアプローチでは最新の SDK やパッケージをいくつかの手順だけでダウンロードできます。 GitHub リポジトリはサンプルのリポジトリです。 したがって、拡張機能開発を作成するために複製する必要はありません。 すべての拡張機能は、パブリック フィードからパッケージを消費して開発できます。

Commerce SDK の利点

Commerce SDK は次の利点を提供します:

  • 更新エクスペリエンスがシームレスです。 コア アプリケーションおよび拡張機能は、コード マージなしで個別に更新できます。 コア アプリケーションを更新するために拡張機能を更新する必要はありません。 この新しいプロセスにより、更新に費やしていた時間を短縮できます。
  • パフォーマンスが向上します。 拡張機能を Commerce SDK および .NET Standard 2.0 に移行した場合、Cloud Scale Unit を新しい ASP.NET Core 3.1 にアップグレードしてアプリケーション プログラミング インターフェイス (API) のパフォーマンスを向上させることができます。
  • 拡張機能は GitHub とパブリック フィードに公開されます。 SDK は数時間ではなく数分以内にダウンロードできます。
  • 新しいシールド インストーラーはヘッドレスです (つまり、ユーザー インターフェイスがありません)。 シールド インストーラーは一括配置に最適です。
  • 拡張機能の個別のヘッドレス インストーラーは、新しいインストーラー フレームワークを使用します。
  • Modern POS 用の CRT および ハードウェア ステーション拡張機能のパッケージとコンフィギュレーションは自動化されます。
  • ビルド時間が短縮されます。
  • 開発者エクスペリエンスが向上します。 CSU 拡張機能は、Visual Studio Code、ソース コード管理用 Git およびビルド自動化用 Azure DevOps を使用して開発できます。

Commerce と Retail SDKs の比較

コンポーネント Commerce SDK (新規) Retail SDK (レガシ)
サンプル サンプルは GitHub で公開されます。 サンプルは、Retail SDKの \Sample 拡張機能フォルダーに公開されます。
SDK の取得 SDK は GitHub とパブリック フィードで使用できます。 SDK は LCS 開発仮想マシン (VM) で使用できます。
パッケージまたは参照ライブラリ パッケージはパブリック フィードに公開され、NuGet 経由で消費できます。 Commerce 開発に必要な参照ライブラリとパッケージは、Retail SDK の /Pkgs フォルダで使用できます。
配置可能パッケージ クラウドとオンプレミス コンポーネントには、別個のパッケージとインストーラーがあります。 拡張機能のコンフィギュレーション ファイルを更新する必要はありません。 コンフィギュレーション ファイルは自動的に生成されます。 パッケージはパブリック フィードのパッケージを消費して生成できます。 GitHub のどのサンプルやプロジェクトにも依存しません。 1 つの結合された配置可能パッケージがあります。 そのパッケージを生成するには、複数のコンフィギュレーション ファイルを更新する必要があります。
インストーラー コア アプリケーションおよび拡張機能には別個のインストーラーがあります。 Commerce SDKは、新しいシールド インストーラー フレームワークを使用してインストーラーを生成します。 新しいシールド インストーラーでのみ機能します。 インストーラーはパブリック フィードのパッケージを消費して生成できます。 GitHub のどのサンプルやプロジェクトにも依存しません。 拡張機能およびコア アプリケーションには結合されたインストーラーがあります。 たとえば、Core POS と拡張機能用に 1 つの Modern POS インストーラーがあります。
ビルド パイプライン GitHub で利用可能なサンプルの YAML ファイルは、パイプラインの設定に使用できます。 ただし、Commerce SDK は独自の Azure DevOps パイプライン設定で動作するように設計されています。 ビルド パイプラインは、Retail SDK で利用できる dirs.proj ファイルに基づいています。
更新 拡張機能を更新するには、パブリック フィードで利用できる最新のパッケージを消費します。 更新は LCS から行う必要があります。 LCS 更新プロセスに従う必要があります。

移行手順の概要

  1. ローカル開発環境を設定するか、LCS 開発環境を構成します。

  2. Modern POS、ハードウェア ステーション、および Cloud Scale Unit - レガシ インストーラーを使用してインストールされた自己ホストをアンインストールします。 その後、新しいシールド インストーラーを使用して必要なアプリケーションをインストールします。

  3. Commerce SDK を使用して CRT、API、チャネル データベース、プロキシ、POS、およびハードウェア ステーション拡張機能を移行します。

    Retail SDK を使用して記述されたコードのほとんどは、簡単に移行できます。 再記述する必要はありません。 たとえば、プロジェクトを NET Standard 2.0 に変更し、参照パッケージをパブリック フィードから消費するように更新することで、CRT 拡張機能を更新できます。 API 拡張機能は、新しいインターフェイスを使用し、EDMModel エクステンダー コードを削除することで更新できます。このコードがバック エンドで自動化されているためです。

  4. 新しいインストーラーとパッケージ フレームワークを使用して、クラウドまたはオンプレミスの拡張機能をパッケージします。

  5. 拡張機能を配置します。

移行する方法

開発者環境の変更

LCS 10.0.21 の開発者 VM には Visual Studio 2017 がありません。 したがって、Retail ソフトウェア開発キット (SDK) の "前提条件” セクションで説明されている Visual Studio 2017 と依存関係を手動でインストールするか、ローカル開発環境を設定します。 ローカル開発環境を設定することをお勧めします。 最終的に、Commerce コンポーネントは LCS VM で利用できなくなります。 これらのコンポーネントは、LCS 開発者 VM に手動でインストールするか、独自のローカル開発コンピューターを使用することができます。

CRT 拡張機能

Retail SDK では、CRT 拡張機能は \Pkgs フォルダーのパッケージまたは参照ライブラリを使用します。 ただし、Commerce SDK では、必要なパッケージはすべてパブリック フィードに公開されます。CRT サンプルは GitHub で参照できます。

拡張コードは Retail SDK \Pkgs フォルダーの代わりにパブリック フィードのパッケージを使用する必要があります。また、プロジェクトを .NET Standard 2.0 に更新する必要があります。 ベスト プラクティスに従った場合、コア ビジネス ロジックや契約を変更する必要はありません。 パブリック フィードのパッケージにはサービスやワークフロー クラスはありません。 拡張機能でこれらのクラスを消費しないでください。

プロジェクト ファイルを編集し、次の XML 例に示すように、手動でパッケージ参照を追加するか NuGet マネージャーを使用してパッケージを消費します。

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

パブリック フィードで利用できる拡張機能が消費するパッケージは、GitHub で確認できます。

CRT 拡張機能に変更を加えた理由

この新しい実装により、アップグレードおよび開発プロセスが簡略化されます。 パッケージの最新バージョンをダウンロードするために、LCS を使用して SDK をアップグレードする必要はなくなりました。 そのアップグレード プロセスは数時間かかる場合があります。 代わりに、パッケージ管理ソリューションの最新バージョン (たとえば NuGet) を選択します。

CRT の Commerce 拡張機能の開発はより合理化され、.NET 開発の標準的なベスト プラクティスに準拠しています。

レガシ Retail SDK と Commerce SDK の参照パッケージの違い

レガシ SDK パッケージ Commerce SDK (新規)
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

レガシ SDK で消費されたヘルパー クラスを Commerce SDK に移行するサンプル コード

レガシ SDK ヘルパー メソッドCommerce SDK (要求 / 応答)
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 は内部です。 .NET メモリ キャッシュまたは同様の方法を使用します。
PricingEngine 拡張機能は PricingEngine を直接呼び出すのではなく、代わりに CalculatePricesServiceRequest と CalculateDiscountsServiceRequest を使用する必要があります。
PricingDatabaseAccessor バージョン 10.0.1 以降廃止されました。関連する CRT データ要求を使用します。

Retail Server または ヘッドレス コマース API の拡張機能

Retail SDK 拡張機能の以前のバージョンでは、Retail SDK \Pkgs フォルダーのパッケージを使用し、CommerceController クラスから拡張して新しい API 拡張機能を作成する必要があります。 Commerce SDK では、拡張機能はパブリック フィードのパッケージを使用し、IController インターフェイスから API コントローラー クラスを拡張します。 詳細については、Retail Server 拡張 API の作成 (Retail SDK バージョン 10.0.11 以降) を参照してください。

API 拡張機能に変更を加えた理由

この変更により、EdmModel ファクトリやエクステンダーを作成する必要がなくなります。 拡張機能でこのファクトリとエクステンダーを追加し、適切な属性を設定する作業は複雑でした。 エンティティ データ モデル (EDM) プロセス全体が自動化されるようになり、Modern POS 用の別のオフライン プロキシ ライブラリを生成する必要がなくなります。 API 拡張ライブラリをオフラインで直接使用でき、プロキシ生成プロセスが簡略化されます。

チャネル データベース

拡張機能に対して作成されるオフライン データベース スクリプトの変更は必要ありません。 ただし、チャンネル データベース プロジェクトを作成し、パッケージのスクリプトを含める必要があります。 サンプル プロジェクトは GitHub で確認できます。

オフライン

以前は、API と CRT 拡張機能を消費するために、別の Modern POS C# プロキシ ライブラリを作成する必要がありました。 しかし、新しい API 拡張機能モデルでは、ヘッドレス コマース API を直接使用できます。

Hardware Station

Retail SDK 拡張機能の以前のバージョンでは、Retail SDK \Pkgs フォルダーのパッケージを使用し、HardwareStationController クラスから拡張して新しいハードウェア ステーションの拡張機能を作成する必要があります。 Commerce SDK を使用する場合、拡張機能はパブリック フィードのパッケージを使用し、IController インターフェイスを使用してハードウェア ステーション コントローラー クラスを拡張する必要があります。 詳細については、POS を新しいハードウェア デバイスと統合し、拡張機能インストーラーを生成するを参照してください。

新しいシールド インストーラー

共有アセット ライブラリに移動して Retail セルフ サービス パッケージを資産タイプとして選択すると、新しいシールド インストーラーを LCS からダウンロードできます。 新しいシールド インストーラーをインストールする前に、レガシ インストーラーまたはアプリ (Modern POS、ハードウェア ステーション、Cloud Scale Unit - 自己ホスト) をアンインストールする必要があります。 POS 用 Commerce SDK は、シールド インストーラーでのみ動作します。

POS

Commerce SDK では、POS 拡張機能の開発プロセスに対して行われたいくつかの改良により、既存の拡張機能を移行する際に変更が必要になります。 次の表に、最も重要な変更をまとめています。 拡張機能を移行するための変更と手順の完全な一覧は、POS 拡張機能を独立したパッケージ モデルに移行するを参照してください。

変更 Description 使用方法
SDK からの POS アプリ コードの削除 Retail SDK の以前のバージョンでは、POS 拡張機能ソリューションには、Microsoft が開発したコードと拡張機能の両方が含まれています。 Commerce SDK ではこのモデルを変更しました。 拡張機能ソリューションには POS 拡張機能コードだけが含まれることになります。 この変更により、コード マージの必要性がなくなり、更新プロセスが簡略化されます。 また、POS の主要パッケージを拡張機能パッケージとは別に更新することができます。 最後に、POS はコード マージを必要とせずに複数の拡張機能パッケージをサポートすることができます。
POS API の更新

パッケージの変更に加えて、POS API に次の主な 2 つの変更を行いました:

  • POS の公開契約から knockout.js の参照をすべて削除しました。 この変更の一環として、PosApi/Consume/Controls 下の新しい API セットを通じて一般的な POS コントロールを使用するように、拡張機能のユーザー インターフェイスを有効にしました。 これらの新しい API の可用性により、Pos.UI.Sdk ライブラリは廃止されました。 そのため、そのライブラリは Commerce SDK では見つかりません。
  • カスタム ビューを作成するために、簡略化した API を導入しました。
 POS 公開契約から knockout.js ライブラリの参照を削除したことにより、拡張機能を中断するリスクを伴わずに POS コントロールの実装を反復処理および改良できます。 更新プロセスで POS の主要パッケージと拡張機能を併せて再コンパイルする必要がなくなったため、この機能は特に重要です。 それでも、拡張機能は引き続き knockout.js を使用できます。 Commerce SDKで knockout.js を使用する方法の詳細については、POS 拡張機能で Knockout.js のような外部またはサード パーティー ライブラリを使用するを参照してください。

ビルド パイプライン

Commerce SDK でビルド パイプラインを設定する方法の詳細については、独立したパッケージ SDK のビルド パイプラインを設定するを参照してください。 設定を簡略化するために、YAML およびスクリプト ファイルがサンプルとして追加されました。 また、Azure Key Vault の証明書を使用してビルド アーティファクトに署名するための手順も追加されています。

パッケージ配置

セルフサービス コンポーネントと Cloud Scale Unit 拡張機能を分離するために、新しいパッケージ タイプが追加されました。 新しい ScaleUnit パッケージには、Cloud Scale Unit コンポーネントだけが含まれます。 ビルド パイプラインを使用すると、セルフサービス コンポーネントを LCS にアップロードできます。 または、手動でアップロードしてバック オフィスに同期することもできます。

Retail SDK を使用してパッケージを生成する場合、Customization.Settings ファイルおよび拡張コンフィギュレーション ファイルを更新する必要があります。 Commerce SDK パッケージでは、これらすべての手順は自動化されています。 したがって、コンフィギュレーション ファイルを含めたり更新したりする必要はありません。

詳細については、Commerce Cloud Scale Unit (CSU) の個別パッケージの生成を参照してください。

よく寄せられる質問

移行する必要がありますか?

Commerce SDK には、簡略化された開発と更新エクスペリエンスや向上されたパフォーマンスなど、Retail SDK では提供されていないいくつかの利点があります。 Retail SDK とインストーラーは 2023 年 10 月に非推奨となり、それより前にすべての拡張機能を移行する必要があります。 2023 年 10 月以降、Retail SDK はリリースもサポートもされなくなります。

いつ移行する必要がありますか?

拡張機能は、新しい Commerce SDK および新しいインストーラーに 2023 年 10 月までに移行する必要があります。