Retail ソフトウェア開発キット (SDK)
この記事では、Retail ソフトウェア開発キット (SDK) の概要を説明します。 Microsoft Dynamics 365 Commerce には、開発者が製品の新機能をカスタマイズして追加するために使用できる豊富な SDK が提供されています。 Dynamics 365 Commerce の複数階層アーキテクチャにより、クライアント、ビジネス ロジック、およびデータ レイヤーを互いに独立してカスタマイズおよび拡張するための簡単なオプションが提供されます。 Retail SDK には、ライブラリ、NuGet パッケージ、販売時点管理 (POS) アプリケーション、コード サンプル、テンプレート、およびツールが含まれています。 拡張機能アプリの作成、機能の追加、およびコマースの既存の機能の変更に使用できます。
Retail SDK の概要
Retail SDK には、既存のコマース機能を拡張やカスタマイズするために必要な、コード、コード サンプル、テンプレート、およびツールが含まれています。 SDK は、迅速な開発、完全な MSBuild 統合、およびパッケージの生成をサポートします。 次の図に、開発環境とクラウド コンポーネントの関係を示します。
メモ
Retail SDKは、トランスポート層セキュリティ (TLS) 1.2標準をサポートしています。 Retail SDK を使用してカスタマイズを行う場合は、すべてのカスタマイズは、TLS 1.2 標準に従う必要があります。
Retail SDK をダウンロード
メモ
Dynamics 365 Commerce アプリケーション バージョン 10.0.18 以降を使用している場合は、パブリック フィードから SDK 参照パッケージを使用します。 また、次の GitHub リポジトリのサンプル テンプレートも使用します (LCS 開発マシンから SDK を使用する必要はありません)。
Commerce Scale unit サンプル レポジトリ
Retail SDK は Microsoft Dynamics Lifecycle Services (LCS) 経由で提供される開発環境、LCSからダウンロードする仮想ハード ディスク (VHD)、および LCS 環境に配置される修正プログラム パッケージで提供されます。 詳細については、開発環境の配置とアクセスおよびクラウド環境への更新プログラムの適用を参照してください。
メモ
リリース 10.0.21 では、LCS の開発 VM には Visual Studio 2017 とコマース開発で必要なその他の依存関係はありません。 前提条件を手動でインストールするか、Retail SDK から MSBuild を実行してインストールします。 VMに Visual Studio 2017 ツールがインストールされていない場合は、Visual Studio 2019 の開発者コマンド プロンプトを使用し、MSBuild コマンドを実行します。 これにより、すべての前提条件がインストールされますが、POS ビルドでは Visual Studio 2019 の開発者コマンド プロンプトが機能せず、POS は Visual Studio 2019がサポートしていない、というエラー表示が出ます。この問題を修正するには、前提条件のインストール完了後、 Visual Studio 2017 の開発者コマンド プロンプトを開いて MSBuild を実行します。 PowerShell を使用して SDK\BuildTools で checkVS2017Installed.ps1 スクリプトを実行し、2017 年版 Visual studio ツールをインストールして、次に Visual Studio 2017 の開発者コマンド プロンプトを使用して前提条件をインストールし、SDK を構築することができます。
Retail SDK にアクセスするには、開発仮想マシン (VM) にログインし、K:\RetailSDK フォルダーに移動します。 LCS から LCS に任意の Commerce バイナリ修正プログラムを適用すると、Retail SDK の新しいバージョンを入手できます。 修正プログラムの配置が完了すると、新しいバージョンの SDK が K:\RetailSDK\Update フォルダーに格納されます。
Retail SDK の現在のバージョンに拡張機能が含まれている場合、構成ファイルおよび拡張プロジェクトは、アップグレード後に SDK の以前のバージョンから新しいバージョンにマージする必要があります。 このマージは、SDK の以前のバージョンに拡張機能が含まれる場合にのみ必要であり、それらの拡張機能を新しいバージョンに移行する必要があります。 詳細および詳細な手順については、Retail チャネル拡張機能を最新のRetail SDKにアップグレードするを参照してください。 Git または Azure などのソース管理システムに SDK を統合することをお勧めします。
完全な MSBuild 統合
Retail SDK は、ビルド システムです。 SDK フォルダーのルートから MSBuild コマンドを実行するだけで、すべてのビルドが完了します。 この機能により、作成方法や作成場所に関する質問が削除されます。 また、整合性と再現度も保証されます。 したがって、Retail SDKは、Azure Pipelines などのビルド パイプラインと簡単に統合できます。 詳細については、Commerce SDK ビルド パイプラインを設定を参照してください。
前提条件
Retail SDK を使用して拡張機能を開発または構築するには、次のコンポーネントが必要です。
以下のワークロードとコンポーネントがある Visual Studio 2017 Community、Professional、または Enterprise edition。
- .NET デスクトップ開発
- ユニバーサル Windows プラットフォーム開発
- ASP.NET および Web 開発
- Azure 開発
- Node.js 開発
- .NET Core クロスプラットフォーム開発
- .NET を使用したモバイル開発 (ハイブリッド アプリの開発に必要)
以下のSDKおよびランタイム。
Visual Studio 2017 には、既定のバージョンとして Typescript 3.1 があります。 POS アプリはバージョンに基づくため、バージョン 2.2.2 をインストールする必要があります。 Visual Studio で、ツール>ツールと機能を取得を選択します。 個々のコンポーネント タブを選択し、SDK、ライブラリ、およびフレームワークからの TypeScript 2.2 SDK セクションを選択してインストールします。
SDK のコンパイルが失敗し、「現在の .NET SDK は .NET Standard 2.0 のターゲット設定をサポートしていません」というエラー メッセージが表示された場合は、x86 バージョンの .NET 2.1 SDK とランタイムをインストールしてみてください。
Retail SDK をビルドする
Retail SDK を使用して開発を開始する前に、MSBuild を使用してすべてのパッケージを復元し、SDK フォルダーのルートから完全ビルドを作成する必要があります。
- Visual Studio 2017 の開発者コマンド プロンプト ウィンドウまたは MSBuild 15.0 コマンド プロンプト ウィンドウを開きます。
- コマンド プロンプト ウィンドウで、Retail SDK フォルダーに移動します。
- SDK フォルダーのルートから msbuild /t:rebuild コマンドを実行します。 SDK フォルダーのルートにある dirs.proj ファイル (RetailSDK\dirs.proj または RetailSDK\Code\dirs.proj) には、完全な SDK を構築するために必要なすべての詳細が含まれています。
前提条件の確認をスキップするための MSBuild 引数
MSBuild では、コマース開発に必要な依存関係がインストールされているかどうかを確認します。 依存関係が見つからない場合は、MSBuild スクリプトによって、欠落している依存関係がインストールされます。 このチェックは、MSBuild の実行時に毎回行われます。 このチェックをスキップするには、次の引数を false として渡します。
MSBuild/p:CheckVS2017Installed=false/p:CheckVSDependencies=false – リリース 10.0.18 で引数を追加
MSBuild/p:InstallRuntimeSdkdependencies=false – リリース 10.0.22 で引数を追加
Retail SDK のコンポーネント
次の表に、拡張機能の開発に役立つ Retail SDK に含まれているフォルダーを示します。 次の表のフォルダ構造と説明は、Retail SDK のバージョン 10.0.13 に基づいています。
| フォルダーまたはファイル | Description |
|---|---|
| 資産 | このフォルダーには、パッキングに必要なスクリプトおよび構成ファイルが含まれています。 これらの構成ファイル (HardwareStation.Extension.config、 RetailProxy.MPOSOffline.ext.config、 CommerceRuntime.Ext.config、and CommerceRuntime.MPOSOffline.Ext.config) のみが、パッケージの拡張機能バイナリの詳細を含むように編集されます。
|
| BuildTools | このフォルダーには、スクリプト、サンプルの証明書、およびカスタマイズ設定 (パッケージ メタデータ) ファイルが含まれています。 カスタマイズ設定以外は、このフォルダー内のファイルを変更することはできません。 |
| データベース | このフォルダーには、共有データベース スクリプトが含まれています。 拡張機能は、Database\Upgrade\Custom フォルダーに拡張スクリプトをコピーする必要があります。 |
| ドキュメント | このフォルダーには、サンプルの一部を実行する手順が含まれています。 |
| OnlineStore | このフォルダーには、Retail プロキシを使用して作成されたエンドツーエンドの eコマース店舗ソリューションのサンプルが含まれています。 |
| 梱包 | パッケージ用に SDK ビルドした後に生成された Retail の配置可能パッケージは、このフォルダー (Package\RetailDeployablePackage) にコピーされます。 Retail の配置可能パッケージは、LCS を使用してさまざまな環境 (テスト、サンドボックス、移動、および運用) に配置されます。 | PaymentExternals | 拡張機能の支払アセンブリはコピーする必要があります。 次の 3 つのサブフォルダーでは、さまざまな支払ファイルを保持します。
|
| 支払 | このフォルダーには、Dynamics 365 Commerce の eコマース アドイン用のサンプルの支払コネクタ プロジェクトが含まれています。 |
| pkgs | このフォルダーには、Retail プロキシ生成用の拡張プロジェクトおよびツールを構築するために必要なすべての NuGet パッケージ (参照ライブラリ) が含まれています。 |
| POS | このフォルダーには、POS アプリおよび拡張プロジェクトが含まれます。
|
| 参照 | このフォルダーは、すべての画像が格納されている単一の場所として機能します。 これは、プロジェクトのバイナリ参照を解決するために使用されます。 ファイルのリストには、外部の非コマース バイナリと Microsoft Commerce バイナリが含まれています。 また、このフォルダーは、Retail SDK からビルドされているバイナリのグローバルな格納場所として使用されます。 |
| SampleExtensions | このフォルダーには、サンプルのプロジェクトと拡張機能のテンプレートが含まれています。
|
| dirs.proj | このプロジェクト ファイルによってビルド順序が設定されます。 |
| Microsoft-version.txt | これには、Retail SDK の Microsoft アプリケーションのバージョンが含まれています。 |
Retail SDK の拡張コンポーネント
次の表は、さまざまなシナリオにカスタマイズできる Retail SDK の各コンポーネントについての情報です。 RetailSDK\SampleExtensions フォルダー内のサンプル プロジェクトのみ、拡張機能のために変更できます。 Retail SDK の他のファイルまたはプロジェクト / スクリプトは変更されません。
クライアント (POS)
| シナリオ | ユーザー エクスペリエンス (UX) の変更、クライアント ロジック、ワークフロー、および単純な検証用に POS アプリを拡張します。 |
|---|---|
| Commerce SDK 参照 | \RetailSDK\POS ModernPos.sln または CloudPos.sln ファイルを開き、POS 拡張プロジェクトに拡張子を追加します。 コア POS アプリ / Web プロジェクトは変更しません。 |
| テクノロジ | TypeScript、HTML、および CSS |
| ドキュメント | 販売時点管理 (POS) サンプルを実行 |
CRT
| シナリオ | CRT を拡張して、ビジネス ロジック (税金、価格、割引の計算のロジックなど) を追加または変更します。 |
|---|---|
| Commerce SDK 参照 | \RetailSDK\SampleExtensions\CommerceRuntime CommerceRuntimeSamples.sln ファイルを開きます。 |
| テクノロジ | C# |
| ドキュメント | Commerce runtime (CRT) および Retail サーバーの拡張機能 |
ヘッドレス Commerce API
| シナリオ | ヘッドレス コマース API 拡張機能を作成し、新しい Commerce API をクライアントに作成します。 |
|---|---|
| Commerce SDK 参照 | \RetailSDK\SampleExtensions\RetailServer RetailServer フォルダー内のサンプルの拡張機能を開きます。 |
| テクノロジ | データ プロトコル (OData) および C# を開きます |
| ドキュメント | 新しい Retail Server 拡張 API の作成 (Retail SDK バージョン 10.0.11 以降) |
TypeScript プロキシ
| シナリオ | POS または eコマース クライアントで新しいヘッドレス コマース API 拡張機能を消費する必要がある場合は、タイプスクリプト プロキシが必要です。 |
|---|---|
| Commerce SDK 参照 | \RetailSDK\SampleExtensions\RetailServer RetailServer フォルダー内のサンプルの拡張機能を開きます。 |
| テクノロジ | OData および C# |
| ドキュメント | 新しい Retail Server 拡張 API の作成 (Retail SDK バージョン 10.0.11 以降) |
Hardware station
| シナリオ | ハードウェア ステーションは、周辺機器に関連するロジックを追加または変更する必要があります。 |
|---|---|
| Commerce SDK 参照 | RetailSDK\SampleExtensions\HardwareStation HardwareStationSamples.sln ファイルを開きます。 |
| テクノロジ | C# |
| ドキュメント | POS と新しいハードウェア デバイスの統合 |
決済コネクタ
| シナリオ | POS と新しい支払いコネクタを統合します。 |
|---|---|
| Commerce SDK 参照 | \RetailSDK\SampleExtensions\HardwareStation\\Extension.PaymentSample PaymentSample.sln ファイルを開きます。 |
| テクノロジ | C# |
| ドキュメント | 支払端末のエンド・ツー・エンド支払統合を作成する |
ネーミングのベスト プラクティス
Retail SDK の C# ソース コードは、Contoso 名前空間を使用します。 したがって、Microsoft の型と拡張機能の型を簡単に区別できます。 内線番号が Microsoft バイナリの型を参照する場合は、Microsoft ライブラリと拡張機能ライブラリとを区別するために Microsoft.Dynamics を参照します。 拡張ライブラリは Microsoft.Dynamics 名で始まりません。
展開パッケージ
拡張機能 (CRT、Retail Server、データベース スクリプト、POS、およびハードウェア) の開発後は、Retail SDK を使用して配置パッケージを生成できます。 パッケージは、テスト環境、サンドボックス環境、および運用環境に配置することができます。 詳細については、配置可能なパッケージの作成 を参照してください。
相互関係、ビルド順序、およびフル ビルド
すべての拡張機能を作成し、必要な新しいプロジェクトを作成する必要があります。 (MSBuildを使用して、SDK フォルダのルートから完全なビルドを行います)。
- 拡張機能、POS プロジェクト、および梱包プロジェクトを作成する必要がありますが、Retail SDK に含まれているサンプル プロジェクトを作成する必要はありません。 Retail SDK の dirs.proj ファイルを編集して、不要なサンプル プロジェクトを削除できますが、パッケージ化されたプロジェクトや POS プロジェクトを一覧から削除しないでください。
- 拡張機能プロジェクトを適切なフォルダの dirs.proj ファイルに含めます。 SDK フォルダーのルートから MSBuild を実行すると、すべての拡張機能と必要な最新のプロジェクトが作成されます。
- SDK フォルダーのルートにある dirs.proj ファイルは、必要なすべてのプロジェクトを作成してからパッケージ プロジェクトを構築するために正しい順序で順序付けされます。 順序は正しい必要があります。 プロジェクトと依存関係を正しく作成できません。
通常の構成 / コード署名
Modern POSで、アプリ パッケージ署名証明書を正しく作成、またはクラウド POS で使用する必要があります。 PFX ファイルの作成の詳細については、パッケージの署名用の証明書を作成するを参照してください。 PFX ファイルを BuildTools フォルダーにコピーし、ModernPOSPackageCertificateKeyFile 要素を使用して BuildTools\Customization.settings ファイルを正しい名前で更新します。
BuildTools\Customization.settings ファイルには Retail SDK のほとんどの構成値が保持されています。
<!-- This section is for global settings and code signing. Any build file will inherit these values if applicable.
also use these values during package generation. -->
<AssemblyNamePrefix>MyCompany</AssemblyNamePrefix>
<CustomAssemblyVersion Condition="'$(CustomAssemblyVersion)' == ''">1.0.0.0</CustomAssemblyVersion>
<CustomVersion Condition="'$(CustomVersion)' == ''">1.0.0.1</CustomVersion>
<CustomName Condition="'$(CustomName)' == ''">MyCompany Retail Customization</CustomName>
<CustomDescription Condition="'$(CustomDescription)' == ''">MyCompany Retail Customization</CustomDescription>
<CustomPublisher Condition="'$(CustomPublisher)' == ''">MyCompany Ltd.</CustomPublisher>
<CustomCopyright Condition="'$(CustomCopyright)' == ''">MyCompany (c) 2015</CustomCopyright>
<SignAssembly Condition="'$(SignAssembly)' == ''">true</SignAssembly>
<DelaySign Condition="'$(DelaySign)' == ''">false</DelaySign>
<AssemblyOriginatorKeyFile Condition="'$(AssemblyOriginatorKeyFile)' == '' and '$(SignAssembly)' == 'true'">
$(MSBuildThisFileDirectory)\StrongNameSigningCert-Contoso.snk</AssemblyOriginatorKeyFile>
<ModernPOSPackageCertificateKeyFile Condition="'$(ModernPOSPackageCertificateKeyFile)' == ''">
$(MSBuildThisFileDirectory)\ModernPOSAppxSigningCert-Contoso.pfx</ModernPOSPackageCertificateKeyFile>
<RetailServerLibraryPathForProxyGeneration Condition="'$(RetailServerLibraryPathForProxyGeneration)' == ''">
$(SdkReferencesPath)\Microsoft.Dynamics.Retail.RetailServerLibrary.dll</RetailServerLibraryPathForProxyGeneration>
グローバル値は次の値です。 これらの値は、ビルド管理バイナリ、コンポーネント、パッケージの名前付け、バージョン管理、コード署名の方法を制御します。
- AssemblyNamePrefix
- CustomAssemblyVersion
- CustomVersion
- CustomName
- CustomDescription
- CustomPublisher
- CustomCopyright
- SignAssembly
- AssemblyOriginatorKeyFile
- ModernPOSPackageCertificateKeyFile
- RetailServerLibraryPathForProxyGeneration
厳密な名前は必須ではありませんが、厳密な名前でアセンブリに署名することをお勧めします。 まだキー ファイルを所有していない場合に独自のキー ファイルを作成する方法については 方法: パブリックプライベート キーの変更を作成するを参照してください。
Modern POS、ハードウェア ステーション、Store scale unit、単位などのセルフサービス コンポーネントに対して生成されたインストーラー ファイルは SignTool. exe を使用して署名できます。
厳密な名前のキー ファイルとアプリ パッケージの署名証明書の両方を BuildTools フォルダー内または Azure Key Vaylt に保存することができます。 パスワードで保護された証明書またはセキュリティで保護された証明書の場合は、Azure Key Vault を使用します。
ビルドのカスタマイズ
新しいプロジェクトの追加
簡単に新しいプロジェクトを Retail SDK のビルド システムに追加することができます。 多くの既存のプロジェクトのいずれかを複製するか、新しいプロジェクトを開始することができます。 次の図に示すように、テキスト エディタでいくつかの調整を加える必要があるだけです。 Import 要素の相対パスを調整する必要があり、AssemblyName 要素は定義済みの AssemblyNamePrefix プロパティを使用する必要があります。 これらの調整は、バージョン管理、コード署名、統一されたアセンブリ命名、[参照] フォルダーへの自動ドロップなどのさまざまなタスクを無料で行うために必要です。
ビルド順序の変更またはビルドへの追加
Retail SDK のディレクトリ ツリー全体を構築するために、MSBuild トラバーサル ファイル (dirs.proj ファイル) が使用されています。 次の図は、Retail SDK の主なトラバーサルファイルを示しています。 類似したファイルは、サブディレクトリにも存在する場合があります。 Visual Studio ソリューション ファイル (.sln ファイル) がトラバーサル ファイルに非常に類似していることに注意します。 どちらも MSBuild エンジンに対して、他のビルド スクリプトを処理するよう命令します。
新しいコードを追加した後、そのほとんどを新しいフォルダーに格納する必要があります。 また、1 つ以上の dirs.proj ファイルに追加して、その構造を簡単な構造に追加する必要があります。 拡張フォルダーは、前述の図の 10 行目で強調表示されています。 新しい dirs.proj ファイルを開始する最も簡単な方法は、既存のファイルをコピーし、Import 要素のパスを修正して、ItemGroup 要素の ProjectFiles 要素を更新することです。
ビルド スクリプトのカスタマイズ
新しいビルド ステップを実装する必要があるとき、既存のスクリプトが Retail SDK 更新プログラムで後で更新される可能性があることに留意してください。 ベスト プラクティスはファイルの編集を最小限にするか、新しいファイルを代わりに追加します。 新しいグローバル MSBuild プロパティが必要な場合、BuildTools\Microsoft.Dynamics.RetailSDK.Build.props ファイルはそれらを追加する上でお勧めです。 同様に、BuildTools\Microsoft.Dynamics.RetailSDK.Build.targets ファイルは、新しいビルド処理のターゲットを追加するために使用できます。
1 つのプロジェクトで特別な処理が必要とならない場合は、明示的に変更を加えることをお勧めします。 新しいローカル MSBuild プロパティが必要な場合は、同じディレクトリに local.props ファイルを追加します。 または、ローカル ビルド処理ターゲットが必要な場合は、local.targets ファイルを追加します。
開発者の生産性
CommerceRuntime および RetailServer 拡張 ダイナミック リンク ライブラリ (DLL) をローカルにインストールされた RetailServer Web アプリケーションの bin フォルダーにコピーする必要があります。 ユーザーは、Customization.setting ファイルをコンフィギュレーションして、これらのファイルの新しいバージョンが拡張機能プロジェクトからビルドされるたびに、DLL がローカルの RetailServer Web アプリケーションの bin フォルダーに自動的にコピーされるようにできます。
アプリケーション ライフサイクル管理
優れたアプリケーション ライフサイクル管理 (ALM) ソリューションは、バージョン管理、ビルド、自動ビルド、プランニング ツール、追跡ツール、ダッシュ ボード、カスタマイズなどを提供します。 Retail SDK の組織は、これらの作業をサポートしています。
分岐およびバージョン管理
チームで効率的に仕事をしたり、以前に行ったいくつかの変更を確認できるようにするには、適正な分岐戦略とバージョン管理の規範が必要です。 次の図は、ほとんどのチームでうまくいく単純な分岐戦略を示しています。 バージョン番号は、架空のものです。 詳細については、Git の分岐戦略を採用するを参照してください。
Retail SDK のミラー分岐
強調すべき非常に重要なポイントは、カスタマイズされていない Retail SDK をソース コントロールに保存する必要があるということです。 すべてのバージョンを保存する必要はありませんが、チームがスナップするバージョンを追加する必要があります。 (これらのバージョンは、累積更新プログラムまたは修正プログラムである可能性があります)。すべての変更 (追加、変更、削除) の単純マージのみを行う必要があります。 このブランチで発生する他の開発作業はありません。 Retail SDK には、独自のバージョンがあります。 すべての Commerce バイナリおよびパッケージには同じバージョンが含まれています。 バージョンは、Microsoft-version.txt という名前のファイルの SDK フォルダーのルートにもあります。
カスタマイズ分岐
配置のために、新しいカスタマイズ分岐を作成する必要があります。 初期分岐アウトの先頭において、この分岐は Retail SDK ミラー分岐の正確なコピーになります。 チームの開発に使用される分岐です。 カスタマイズ分岐のバージョンは、少なくともテストのためにビルドが作成されるたびに増分する必要があります。 毎日増やすことも可能です。 増分するファイル バージョンは、CustomVersion プロパティを使用して Customization.setting ファイルで定義されます。 バージョンを更新し、すべてのバイナリ、パッケージを再構築すると、マニフェスト ファイルはそれに応じて更新されます。
CustomAssemblyVersion プロパティは、更新プログラムに下位互換性がなく、主な新しいリリースに対して互換性がない場合のみ更新する必要があることに注意してください。 つまり、このプロパティの更新プログラムはめったにありません。 前述の図では、カスタマイズ分岐の現在のファイル バージョンは、1.0.2 です* (Microsoft バージョン 7.0.2200.3 に基づく)。 展開された最初のリリースのファイル バージョンは 1.0.0.40 (Microsoft バージョン 7.0.2000.0 に基づく) でした。 テスト フェーズが完了し、最後のパッケージがそのバージョンで配置されるとき、バージョン番号を増分するか、またはソース コントロールのラベルを作成することが重要です。