次の方法で共有

Commerce SDK サンプルと参照パッケージを GitHub および NuGet からダウンロードする

  • [アーティクル]

この記事では、Microsoft Dynamics 365 Commerce ソフトウェア開発キット (SDK) サンプルを GitHub および参照パッケージからダウンロードする方法について説明します。

メモ

この記事は、Commerce SDK バージョン 10.0.16 およびそれ以降に適用されます。 Commerce SDK の以前のバージョンをダウンロードする詳細方法については、Retail ソフトウェア開発キット (SDK) を参照してください。

Commerce SDK には、Dynamics 365 Commerce 機能を拡張やカスタマイズするために必要な、コード、コード サンプル、テンプレート、およびツールが含まれています。 SDK は、拡張コンポーネントに応じて、GitHub の異なるレポジトリ (Repos) で公開されます。

Commerce SDK は、迅速な開発、MSBuild との完全な統合、およびパッケージ生成をサポートしています。 次の図に、開発環境とクラウド コンポーネントの関係を示します。

Commerce コンポーネント。

Dynamics 365 Commerce の拡張コンポーネント

次の表は、さまざまなシナリオにカスタマイズできる Commerce SDK の各コンポーネントについての情報です。

クライアント (Store Commerce)

シナリオ ユーザー エクスペリエンス (UX) の変更、クライアント ロジック、ワークフロー、および単純な検証用に Store Commerce アプリを拡張します。
Commerce SDK 参照 Store Commerce アプリのサンプル
テクノロジ TypeScript、HTML、および CSS
ドキュメント 販売時点管理 (POS) サンプルを実行

Commerce Runtime (CRT)

シナリオ CRT を拡張して、ビジネス ロジック (税金、価格、割引の計算のロジックなど) を追加または変更します。
Commerce SDK 参照 CRT サンプル
テクノロジ C#
ドキュメント Commerce runtime (CRT) および Retail サーバーの拡張機能

ヘッドレス Commerce API

シナリオ ヘッドレス コマース API 拡張機能を作成し、新しい Commerce API をクライアントに作成します。
Commerce SDK 参照 Retail Server サンプル
テクノロジ データ プロトコル (OData) および C# を開きます
ドキュメント 新しい Retail Server 拡張 API の作成 (Retail SDK バージョン 10.0.11 以降)

TypeScript プロキシ

シナリオ POS または eコマース クライアントで新しいヘッドレス コマース API 拡張機能を消費する必要がある場合は、タイプスクリプト プロキシが必要です。
Commerce SDK 参照 CommerceProxyGenerator
テクノロジ OData および C#
ドキュメント 新しい Retail Server 拡張 API の作成 (Retail SDK バージョン 10.0.11 以降)

Hardware station

シナリオ ハードウェア ステーションは、周辺機器に関連するロジックを追加または変更する必要があります。
Commerce SDK 参照 src\HardwareStationSample サンプル
テクノロジ C#
ドキュメント POS と新しいハードウェア デバイスの統合

決済コネクタ

シナリオ POS と新しい支払いコネクタを統合します。
Commerce SDK 参照 src\HardwareStationSample\PaymentDevices
テクノロジ C#
ドキュメント 支払端末のエンド・ツー・エンド支払統合を作成する

ネーミングのベスト プラクティス

Commerce SDK の C# ソース コードは、Contoso 名前空間を使用します。 したがって、Microsoft の型と拡張機能の型を簡単に区別できます。 内線番号が Microsoft バイナリの型を参照する場合は、Microsoft ライブラリと拡張機能ライブラリとを区別するために Microsoft.Dynamics を参照します。 拡張ライブラリは Microsoft.Dynamics 名で始まりません。

展開パッケージ

拡張機能の開発 (CRT、Retail Server、データベース スクリプト、POS、およびハードウェア ステーション) 後、配置パッケージを生成して、テスト環境、サンドボックス環境、運用環境に展開できます。 詳細については、配置可能なパッケージの作成 を参照してください。

以下のサンプル リポジトリには、既存の Commerce 機能を拡張やカスタマイズするために必要な、コード サンプル、テンプレート、およびツールが含まれています。 サンプルは、Commerce 拡張コンポーネントに基づいて、GitHub のリポジトリに公開されます。 これらのリポジトリを閉じる必要はなく、サンプル プロジェクトとテンプレート プロジェクトをダウンロードして使用することができます。

Dynamics365Commerce.ScaleUnit リポジトリ

Dynamics365Commerce.ScaleUnit リポジトリには、Commerce runtime (CRT)、Retail Server およびチャネル データベースをカスタマイズするためのサンプル コードが含まれています。

リポジトリ内のサンプルは、Dynamics 365 Commerce アプリケーション リリースごとに管理されています。 リポジトリ内の各分岐は、Dynamics 365 Commerce のアプリケーション リリースを指しています。 Go-Live バージョンと一致するリリース分岐を使用します。 このリポジトリを複製する必要はなく、サンプル プロジェクトとテンプレート プロジェクトをダウンロードして使用することができます。

リリース ブランチ名 バージョン アプリケーション リリース バージョン
リリース/9.38 9.38.* 10.0.28
リリース/9.37 9.37.* 10.0.27
リリース/9.38 9.36.* 10.0.26

拡張リポジトリ (Dynamics365Commerce.ScaleUnit)

microsoft/Dynamics365Commerce.ScaleUnit からサンプルとテンプレートをダウンロードして使用できます。 リポジトリには、nuget.config、repo.props、CustomizationPackage.props、およびビルド パイプライン スクリプトが含まれています。 同時に、拡張機能でリポジトリ メタデータ ファイルを設定する方法に関するガイダンスを提供します。

Dynamics365Commerce.ScaleUnit リポジトリ フォルダーおよびプロジェクト

フォルダー Project Description
チャネル データベース (./src/ScaleUnitSample/ChannelDatabase) ChannelDatabase.csproj (./src/ScaleUnitSample/ChannelDatabase/ChannelDatabase.csproj) このプロジェクトには、Commerce Runtime データベース拡張機能の作成方法に関するサンプルが含まれています。
CommerceRuntime (./src/ScaleUnitSample/CommerceRuntime) CommerceRuntime.csproj (./src/ScaleUnitSample/CommerceRuntime/CommerceRuntime.csproj) コントローラー – 新しい RS API の実装方法のサンプル コード。
エンティティ、メッセージ、および RequestHandlers – 新しい CRT サービスの実装方法のサンプル コード。
ScaleUnit (./src/ScaleUnitSample/ScaleUnit) ScaleUnit.csproj (./src/ScaleUnitSample/ScaleUnit/ScaleUnit.csproj) Cloud Scale Unit (CSU) の生成方法に関するサンプル プロジェクト。
ScaleUnit.Installer (./src/ScaleUnitSample/Installer) ScaleUnit.csproj (./src/ScaleUnitSample/Installer/ScaleUnit.Installer.csproj) CSU インストーラーの生成方法に関するサンプル プロジェクト。
POS (./src/ScaleUnitSample/POS) POS.csproj (./src/ScaleUnitSample/POS/POS.csproj) 販売時点管理 (POS) 拡張機能の作成方法についてのサンプルが含まれています。
E-CommerceProxyGenerator (./src/ScaleUnitSample/E-CommerceProxyGenerator) E-CommerceProxyGenerator.csproj (./src/ScaleUnitSample/E-CommerceProxyGenerator/E-CommerceProxyGenerator.csproj) eコマース アプリケーションの拡張プロキシを生成する方法のサンプルが含まれています。

Store Commerce アプリ、Web 用 Store Commerce、ハードウェア ステーション、Cloud Scale Unit などの店舗内コンポーネントのサンプル – Dynamics365Commerce.InStore リポジトリに自己ホストされ公開されます。

Commerce Runtime、ChannelDatabase および ScaleUnit フォルダーの readme.md ファイルには、サンプルの実行方法に関する詳細が含まれています。

Dynamics365Commerce.InStore リポジトリ

Dynamics365Commerce.InStore リポジトリには、POS、ハードウェア ステーション、Commerce runtime (CRT)、ヘッドレス Commerce API、およびチャネル データベースをカスタマイズする方法のサンプル コードが含まれています。

リポジトリのサンプルは Dynamics 365 Commerce アプリケーション リリースごとに管理されており、リポジトリ内の各分岐は、Dynamics 365 Commerce のアプリケーション リリースを指しています。 Go-Live バージョンと一致するリリース分岐を使用します。 このリポジトリを複製する必要はなく、サンプル プロジェクトとテンプレート プロジェクトをダウンロードして使用することができます。

リリース ブランチ名 バージョン アプリケーション リリース バージョン
リリース/9.38 9.38.* 10.0.28
リリース/9.37 9.37.* 10.0.27
リリース/9.36 9.36.* 10.0.26

拡張リポジトリ (Dynamics365Commerce.InStore)

microsoft/Dynamics365Commerce.InStore からサンプルとテンプレートをダウンロードして使用できます。 リポジトリには、nuget.config、repo.props、CustomizationPackage.props、およびビルド パイプライン スクリプトが含まれています。 同時に、拡張機能でリポジトリ メタデータ ファイルを設定する方法に関するガイダンスを提供します。

Dynamics365Commerce.InStore リポジトリ フォルダーおよびプロジェクト

フォルダー Project Description
HardwareStationSample HardwareStation.Samples.sln このプロジェクトには、ハードウェア ステーション、支払拡張機能、拡張機能インストーラーの作成方法についてのサンプルが含まれています。
POSSample Pos.sln このフォルダーとプロジェクトには、POS、CRT、ヘッドレス Commerce API、ハードウェア ステーション拡張とインストーラー サンプルが含まれています。

CSU のその他のサンプル – 自己ホスト、Commerce Runtime、ヘッドレス Commerce API は Dynamics365Commerce.ScaleUnit リポジトリで公開されます。

プロジェクト フォルダー内の readme.md ファイルには、これらのサンプルの実行方法に関する詳細が含まれています。

Dynamics365Commerce.Solutions リポジトリ

Dynamics365Commerce.Solutions リポジトリには、Commerce で E2E ビジネス シナリオのカスタマイズを実行する方法を示すサンプルが含まれています。 POS、eコマース、または本社のヘッドレス コマース エンジンをカスタマイズする必要がある可能性があります。

API の作成、およびメッセージ、要求、エンティティ、契約の消費に関する参照パッケージをダウンロードする

Dynamics 365 Commerce アプリケーションの既存の機能の消費およびカスタマイズ、または新しい機能をビルドする Commerce 拡張機能コード用に、Commerce 契約、メッセージ、エンティティ、および要求パッケージはこのパブリック フィードに公開されます。

index.json からのパッケージを使用します。 次のコード例にあるとおり、パッケージのソースの場所を拡張機能プロジェクト ファイルの nuget.config ファイルに追加できます:

<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>

パブリック フィードで使用できる参照パッケージ

パッケージ名 Description
Microsoft.Dynamics.Commerce.Sdk.ChannelDatabase このパッケージは、CSU を含む DB パッケージを生成するために必要です。
Microsoft.Dynamics.Commerce.Sdk.Runtime このメタ パッケージには、CRT および Retail Server 拡張機能を実装するために必要なすべてのパッケージが含まれています。 このパッケージには、必要なすべての契約、メッセージ、要求/応答、およびエンティティが含まれています。
Microsoft.Dynamics.Commerce.Sdk.ScaleUnit このパッケージは、展開用 CSU パッケージを生成するために必要です。
Microsoft.Dynamics.Commerce.Sdk.Installers.ScaleUnit このパッケージは、展開用 ScaleUnit パッケージを生成するために必要です。
Microsoft.Dynamics.Commerce.Sdk.HardwareAndPeripherals このパッケージには、Commerce ハードウェア ステーションおよび周辺機器ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.Sdk.Installers このパッケージには、インストーラー ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.Sdk.Installers.HardwareStation このパッケージは、展開用ハードウェア ステーション パッケージを生成するために必要です。
Microsoft.Dynamics.Commerce.Sdk.Pos このパッケージには、POS ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.Sdk.Installers.ModernPos このパッケージは、展開用 POS 拡張機能インストーラーを生成するために必要です。
Microsoft.Dynamics.Commerce.Diagnostics このパッケージには、診断ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.Runtime.Data このパッケージには、データ コントラクト ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.Runtime.DataServices.Messages このパッケージには、データ サービス メッセージ ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.Runtime.Entities このパッケージには、エンティティ定義がすべて含まれています。
Microsoft.Dynamics.Commerce.Runtime.Framework このパッケージには、フレームワーク ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.Runtime.Hosting.Contracts このパッケージには、コントローラー ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.Runtime.Messages このパッケージには、ランタイム メッセージ ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.Runtime.RealtimeServices.Messages このパッケージには、リアル ランタイム ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.Runtime.Services.Messages このパッケージには、サービス メッセージ ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.HardwareStation.Core このパッケージには、ハードウェア ステーション ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.HardwareStation.PeripheralRequests このパッケージには、ハードウェア ステーション周辺機器要求ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.HardwareStation.Peripherals.Contracts このパッケージには、ハードウェア ステーション周辺機器契約ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.HardwareStation.Peripherals.Entities このパッケージには、ハードウェア ステーション周辺機器エンティティ ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.Installers.Framework このパッケージには、インストーラー フレームワーク ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.KeyVault.Contracts このパッケージには、Key Vault コントラクト ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.PaymentSDK.Extensions.Portable このパッケージには、支払拡張機能ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.PaymentSDK.Portable このパッケージには、支払ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.Runtime.FIF.Connector.Messages このパッケージには、FIF コントローラー ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.Runtime.FIF.DocumentProvider.Messages このパッケージには、FIF ドキュメント プロバイダー ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.Installers.Framework.DatabaseExtensions このパッケージには、データベース インストーラー フレームワーク ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.Tools.DbUtilities このパッケージには、データベース ユーティリティ ライブラリがすべて含まれています。
Microsoft.Dynamics.Commerce.Tools.ExtensionsProxyGenerator.AspNetCore このパッケージには、拡張機能プロキシ ジェネレーター ユーティリティがすべて含まれています。
Microsoft.Dynamics.Commerce.Proxy.ScaleUnit このパッケージには、拡張機能アプリケーションがオンライン モード (ヘッドレス Commerce に接続) でヘッドレス Commerce API を消費するためのプロシキ クラスがすべて含まれています。

パッケージのバージョン管理

パッケージ バージョン アプリケーション リリース
9.36.x.x-プレビュー 10.0.26 PEAP/プレビュー リリース
9.36.x.x 10.0.26 顧客プレビュー
9.36.x.x 10.0.26 GA
9.37.x.x-プレビュー 10.0.27 PEAP/プレビュー リリース
9.37.x.x 10.0.27 顧客プレビュー
9.37.x.x 10.0.27 GA
9.38.x.x-プレビュー 10.0.28 PEAP/プレビュー リリース
9.38.x.x 10.0.28 顧客プレビュー
9.38.x.x 10.0.28 GA

拡張機能プロジェクトでは、プロジェクトにパッケージの参照を追加し、完全なバージョン番号を含めると、正しいバージョンを消費できます。 または、拡張機能プロジェクトで常に最新バージョンを取得するには、ワイルドカード文字を使用します。 完全なバージョン番号を使用し、Go-Live バージョンに基づいてバージョンを更新することをお勧めします。 次の 2 つのオプションがあります。

  • ワイルドカード文字がない場合:

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

  • ワイルドカード文字がある場合:

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

修正プログラムと新しいアプリケーション リリースごとに、パッケージのバージョンが同じパブリック フィードで公開されます。Go-Live バージョンに必要なバージョンに基づいて適切なパッケージ バージョンを消費してください。 Go-Live アプリケーション バージョンよりも高いバージョンのパッケージを消費すると、実行時および展開でエラーが発生する場合があります。

ビルド自動化とパッケージ生成用の Azure パイプラインを設定する

Azure パイプラインを設定するには、独立したパッケージ SDK のビルド パイプラインの設定を参照してください。

ベスト プラクティスと分岐戦略

Git 分岐戦略の詳細については、Git 分岐戦略を参照してください。

次の分岐戦略は、Microsoft が Git を使用する方法に基づいて行います。 詳細については、Microsoft で Git を使用する方法を参照してください。

分岐戦略を単純に保ちます。 これらの 3 つの概念から戦略をビルドします:

  • すべての新しい機能とバグ修正プログラムに対して機能分岐を使用します。
  • プル要求を使用して、機能分岐をメイン分岐にマージします。
  • 高品質かつ最新のメイン分岐を維持します。

開発とバグ修正プログラムのための新しい機能分岐を作成する

Git の分岐ドキュメントによる名前付け規則のサンプルで名前付け規則に従って、拡張機能に対する新しい機能メイン分岐を作成します。

新しい開発分岐を作成する

新しい開発分岐を作成するには、次の手順に従います:

  1. 開発用のプライベート分岐を作成します。

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

  2. 変更を開発分岐に追加し、コミットします。 たとえば次のようにできます。

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

  3. 開発が完了し、テストと検証が行われた後、変更をメイン分岐にプッシュします。 たとえば次のようにできます。

    git push <remote> <branch>

    または:

    git push origin {private branch name}

開発後にリリース分岐を作成する

開発後にリリース分岐を作成するには、次の手順に従います:

  1. 開発変更をメイン分岐にプッシュした後、新しいリリース分岐を作成し、リリース分岐から配置可能パッケージを作成します。

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

  2. リリース分岐で変更が行われた場合に、その変更をリリース分岐からメイン分岐にマージします。 たとえば次のようにできます。

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

拡張機能修正プログラムの分岐

  1. メイン 岐から拡張機能用の修正プログラム分岐を作成します。 詳細については、開発後にリリース 分岐を作成するを参照してください。
  2. 修正プログラムをリリースします。
  3. 変更をメイン分岐にマージします。

新しいリリース分岐をメイン分岐および開発分岐にマージする

サンプルの新しいバージョンのリリース後に、必要に応じて開発分岐を新しい分岐にマージします。 リポジトリにはサンプルだけが含まれているので、分岐から更新された変更を取得する必要はありません。 たとえば次のようにできます。

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