TypeScript および小売販売時点管理 (POS) の C# プロキシ

[アーティクル]
03/08/2023

新しい小売サーバー API を作成する場合は、Retail ソフトウェア開発キット (SDK) の一部として使用できるツールを使用して、Commerce プロキシを生成する必要があります。たとえば、新しい Retail サーバー API を追加する場合は、Commerce プロキシを生成する必要があります。

Commerce プロキシとそれを使用する場合

すべてのクライアントは Retail Serve とやりとりするためにプロキシ API を使用します。 Commerce プロキシは、Retail Server と Commerce Runtime (CRT) 間のインターフェイスを抽象化します。たとえば、CRT で要求/応答の操作として新しいエンティティとビジネスロジックを作成し、そのエンティティおよびそれらの要求/応答の操作を公開するために、新しい Retail サーバー API を追加できます。販売時点管理 (POS) におけるエンティティと要求/応答動作にアクセスして、あるクライアントロジックを実行する必要が出てきました。 POS ですべてのエンティティと要求/応答メタデータを手動で作成し、適切なパラメーターを使用して Retail サーバー API にアクセスすることができます。ただし、エンティティ、マネージャ、および 2 つの場所で要求/応答コードを複製する必要があり、および多くのコードの書き込みもする必要があるため、このアプローチには追加の間接費が多く含まれます。

Commerce プロキシは、Retail Server に追加されたすべてのユーザー定義エンティティと要求/応答操作のプロキシを自動的に作成することによって、この労力を軽減します。プロキシツールは、必須のインターフェイスとすべての必須メタデータを生成し、実際の実装を抽象化します。この方法では、拡張プロジェクトにファイルを含めることができ、生成されたメタデータとインターフェイスを使用して Retail サーバー API とエンティティにアクセスできます。

プロキシのタイプ

クロスプラットフォームシナリオをサポートするプロキシのタイプには 2 つあります。

TypeScript プロキシ- POS は、TypeScript プロキシを使用して Retail Server API および CRT エンティティにアクセスします。 POS が Retail Server を使用する場合は、TypeScript プロキシが必要です。それ以外の場合、POS はオペレーションまたはワークフローのために Retail サーバーと通信することができません。
C# プロキシ - POS はオフラインのときに C# プロキシを使用します。 (POS がオフラインの場合、Retail サーバーを使用せずに CRT と直接通信します)。POS は、Dynamics 電子商取引プラットフォームにもこのプロキシを使用します。カスタマイゼーションを POS がオフラインのときに動作させ、電子商取引クライアントを Retail Server API にアクセスするようにするには、C＃プロキシを生成する必要があります。

TypeScript プロキシを生成する手順と C# プロキシを生成する手順は異なります。この記事の後半では、各タイプのプロキシを生成する方法について説明します。

TypeScript プロキシ (10.0.11 以前) Retail Server の生成

Microsoft Dynamics Commerce バージョン 10.0.12 以降を使用している場合は、新しい Ratail サーバー拡張機能 API を作成するで説明している手順に従ってください。

重要

Retail SDK ルートフォルダーから MSBuild を実行して、CommerceProxyGenerator.exe パッケージを復元します。 Visual Studio の開発者コマンドプロンプト、または MSBuild コマンドプロンプトを使用して、参照フォルダー内のすべてのパッケージを復元してから、プロキシを生成します。この手順を実行しないと、RetailSDK\Reference フォルダーで CommerceProxyGenerator.exe パッケージを利用できません。

Retail SDK\Reference\Microsoft.Dynamics.Commerce.Tools.CoreProxyGenerator.<version_number>\tools フォルダーから CommerceProxyGenerator.exe ファイルを使用して、POS の typescript プロキシを生成します。

プロキシを生成する前に、カスタマイズされた Retail サーバー API、CRT、その他の依存ライブラリを、Retail SDK\参照 フォルダーにコピーしてください。
管理者としてコマンドプロンプトウィンドウを開き、...\Retail SDK\Reference\Microsoft.Dynamics.Commerce.Tools.CoreProxyGenerator<version_number>\tools フォルダへ移動します。次のコマンドを実行してプロキシを生成します。プロキシファイルは同じフォルダーに生成されます。

POS TypeScript プロキシ

    CommerceProxyGenerator.exe <Path>\Microsoft.Dynamics.Retail.RetailServerLibrary.dll <FilePathNameForRetailServerExtensionDLL> /application:typescriptextensions

E コマース TypeScript プロキシ

   CommerceProxyGenerator.exe <Path>\Microsoft.Dynamics.Retail.RetailServerLibrary.dll <FilePathNameForRetailServerExtensionDLL> /application:typescriptmoduleextensions

メモ

Microsoft.Dynamics.Retail.RetailServerLibrary.dll file from \RetailSDK\References\Microsoft.Dynamics.Commerce.Tools.ExtensionsProxyGenerator.<version_number>\build を使用します。

Example
CommerceProxyGenerator.exe C:\\RetailSDK\\References\\Microsoft.Dynamics.Commerce.Tools.ExtensionsProxyGenerator.9.21.20042.5\\build\\Microsoft.Dynamics.Retail.RetailServerLibrary.dll C:\\RetailSDK\\References\\Microsoft.Dynamics.RetailServer.CrossLoyaltySample.dll /a:typescriptextensions

実行するコマンドで、Microsoft.Dynamics.RetailServer.CrossLoyaltySample.dll をカスタム Retail サーバー拡張ライブラリの名前に置き換えます。 POS プロジェクトに生成されたファイルを含めます。このコマンドは、拡張ライブラリに基づいた 2 つのファイル、DataServiceEntities.g.ts と DataServiceRequests.g.tss を生成します。

C# プロキシ (Commerce バージョン 10.0.11 以下) の生成

重要

この Microsoft.Dynamics.Commerce.Hosting.Contracts API を使用してビルトされた Retail Server 拡張機能は、オフライン実装でも使用でき、別に C# プロキシライブラリを作成する必要はありません。この手順は、Dynamics.Commerce.Runtime.Hosting.Contracts を使用しない Commerce バージョン 10.0.11 以前、または低またはRetail Server の拡張機能に対してのみ必要です。

Retail サーバー拡張機能ごとに、別個のプロキシを生成する必要があります。

RetailSDK\SampleExtensions\RetailProxy\RetailProxy.Extensions.StoreHoursSample に移動します。
Microsoft Visual Studio で、Proxies.RetailProxy.Extensions.StoreHoursSample プロジェクトファイルを開きます。
右クリックし、プロジェクトのアンロードを選択します。
プロジェクトを右クリックし、Proxies.RetailProxy.Extensions.StoreHoursSample.csproj を選択して編集します。
最初のプロパティグループセクションで、次のノードを更新します。
- <RootNamespace> – ユーザー設定の名前空間を指定します。
- <AssemblyName> – プロキシのカスタム出力ライブラリ名を指定します。
Retail サーバーの拡張機能ライブラリ名を指定して、CommerceProxyGeneratorExtendedAssemblyPaths 要素を更新します。

次に例を示します。
```
<CommerceProxyGeneratorExtendedAssemblyPaths Include="..\..\RetailServer\Extensions.StoreHoursSample\bin\$(Configuration)\net451\$(AssemblyNamePrefix).RetailServer.StoreHoursSample.dll" />
```
メモ

.RetailServer.StoreHoursSample.dll は、Retail サーバー拡張アセンブリの名前です。残りの値は、接頭語 (接頭語がある場合) と、プロキシエンジンがこのアセンブリを見つけることができるアセンブリのパスです。プロキシは、このアセンブリに基づいて生成されます。
ファイルを保存し、プロジェクトを再度読み込みます。
拡張パターンに従って、プロジェクトの名前を変更します。
プロジェクトが読み込まれた後、アダプタ フォルダから StoreDayHoursManager.cs ファイルを削除します。
すべての関連する CRT と Retail サーバーライブラリをプロジェクトまたはアセンブリ参照としてプロキシプロジェクトに追加します。
プロジェクトをリビルドします。

アダプタフォルダー内で新しい Interfaces.g.cs ファイルが生成されると表示されます。

メモ

プロキシプロジェクトを作成する前に、すべての CRT および Retail サーバー拡張ライブラリを再構築して、RetailSDK\References フォルダーにドロップしてください。
プロキシプロジェクト内に新しい Interfaces.g.cs ファイルを含めます。ただし、このファイルを変更しないでください。
アダプタ フォルダーで、新しいクラスファイルを追加し、拡張機能のパターンに従って名前をつけます。
インターフェイスマネージャークラスからクラスを拡張し、必要なインターフェイスメソッドのみを実装します。

メモ

Interfaces.g.cs. ファイルで、インターフェイスマネージャークラスの名前を見つけることが

次の例では、IStoreDayHoursManager はインターフェイスの名前です。
```
public interface IStoreDayHoursManager : Microsoft.Dynamics.Commerce.RetailProxy.IEntityManager
{
}
```
フルサンプルコードについては、RetailSDK\SampleExtensions\RetailProxy\RetailProxy.Extensions.StoreHoursSample にある Proxies.RetailProxy.Extensions.StoreHoursSample プロジェクトをご覧ください。
メソッド内で、実際の CRT 要求/応答を呼び出します。プロキシプロジェクトに任意のロジックを含めないようにしてください。プロキシプロジェクトは、CRT 要求/応答だけを呼び出す必要があります。
プロジェクトを構築します。
出力アセンブリをコピーして、RetailSDK\References フォルダーに貼り付けます。
RetailSDK\Assets フォルダーに移動して RetailProxy.MPOSOffline.ext.config を開きます。
合成セクションで、新しいプロキシライブラリ (つまり、プロキシプロジェクトをビルドした後に生成されたアセンブリ) の名前を登録します。

次に例を示します。
```
<add source="assembly" value="Contoso.Commerce.RetailProxy.StoreHoursSample" />
```
この例では、プロキシライブラリ名は Contoso.Commerce.RetailProxy.StoreHoursSample です。プロキシライブラリの名前は、値フィールドで指定してください。
手動テストでは、C:\Program Files (x86)\Microsoft Dynamics 365\70\Retail Modern POS\ClientBroker\ext にある RetailProxy.MPOSOffline.ext.config ファイルを開きます。カスタムプロキシライブラリの名前で合成セクションを更新します。

次に例を示します。
```
<add source="assembly" value="Contoso.Commerce.RetailProxy.StoreHoursSample" />
```
電子商取引の場合、電子商取引プロジェクトから呼び出しする前に、拡張のプロキシを初期化する必要があります。電子商取引の Startup.cs ファイル (または、Web プロジェクトの初期化などの同等のファイル) で、Retail プロキシ拡張の拡張データモデル (EDM) を使用して RetailServerContext を初期化します。それ以外の場合、プロキシのを呼び出そうとすると、ランタイムエラーが表示されます。このステップは 1 回のみ完了する必要があります。

次に例を示します。
```
RetailServerContext.Initialize(newIEdmModelExtension[]
{
    // /* BEGIN SDKSAMPLE_STOREHOURS
    new Contoso.Commerce.RetailProxy.StoreHoursSample.EdmModel(),
    // END SDKSAMPLE_STOREHOURS */
});
```

次の方法で共有