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

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

Hardware Station の概要

最新の POS とクラウド POS では、ハードウェアステーションを使用して、プリンター、キャッシュドロワー、スキャナー、支払いターミナルなどのハードウェア周辺機器に接続します。

ローカルハードウェアステーションアーキテクチャの図。

共有ハードウェアステーションアーキテクチャの図。

Hardware Station 設定

開始する前に、「リテールハードウェアステーションの構成とインストール」の情報を使用して、ハードウェアステーションをインストールします。この記事は、ハードウェアの内容とインストール方法を理解するのにも役立ちます。

Hardware Station アーキテクチャ

ハードウェアステーションは、ハードウェアステーションアプリケーションプログラミングインターフェイス (API) 用の Web API を公開します。ハードウェアステーションを拡張するには、新しいデバイスの新しいコントローラー (キャッシュディスペンサーなど) を実装するか、既存のデバイスの種類 (たとえば、新しい Audio Jack 磁気ストライプリーダー (MSR) 実装) の既存のコントローラーをオーバーライドします。

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

Hardware Station 拡張性シナリオ

.NET でサポートされている 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	いずれか	拡張機能を渡すためのカスタムパラメーター。

サンプルコード

次のコードの例は､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);
}

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

パラメーター	データタイプ	内容
応答	いずれか	ハードウェアステーション拡張コードが POS に送信する応答。

エンドツーエンドフロー

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

POS、ハードウェアステーション、ハードウェアデバイス間のエンドツーエンドフローの図。

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

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

Retail SDK バージョン 10.0.11 以降のハードウェアステーション拡張機能を実装するには、次の手順に従います。

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 属性を持つメソッドをコントローラークラスに追加します。このメソッドを 2 番目のパラメーター (アクションパラメーター) として POS HardwareStationDeviceActionRequest に渡します。拡張機能メソッドから、この拡張機能では、印刷やキャッシュドロワー要求などの他の要求を呼び出すことができます。 Retail SDK から関連する NuGet パッケージのみを含めます。
```
[HttpPost]
public async Task<bool> IsReady(IEndpointContext context)
{
}
```
プロジェクトを構築します。

バージョン 10.0.11 より前の Retail SDK バージョンのハードウェアステーション拡張機能を実装するには、次の手順に従います。

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

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 を開いて、共有ハードウェアステーションを使用するように構成します。
拡張機能ハードウェアステーションのシナリオを検証します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-02-19

次の方法で共有

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

Hardware Station の概要

Hardware Station 設定

Hardware Station アーキテクチャ

Hardware Station 拡張性シナリオ

HardwareStationDeviceActionRequest

サンプル コード

HardwareStationDeviceActionResponse

エンド ツー エンド フロー

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