POS を新しいハードウェアデバイスと統合し、拡張機能インストーラーを生成

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

この記事では、販売時点管理 (POS) を新しいハードウェアデバイスと統合し、拡張機能インストーラーを生成する方法について説明します。

Hardware Station の概要

Hardware Station は、プリンター、キャッシュドロワー、スキャナー、および支払ターミナルなどのハードウェア周辺機器に接続するために Modern POS および Cloud POS で使用されます。

HWS-Local-Traditional

共有ハードウェアステーション

Hardware Station 設定

開始する前に、 Retail ハードウェアステーションのコンフィギュレーションとインストールの情報を使用してハードウェアステーションをインストールし、ハードウェアがどのようなものでインストールがどのようにされているかを知ることができます。

Hardware Station アーキテクチャ

ハードウェアステーションは、ハードウェアステーションアプリケーションプログラミングインターフェイス (API) 用の Web API を公開します。新しいデバイス (たとえば、現金自動支払機) の新しいコントローラーを実装するか、または既存のデバイスタイプ (たとえば、新しいオーディオジャック磁気ストライプリーダー (MSR) の実装) の既存のコントローラーを上書きするかのいずれかによって、ハードウェアステーションを拡張できます。

ハードウェアステーションアーキテクチャ

Hardware Station 拡張性シナリオ

.NTE にサポートされている Managed Extensibility Framework (MEF) を使用して、ハードウェアステーションの拡張性が獲得されます。 拡張性の規定: 拡張機能アセンブリで、常に、拡張機能の書き込みをします。そのようにして、実際の拡張機能を記述し、アップグレードがかなり簡単になります。拡張のための 2 つの基本的なシナリオがあります。

新しいデバイスを追加する - 最初から用意されているハードウェアステーションはデバイス (現金自動支払機など) をまだサポートしていません。したがって、ハードウェアステーションで新しいデバイスのサポートを追加する必要があります。
既存のデバイスに対する新しいデバイスタイプを追加する - 最初から用意されているハードウェアステーションの実装ではすでにデバイス (MSR など) がサポートされていますが、特定のデバイスタイプ (オーディオジャック MSR 実装) のサポートを追加する必要があります。

POS からハードウェアステーション API を呼び出すには、要求と応答を使用する必要があります。

HardwareStationDeviceActionRequest – POS からハードウェアステーションに送信される要求。
HardwareStationDeviceActionResponse – ハードウェアステーションから POS が受信した要求。

拡張するクラスは、使用している Retail ソフトウェア開発キット (SDK) のバージョンによって異なります。

Retail SDK バージョン 10.0.11 以降では、IController インターフェイスを拡張します。

HardwareStationDeviceActionRequest

次のコード例は、HardwareStationDeviceActionRequest の定義を示します。

class HardwareStationDeviceActionRequest<TResponse extends HardwareStationDeviceActionResponse> extends Request<TResponse> {
    readonly device: string;
    readonly action: string;
    readonly actionData: any;
    constructor(device: string, action: string, actionData: any, correlationId?: string);
}

次の表では、パラメーターについて説明します。

パラメーター	データ型	説明
デバイス	文字列	ハードウェアステーションの要求に渡されるデバイス名は、ハードウェアステーションのデバイス拡張機能コントローラークラスに追加されるエクスポート属性と一致している必要があります。
アクション	文字列	ハードウェアステーション拡張機能で呼び出す必要があるメソッド。メソッド名は、文字列値として渡される必要があります。コア POS ハードウェアステーションの層レイヤーは、ハードウェアステーション拡張機能コードから対応するメソッドを呼び出します。このメソッドは、ハードウェアステーション拡張機能のメソッド名と完全に一致する必要があります。ハードウェアステーション拡張機能は、パラメータとして渡す必要があります。
actionData	any	拡張機能を渡すためのカスタムパラメーター。

サンプルコード

次のコードの例は､HardwareStationDeviceActionRequest オブジェクトを作成します。

let hardwareStationDeviceActionRequest: HardwareStationDeviceActionRequest<HardwareStationDeviceActionResponse> =
    new HardwareStationDeviceActionRequest("Export attribute in Hardware station controller class",
        "extension method name in Hardware station", "Custom parameters/you can also pass custom object");
return this.extensionContextRuntime.executeAsync(hardwareStationDeviceActionRequest);

HardwareStationDeviceActionResponse

次のコード例は、HardwareStationDeviceActionResponse の定義を示します。

class HardwareStationDeviceActionResponse extends Response {
    readonly response: any;
    constructor(response: any);
}

次の表では、パラメーターについて説明します。

パラメーター	データ型	説明
応答	any	ハードウェアステーションから POS に送信される要求。

エンドツーエンドフロー

次の図は、POS、ハードウェアステーション、およびハードウェアデバイス間のフローを示しています。

フロー図。

ハードウェアステーション拡張機能

新しいハードウェアデバイスを呼び出すには、ハードウェアステーションコードを実装する必要があります。そのコードからハードウェアデバイスを呼び出します。

Retail SDK バージョン10.0.11 以降の Hardware station 拡張機能を実装するには、次の手順を実行します。

Microsoft .NET Framework バージョン 4.6.1を使用して、新しい C# クラスライブラリプロジェクトを作成します。または、Retail SDK に含まれているサンプルのいずれかをテンプレートとして使用します。 (サンプルは ...\RetailSDK\SampleExtensions\HardwareStation\ で見つけることができます)。テンプレートとしてサンプルを使用することをお勧めします。
拡張機能プロジェクトで、NuGet パッケージマネージャーを使用して、Microsoft.Dynamics.Commerce.Hosting.Contracts パッケージを追加します。 NuGet パッケージは、RetailSDK\pkgs フォルダで見つけることができます。
IController インターフェイスを拡張する新しいコントローラクラスを追加します。
コントローラクラスをクライアントに公開するには、コントローラクラスに RoutePrefix 属性を追加します。
```
[RoutePrefix("ISVEXTENSIONDEVICE")]
```
ハードウェアデバイスを呼び出すためのカスタムロジックを実装するために、HttpPost 属性を持つメソッドをコントローラークラスに追加します。このメソッドは、POS HardwareStationDeviceActionRequest に対して 2 番目のパラメーター (アクションパラメーター) として渡されます。拡張機能メソッドから、この拡張機能では、印刷やキャッシュドロワー要求などの他の要求を呼び出すことができます。 Retail SDK から関連する NuGet パッケージのみを含めます。
```
[HttpPost]
public async Task<bool> IsReady(IEndpointContext context)
{
}
```
プロジェクトを構築します。

Retail SDK バージョン10.0.11 の Hardware station 拡張機能を実装するには、次の手順を実行します。

新しい C# クラスライブラリプロジェクトの作成
HardwareStationController と IHardwareStationController を拡張する新しいコントローラークラスを追加します。
コントローラークラスにエクスポート属性を追加します。 エクスポート属性は、すべて大文字で指定する必要があり、値をパラメーターとして POS 拡張機能から渡す必要があります。 POS HardwareStationDeviceActionRequest から渡されるデバイスパラメータは、この値と一致している必要があります。
ハードウェアデバイスを呼び出すためのカスタムロジックを実装するために、メソッドをコントローラクラスに追加します。このメソッドは、POS HardwareStationDeviceActionRequest に対して 2 番目のパラメーター (アクションパラメーター) として渡されます。
プロジェクトを構築します。

Modern POS にハードウェアステーション拡張機能を配置し、ローカルハードウェアステーションを使用してテストするには、次の手順を実行します。

出力ライブラリを C:\Program Files (x86)\Microsoft Dynamics 365\70\Retail Modern POS\ClientBroker\ext フォルダーにコピーします。
HardwareStation.Extension.config ファイルを開きます。
合成セクションで、拡張機能ライブラリの詳細を追加します。
```
<add source="assembly" value="your extension library name" />
```
ファイル保存します。
現在実行中の場合は、Modern POS を閉じます。
タスクマネージャーを開いて、dllhost.exe タスクを終了します。
Modern POS を開いて、ローカルハードウェアステーションを使用するように構成します。
シナリオを検証します。

Cloud POS を使用してテストするには、ハードウェアステーション拡張機能のダイナミクスリンクライブラリ (DLL) を、共有ハードウェアステーションの ext フォルダに配置します。次に、共有ハードウェアステーションフォルダのカスタムライブラリを使用して、HardwareStation.Extension.config ファイルを更新します。

Retail SDK サンプル

Retail SDK には、参照用に使用できるサンプルがいくつか含まれています。

POS: \RetailSDK\POS\Extensions\FiscalRegisterSample
ハードウェアステーション: \RetailSDK\SampleExtensions\HardwareStation\Extension.FiscalRegisterSample

Retail SDK バージョン 10.0.11 以降のサンプルコード

namespace Contoso
{
    namespace Commerce.HardwareStation.ISVExtensionDevice
    {
        using Microsoft.Dynamics.Commerce.Runtime.Hosting.Contracts;
        using System;
        using System.Threading.Tasks;

        /// <summary>;
        /// Sample hardware station extension
        /// </summary>

        [RoutePrefix("ISVEXTENSIONDEVICE")]
        public class ISVExtensionDeviceController : IController
        {
            /// <summary>
            /// Sample.
            /// </summary>

            /// <param name="request">Custom request.<param>
            /// <returns>Result of Custom response.</returns>

            [HttpPost]
            public async Task<CustomResponse> Sample(CustomRequest request, IEndpointContext context)
            {
                CustomResponse response;
                try
                {
                    response = new CustomResponse();
                }
                catch (Exception ex)
                {
                    throw ex;
                }
                return await Task.FromResult(response);
            }
        }
        public class CustomResponse
        {
            public string sampleProp { get; set; }
            public CustomResponse()
            {
                this.sampleProp = "sampleValue";
            }
        }
    }
}

ハードウェアステーション拡張機能を呼び出すためのサンプル POS コード

POS 拡張機能から、次のパターンを使用してハードウェアステーションを呼び出します。

let hardwareStationDeviceActionRequest: HardwareStationDeviceActionRequest<HardwareStationDeviceActionResponse> =
    new HardwareStationDeviceActionRequest("ISVEXTENSIONDEVICE",
        "Sample", "Custom parameters or custom object");
return this.extensionContextRuntime.executeAsync(hardwareStationDeviceActionRequest);

メモ

独立した POS 梱包 SDK またはシールド HWS インストーラーを使用していない場合は、配置可能パッケージの作成の手順に従って、配置用のパッケージを生成します。

ローカル HWS を使用するには、HWS 拡張機能を Modern POS にパッケージ化する

メモ

このセクションは、バージョン 10.0.22 以降の財務と運用アプリで POS 独立パッケージ SDK を使用している場合に適用できます。

ローカル HWS を使用するために HWS 拡張機能を Modern POS にパッケージ化するには、HWS 拡張機能を POS にパッケージ化する必要があります。 Modern POS JavaScript プロジェクトで、HWS プロジェクトへの参照を追加します。次に、POS インストーラープロジェクトを使用して拡張機能インストーラーを作成します。詳細については、Dynamics365Commerce.InStore/src/PosSample/ModernPos/ModernPos.jsproj GitHub リポジトリで、サンプル JavaScript プロジェクトを参照してください。

HWS 拡張機能しかない場合は、サンプルから他の不要なプロジェクト参照をすべて削除してください。 ModernPos.jsproj プロジェクトは、msix インストーラーを作成し、インストーラプロジェクトで消費して、exe インストーラーを作成します。 HWS 拡張機能は UWP アプリ拡張機能として配置されます。

ハードウェアステーションの拡張機能インストーラーの生成

Dynamics 365 Commerce 10.0.18 以降では、シールドインストーラーがサポートされます。拡張機能インストーラーは基本インストーラーとは別に生成できます。また、インストーラーは個別にインストールしてサービスを提供できます。この機能はシールドセルフサービスインストーラーを使用している場合にのみ機能します。

ハードウェアステーションのシールド拡張機能インストーラーを生成するには、次の手順に従います。

GitHub からサンプルハードウェアステーションインストーラープロジェクトをダウンロードして、Visual Studio で HardwareStation.Installer.csproj プロジェクトを開きます。
ハードウェアステーション拡張機能プロジェクトを、プロジェクト参照として HardwareStation.Installer.csproj インストーラープロジェクトに追加します。既存のサンプルのプロジェクト参照を HardwareStation.Installer.csproj プロジェクトから削除します。

インストーラープロジェクトは、Microsoft.Dynamics.Commerce.Sdk.Installers.HardwareStation パッケージを使用して拡張機能インストーラーを生成します。サンプルインストーラープロジェクトクラスでは ExtensionPackageInstallerSetup クラスが拡張され、インストール手順が実装されます。
インストーラー名を更新するには、サンプルコードの InstallerName 変数を設定します。
サンプルインストーラープロジェクトを更新して、インストール中に追加のロジックを実行できます。たとえば、サーバーに対して ping を実行できます。ロジックを追加するには、HardwareStation.Installer.csproj の HardwareStationExtensionPackageInstallerSetup.cs ファイルを使用します。
IExtensionInstallerStep インターフェイスを実装すると、インストーラーに前後の手順を追加することもできます。 TestExtensionInstallerPreInstallStep.cs ファイル、および HardwareStation.Installer.csproj サンプルインストーラープロジェクトの TestExtensionInstallerPostInstallStep.cs を使用して、ステップを追加します。
拡張機能 HardwareStation.Installer.csproj プロジェクトを構築して、共有ハードウェアステーション拡張機能インストーラーを生成します。プロジェクトの出力は、拡張機能インストーラーです。ビルドの完了後、生成された拡張機能インストーラーのパスが Visual Studio 出力ウィンドウに表示されます。
販売時点管理 (POS) 用の共有ハードウェアステーション拡張機能を配置し、シナリオでテストします。

メモ

拡張機能インストーラーを実行する前に、シールド共有ハードウェアサーバーインストーラーをインストールする必要があります。
コマンドプロンプトを使用して生成された拡張機能インストーラーを実行します。管理者モードでコマンドプロンプトを開き、install パラメーターを指定してインストーラーを実行します。アンインストールするには、uninstall パラメーターを使用して拡張機能インストーラーを実行します。例:
```
C:\HardwareStation.Installer\bin\Debug\net461> .\HardwareStation.Installer.exe install
```
現在実行中の場合は、POS を閉じます。
POS を開いて、共有ハードウェアステーションを使用するように構成します。
拡張機能ハードウェアステーションのシナリオを検証します。

POS を新しいハードウェア デバイスと統合し、拡張機能インストーラーを生成

Hardware Station の概要

Hardware Station 設定

Hardware Station アーキテクチャ

Hardware Station 拡張性シナリオ

HardwareStationDeviceActionRequest

サンプル コード

HardwareStationDeviceActionResponse

エンド ツー エンド フロー

ハードウェア ステーション拡張機能

Retail SDK サンプル

Retail SDK バージョン 10.0.11 以降のサンプル コード

ハードウェア ステーション拡張機能を呼び出すためのサンプル POS コード