小売チャネル拡張機能を最新の Retail SDK にアップグレード

  • [アーティクル]

重要

Retail SDK のサポートは 2023 年 10 月に終了します。 開発・更新の簡素化、パフォーマンスの向上などの利点がある Commerce SDK をご利用いただくか、移行してください。

この記事では、以前のリリースから Retail SDK の最新の更新プログラムにアップグレードする方法について説明します。 プロセス全体とサポートされるシナリオの情報が含まれていますが、この記事ではプロセスの各ステップに関する詳細な指示は提示しません。 この記事は、Dynamics 365 Commerce と Dynamics 365 Finance に適用されます。

以下のセクションは新しい Retail SDK に拡張機能を手動で移動する方法を説明しますが、Azure DevOps または Git などのソース管理システムを使用してこれを行うことができます。

Retail SDK の更新

新しい環境を配置する場合、新しい Retail SDK は仮想マシン (VM) のサービス ボリュームまたはダウンロード可能な VHD の C ドライブにあります。 Lifecycle Services (LCS) からの新しいバイナリ修正プログラムを適用して Retail SDK を更新すると、既存の RetailSDK フォルダ内に新しい更新プログラム フォルダーが作成され、更新された新しい SDK のコピーが {{Guid.RetailSDKUpdate.Date}} という名前で更新プログラム フォルダー内に作成されます。 このフォルダーをコピーする際、パスまたはファイル名が長すぎるという内容のエラー メッセージが表示されることがあるため、フォルダーの名前を短くすることをお勧めします。

Retail SDK のコンポーネント

Retail SDK の更新は、主に次のコンポーネントで構成されます。

  • 資産: 拡張機能に関連するコンフィギュレーション ファイル変更。
  • ビルド ツール: カスタマイズ パッケージおよびバージョン管理設定。
  • データベース: 拡張 DB スクリプト。
  • ドキュメント: サンプルを実行する方法。
  • パッケージ: 配置パッケージ。
  • 支払の外部参照: 支払パッケージング フォルダー。
  • 支払: 支払のサンプル コード。
  • POS : Store Commerce コードおよびサンプル。
  • 参照: すべてのバイナリ参照およびコマース アナライザー プロキシ ツール。
  • サンプル拡張機能: 拡張機能のサンプル プロジェクト。

アップグレード シナリオ

次のシナリオのいずれかでアップグレードを完了することができます。

  • 特定のバイナリ修正プログラムを更新する。
  • カスタム コードをアップグレードする。
  • 最新のアプリケーション リリースにアップグレードする。

SDK アップグレード プロセスは、バージョンによって異なります。 バージョン 7.3 以降では、すべてのコンポーネントがシールされており、拡張点を使用してのみカスタマイズを完了する必要があります。 これにより、コード アップグレード作業が容易になります。 ただし、7.0、7.1、または 7.2 からアップグレードした場合と、インライン変更を行った場合、インラインを拡張機能に移動する必要があります。 これには追加の作業が必要になります。

メモ

新しいバージョンにアップグレードする場合、既存の Commerce Scale Unit、Commerce Runtime、プロキシ、ハードウェア ステーション、CDX、またはデータベース拡張機能コード/API は一切削除しないでください。 POS クライアントはこのコードに依存しているため、削除するとランタイム例外エラーが発生します。 コード更新中にそれを削除したい場合は、クライアント コードもこの変更をサポートするように更新する必要があり、これをおこなわないとランタイムエラーが発生します。 ベスト プラクティスとして、拡張コードは、常に下位互換性があることを示す方法で記述する必要があります。

次の表では、コードがシールされているバージョンに関する一部の概要情報を提供します。 アンシールド バージョンからシールド バージョンにアップグレードする場合は、すべてのカスタマイズを識別し、拡張機能にインライン カスタマイズを移動する必要があります。 インライン カスタマイズを移動するには、これを行うために必要な拡張ポイントがすべてあることを確認します。 ない場合は、拡張機能の要求を送信します。

メモ

バージョン 7.3 以上にアップグレードする際、7.1 で行った POS インラインの変更の一部を書き換える必要がある場合があります。

アプリケーションのバージョン CRT シールド HWS シールド POS シールド DB シールド プロキシ シールド
アプリケーション リリース 8.1 はい はい はい はい はい
アプリケーション リリース 8.0 有 有 有 有 有
アプリケーション 7.3 有 有 有 有 有
2017 年 7 月のリリース (アプリケーション 7.2) 有 有 有 有 無
リリース 1611 (アプリケーション 7.1) 有 無 無 無 無
2016 年 2 月リリース (アプリケーション 7.0) いいえ いいえ いいえ いいえ いいえ

7.3 からそれ以上のバージョンにチャネル拡張機能をアップグレードする

コード アップグレードを実行している場合、Retail SDK の次のコンポーネントをアップグレードする必要があります。 これらの各コンポーネントは、Retail SDK 内のフォルダーです。

メモ

ソース管理/マージ ツールを使用してコード アップグレードを完了できます。 変更を追跡して必要に応じて戻すことができるように、このプロセスでソース コード管理ツールを使用することをお勧めします。 ソース管理を使用していない場合、コードをアップグレードする前に、古いおよび新しい Retail SDK フォルダーのバックアップを作成することを確認します。

  • 資産: カスタム アセンブリを含めるために次の拡張構成ファイルのいずれかを変更した場合、これらの変更を新しい資産フォルダーにある同じ構成ファイルに移動する必要があります。

    • CommerceRuntime.Ext.config - CRT 拡張。
    • CommerceRuntime.MPOSOffline.Ext.config - CRT オフライン拡張。
    • HardwareStation.Extension.config - ハードウェア ステーションと支払拡張機能。
    • RetailProxy.MPOSOffline.ext.config - プロキシ拡張機能。

  • ビルド ツール:ビルド ツール フォルダーには、パッケージング、ビルド設定と pfx、および snk ファイルに関連するファイルが含まれています。 以前のバージョンで変更を加えた場合は、以下のファイルをマージおよび更新します。

    • Customization.settings
    • Microsoft.Dynamics.RetailSdk.Build.props
    • 作成したカスタム pfx または snk ファイル。

  • データベース: カスタム SQL スクリプトをすべてコピーしてドロップします: ...\RetailSDK\Database\Upgrade\Custom

  • オンライン ストア: オンライン ストア Web プロジェクトまたはオンライン拡張コードがある場合、このフォルダーに含めます。

    メモ

    配置可能パッケージには、パッケージ用のオンライン ストア コードは含まれません。

  • 支払の外部参照: 支払拡張アセンブリすべてをコピーして以下の支払アセンブリ フォルダーに貼り付けます。

    • IPaymentDeviceAssemblies
    • IPaymentProcessorAssemblies
    • PaymentWebFiles

  • 支払: このフォルダーにすべての支払拡張プロジェクトをマージします。

    メモ

    新しい支払拡張機能プロジェクトを作成したが、このフォルダーは何も変更しなかった場合、ビルドとパッケージング プロセスの一部として含めることができます。 RetailSDK フォルダーで dirs.proj を更新し、カスタム プロジェクトをビルドします。 次に、支払拡張機能の格納場所で Customization.settings ファイルを更新し、パッケージの作成時にカスタム プロジェクトがビルドされるようにします。 必ず、パッケージの一部として拡張機能を含めます。

  • POS: 生成されたプロキシを含む任意の POS 拡張機能がある場合、POS 拡張機能を …\RetailSDK\POS\Extensions から新しい Retail SDK POS 拡張子フォルダー RetailSDK\POS\Extensions にコピーします。 拡張機能をコピーしたら、POS\Extensions フォルダー内の extension.json ファイルを更新して、コピーした新しい POS 拡張機能とマージします。

    たとえば、CustomExtension フォルダーをコピーした場合、以下に示すように extension.json を更新します。

    {
"extensionPackages": [
{
   "baseUrl": "SampleExtensions"
},
{
  "baseUrl": "SampleExtensions2"
},
{
  "baseUrl": "CustomExtension"
}
]
}

ビルド中に変更を POS がコンパイルできるように、カスタム拡張機能パッケージで tsconfig.json を更新する必要もあります。

  • 参照:Commerce ランタイム、ハードウェア ステーション、プロキシ などのすべての拡張機能出力アセンブリと、へのすべての外部アセンブリを参照フォルダーにコピーします。 配置およびパッケージの一部として含めようとしているすべてのアセンブリを含めます。

  • Commerce runtime (CRT) と Commerce Scale Unit 拡張機能: CRT および拡張機能プロジェクトすべてを Retail SDK フォルダーの下にコピーします。 msbuild 中にすべての拡張プロジェクトがビルドされ、プロジェクト アセンブリの出力パスが RetailSDK\Reference フォルダーに設定されるように、必ず、CRT および RS 拡張ソリューション ファイルの詳細を RetailSDK フォルダーにある dirs.proj ファイルに含めてください。

  • ハードウェア ステーション (HWS) および支払拡張機能: すべてのハードウェア ステーション (HWS) と支払拡張プロジェクトを Retail SDK フォルダーの下にコピーします。 msbuild 中にすべての拡張プロジェクトがビルドされ、プロジェクト アセンブリの出力パスが RetailSDK\Reference フォルダーに設定されるように、必ず、HWS および支払拡張ソリューション ファイルの詳細を RetailSDK フォルダーにある dirs.proj ファイルに含めてください。

  • Retail プロキシ拡張: すべてのプロキシ拡張プロジェクトを Retail SDK フォルダーにコピーします。 msbuild 中にすべての拡張プロジェクトがビルドされ、プロジェクト アセンブリの出力パスが RetailSDK\Reference フォルダーに設定されるように、必ず、プロキシ ソリューション ファイルの詳細を RetailSDK フォルダーにある dirs.proj ファイルに含めてください。

メモ

Retail SDK フォルダーのルートで msbuild を実行します。 配置可能パッケージを生成するために、Microsoft Visual Studio 開発者コマンド ライン ツールを使用します。

すべてのコンポーネントをアップグレードしたら、コマース配置可能パッケージを配置し、配置を検証して、Retail SDK ファイルをリポジトリに追加します。

7.2 からそれ以上のバージョンにチャネル拡張機能をアップグレードする

前のセクション 7.3 からそれ以上のバージョンにチャネル拡張機能をアップグレードするで説明した手順はコマース プロキシを除くすべてのコンポーネントでも同じです。 RS 拡張機能を持つ CRT があり、customization.settings ファイルに基づいて TypeScript セッションが自動生成された場合、7.2 では、プロキシ プロジェクトでインライン変更を完了している必要があります。

プロキシを 7.3 にアップグレードするには、Typescript および小売販売時点管理 (POS) の C# プロキシ の記事の手順を完了した後、Retail SDK フォルダーにプロキシを移動し、構成ファイル RetailProxy.MPOSOffline.ext.config を更新します。

7.1 からそれ以上のバージョンにチャネル拡張機能をアップグレードする

7.1 では、POS およびプロキシ カスタマイズ インラインのほとんどを完了している必要があります。 それ以上のアプリケーション リリースにアップグレードするは、すべてのインライン変更を拡張機能に移動する必要があります。 バイナリ修正プログラムのアップグレードの場合、新しい Retail SDK とのコード マージを実行し、パッケージを再生成する必要があります。

7.0 からそれ以上のバージョンにチャネル拡張機能をアップグレードする

7.0 では、カスタマイズ インラインのほとんどを完了している必要があります。 それ以上のアプリケーション リリースにアップグレードするは、すべてのインライン変更を拡張機能に移動する必要があります。 バイナリ修正プログラムのアップグレードの場合、新しい Retail SDK とのコード マージを実行し、パッケージを再生成する必要があります。

検証用の配置可能パッケージを生成する

配置可能なパッケージの作成 の記事の手順を完了し、検証用の配置可能パッケージを生成します。