プロダクションでの .NET ゲートウェイの使用

ビジネス・サービスの作成

コマンド・プロンプトから .NET ゲートウェイ・サーバを起動することもできますが、Ensemble プロダクションで .NET ゲートウェイを使用する最も簡単な方法は、プロダクションのビジネス・サービスとして EnsLib.DotNetGateway.ServiceOpens in a new tab クラスを構成する方法です。Ensemble を実行しているローカル・マシン上に .NET ゲートウェイ・サーバがある場合のみ、この方法を使用できます。

それ以外の場合は、コマンド・プロンプトから .NET ゲートウェイ・サーバを起動する必要があります。詳細は、"コマンド・プロンプトの使用法" を参照してください。

ビジネス・サービスとして EnsLib.DotNetGateway.ServiceOpens in a new tab クラスを構成するには、Ensemble, プロダクション ページの構成画面を使用します。以下の手順は、構成手順をまとめたものです。

1. 管理ポータルのメイン・メニューで [プロダクション] を選択します。

2. リストからプロダクションを検索し、名前の横にある [構成] をクリックします。

3. [サービスの追加] をクリックして、ビジネス・サービス・ウィザードを開始します。

4. [その他] をクリックして、[ServiceClass] リストの [EnsLib.DotNetGateway.Service] をクリックします。

5. [OK] をクリックして、更新されたプロダクションのダイアグラムを表示します。ダイアグラムには .NET ゲートウェイのビジネス・サービスが新たに追加されています。[EnsLib.DotNetGateway.Service] ボックスをクリックしてこのサービスを構成します。

このウィザードでは、関連する .NET ゲートウェイのアダプタ・クラスが指定されます。構成可能な設定は、".NET ゲートウェイのビジネス・サービス設定" を参照してください。

ビジネス・サービス・メソッドの呼び出し

.NET ゲートウェイ・ビジネス・サービスは、.NET ゲートウェイ・エンジンの開始、接続、停止に使用できるメソッドを提供します。.NET ゲートウェイ・ビジネス・サービスをプロダクションのメンバとして構成した後、以下のメソッドを Ensemble コードから呼び出すことができます。

• StartGateway()

• ConnectGateway()

• StopGateway()

これらのメソッドの詳細は、"Class Reference" で EnsLib.DotNetGateway.ServiceOpens in a new tab のエントリを参照してください。

StartGateway() メソッド

EnsLib.DotNetGateway.Service:StartGateway(pFilePath As %String,
     pPort As %String,
     pAllowedIPAddresses As %String,
     pLogfile As %String = "",
     ByRef pDevice As %String = "",
     pServer As %String = "127.0.0.1",
     pCmdLine As %String = "")

このクラス・メソッドは、指定された引数を使用して .NET ゲートウェイ・サーバを起動します。pLogFile に有効なファイル名を指定すると、ゲートウェイのアクティビティに関するメッセージがそのファイルに書き込まれます。このメッセージでは、サーバへの接続が開かれたことの通知、閉じられたことの通知、.NET クラスを Ensemble プロキシ・クラスにマッピングするときに生じた問題などを扱います。

ConnectGateway() メソッド

EnsLib.DotNetGateway.Service:ConnectGateway(pEndpoint As %String,
     ByRef pGateway As %Net.Remote.Gateway,
     pTimeout As %Integer = 5,
     pAdditionalPaths As %String = "")

このクラス・メソッドは、指定された pEndpoint (ホスト名:ポート:ネームスペース) の .NET ゲートウェイ・サーバに接続します。

StopGateway() メソッド

EnsLib.DotNetGateway.Service:StopGateway(pPort As %String,
     pServer As %String = "127.0.0.1",
     pTimeout As %Integer = 5)

このクラス・メソッドは、.NET ゲートウェイ・サーバに接続し、サーバをシャットダウンします。

ビジネス・オペレーションの作成

Ensemble プロダクション用に .NET ゲートウェイ指向のビジネス・オペレーションを構築するための基礎として、抽象ビジネス・オペレーションを使用できます。EnsLib.DotNetGateway.AbstractOperationOpens in a new tab 抽象クラスのサブクラスを定義し、適切なメッセージ・ハンドラを実装するだけでこの処理が可能です。

有効な .NET ゲートウェイ接続があるかどうかを確認するために、GetConnection() メソッドを呼び出します。以下に例を示します。

 Set tSC = ..GetConnection(.tGateway)
     If $$$ISOK(tSC) { 
        // Start using the .NET Gateway connection object tGateway 
      ... 
     }

このメソッドは、プロキシ・クラスで使用するプライベート・ゲートウェイ接続オブジェクトを返します。

.NET ゲートウェイの IP アドレスおよびポートは、プロダクションにビジネス・オペレーションを追加するときに、そのビジネス・オペレーションの設定で構成できます。.NET ゲートウェイのインスタンスへの接続は、OnInit() で開始し、OnTearDown() で終了します。ビジネス・オペレーション・クラスでこれらのメソッドをオーバーライドして、独自のセットアップおよびティアダウン手順を実装できます。

これらのメソッド、および AdditionalPaths、ConnectTimeout、 DotNetServer、Port の各プロパティの詳細は、"Class Reference" の EnsLib.DotNetGateway.AbstractOperationOpens in a new tab のエントリを参照してください。

API メソッドの呼び出し

ビジネス・サービスへの接続、ビジネス・サービスからの切断、および停止に加えて、%Net.Remote.GatewayOpens in a new tab クラスでは以下のメソッドも使用できます。ビジネス・サービス・モデルが不適切な状況の場合に、これらを使用できます。

%Net.Remote.GatewayOpens in a new tab クラスは、以下の種類のメソッドを提供します。

• .NET ゲートウェイ・サーバに接続する %Connect、.NET ゲートウェイ・サーバから切断する %Disconnect、および .NET ゲートウェイ・サーバをシャットダウンする %Shutdown の各 API メソッド。

• .NET から .NET クラスまたはアセンブリをインポートし、Ensemble 側に必要なすべてのプロキシ・クラスを生成する、%Import メソッド。

• %Connect、%Import、および %Disconnect　に対する呼び出しを組み合わせた %ExpressImport メソッド。

• ユーティリティ・メソッドの %GetAllClasses。

%Connect() メソッド

Method %Connect(host As %String,
                port As %Integer,
                namespace As %String,
                timeout As %Numeric = 5,
                additionalClassPaths As %ListOfDataTypes = "")
    As %Status [ Final ]

%Connect() メソッドは、.NET ゲートウェイ・エンジンとの接続を確立します。以下の引数を使用できます。

引数	説明
host	.NET ゲートウェイ・サーバを実行しているマシンを特定します。
port	プロキシ・クラスが .NET クラスと通信するポート番号。
namespace	Ensemble ネームスペース。
timeout	タイムアウトとなるまで待機する秒数。デフォルトは 5 です。
additionalClassPaths	オプション — 追加のクラス・パスを指定します。例えば、.NET ゲートウェイ経由でインポートするクラスを含む追加のアセンブリ DLL の名前を指定します。この引数の使用に関する詳細は、「%Import 引数」の節を参照してください。

%Disconnect() メソッド

Method %Disconnect() As %Status [ Final ]

%Disconnect() メソッドは、.NET ゲートウェイ・エンジンへの接続を閉じます。

%Shutdown() メソッド

Method %Shutdown() As %Status [ Final ]

%Shutdown() メソッドは、.NET ゲートウェイ・エンジンをシャットダウンします。

%Import() メソッド

Method %Import(class As %String,
               ByRef imported As %ListOfDataTypes,
               additionalClassPaths As %ListOfDataTypes = "",
               exclusions As %ListOfDataTypes = "")
    As %Status [ Final ]

%Import()　メソッドは、必要なすべてのプロキシ・クラスを作成およびコンパイルすることによって、指定されたクラスおよびそのすべての依存関係をインポートします。%Import() メソッドは、生成された Ensemble プロキシ・クラスのリストを imported で参照渡しで返します。.NET クラス定義がどのように Ensemble プロキシ・クラスにマッピングされるかについての詳細は、".NET 用 Caché ゲートウェイの使用法" の “マッピング仕様” の章を参照してください。

%Import() は、一回限りのスタートアップ・オペレーションです。初めて Ensemble プロキシ・クラスを生成する場合のみ、呼び出す必要があります。再度必要になるのは、.NET コードをリコンパイルし、プロキシを再生成する場合のみです。以下の節では、%Import() メソッドについて詳しく説明します。

• %Import 引数

• インポートの依存関係と除外

%Import 引数

%Import() を呼び出す前に、引数 additionalClassPaths および exclusions を用意します。つまり、引数ごとに新しい %ListOfDataTypesOpens in a new tab オブジェクトを作成し、その Insert() メソッドを呼び出してリストの内容を設定します。オプションの additionalClassPaths 引数を使用して追加のパス引数を指定できます。例えば、.NET ゲートウェイ経由でインポートするクラスを含む追加のアセンブリ DLL の名前を指定できます。リストの各要素は、追加アセンブリ DLL の個々のエントリに対応している必要があります。そのためには以下の形式にする必要があります。

" rootdir\...\mydll.dll "

DotNetGatewaySS.exe を実行していないディレクトリからでもアセンブリをロードできますが、そのアセンブリでクラスを使用しようとすると、アセンブリのロード・エラーが発生する可能性があります。DotNetGatewaySS.exe を配置したディレクトリにすべてのローカル・アセンブリを配置することをお勧めします。また、例えば System.Data のように、名前の一部を使用して、GAC 内のアセンブリを指定することもできます。

インポートの依存関係と除外

.NET クラスを Ensemble プロキシ・クラスにマッピングして Ensemble にインポートするときに、.NET ゲートウェイでは、プロパティとして参照されているクラスおよび引数リストで参照されているすべてのクラスを含め、指定した .NET クラス内で見つかったすべてのクラス依存関係がループ処理されます。言い換えると、.NET ゲートウェイは、指定されたクラスを正しくインポートするために必要なすべてのクラス依存関係のリストを収集し、その依存関係リストを調べて、必要なすべてのプロキシ・クラスを生成します。

このプロセスから除外するアセンブリおよびクラス名の接頭語のリストを指定することによって、このプロセスを制御できます。このような状況はまれですが、インポートするクラスを制御できる柔軟性があります。.NET ゲートウェイでは、Microsoft.* アセンブリのような、アセンブリの小さなサブセットが自動的に除外されます。

%ExpressImport() メソッド

ClassMethod %ExpressImport(name As %String,
                           port As %Integer,
                           host As %String = "127.0.0.1",
                           silent As %Boolean = 0,
                           additionalClassPaths As %ListOfDataTypes = "",
                           exclusions As %ListOfDataTypes = "")
    As %Status [ Final ]

%ExpressImport() は、%Connect()、%Import()、および %Disconnect() への呼び出しを組み合わせた、1 つの手順の便利なクラス・メソッドです。このメソッドは、生成されたプロキシのリストを返します。また、silent 引数を 0 に設定している場合は、そのリストがログに記録されます。name 引数は、クラス DLL またはアセンブリ DLL のセミコロン区切りリストです。

%GetAllClasses() メソッド

 %GetAllClasses(jarFileOrDirectoryName As %String,
                ByRef allClasses As %ListOfDataTypes)
     As %Status

このメソッドでは、最初の引数 jarFileOrDirectoryName で指定したアセンブリ DLL にあるすべてのパブリック・クラスのリストが ByRef 引数 allClasses に返されます。

コマンド・プロンプトの使用法

通常は、プロダクションのメンバとして EnsLib.DotNetGateway.ServiceOpens in a new tab ビジネス・サービスを構成することによって、.NET ゲートウェイ・サーバを自動的に起動および停止します。この構成を行うと、.NET ゲートウェイ・サーバはプロダクションと共に自動的に起動および停止します。クラス・メソッド StartGateway() を利用して、手動で .NET ゲートウェイ・サーバを起動することもできます。

ただし、開発時やデバッグ時、または Ensemble と .NET ゲートウェイ・サーバを別々のマシンで実行している場合は、コマンド・プロンプトからゲートウェイ・サーバを起動すると便利な場合があります。ファイル DotNetGatewaySS.exe を、アセンブリのロード先ディレクトリにコピーします。デフォルトでは、DotNetGatewaySS.exe はディレクトリ install-dir\dev\dotnet\bin に格納されています。以下のように、install-dir\dev\dotnet\bin から DotNetGatewaySS.exe を実行します。

DotNetGatewaySS portlistenerlogfile

以下に例を示します。

DotNetGatewaySS 55000 "" ./gatewaySS.log

.NET ゲートウェイ・ウィザードの使用法

スタジオに組み込まれた .NET ゲートウェイ・ウィザードを使用して、.NET から DLL アセンブリ・ファイルをインポートし、対応する一連のクラスを作成できます。ウィザードを開始するには、以下の手順を実行します。

1. スタジオを起動します。

2. [ツール] メニューで [アドイン] をクリックします。

3. [.NET ゲートウェイ・ウィザード] をクリックして、.NET ゲートウェイ・ウィザードのダイアログを開始します。

4. DLL アセンブリ・ファイルのパスとファイル名を入力するか、または [参照] をクリックして DLL アセンブリ・ファイルにナビゲートします。

5. .NET ゲートウェイ・サーバの [.NET ゲートウェイ・サーバ名 / IP アドレス] および [.NET ゲートウェイ・サーバ・ポート] を入力します。

6. ダイアログの指示に従って、[依存クラスの検出に使用する追加の paths\assemblies] および [以下の接頭語と一致する依存クラスを除外] も入力できます。

7. [次へ] をクリックして、Ensemble プロキシ・クラスを生成します。各プロキシ・クラスが生成されると、ウィザードにクラス名が表示されます。

8. インポート操作が完了したら、[終了] をクリックしてウィザードを終了します。

エラーのチェック

.NET ゲートウェイには、以下のようなエラー・チェック機能が用意されています。

• Ensemble プロキシ・メソッドの実行中にエラーが発生した場合、そのエラーの多くは、元の .NET メソッド自体または .NET ゲートウェイ・エンジンに起因する .NET の例外です。これが発生すると、エラーがトラップされます。

• %Import() や %Connect()　などの .NET ゲートウェイ API メソッドは、通常の Ensemble %StatusOpens in a new tab 変数を返します。

どちらの場合も、.NET クラスから返された最新のエラー値 (多くの場合、スローされた実際の .NET の例外) が、Ensemble ローカル変数 %objlasterror に記録されます。

以下のように、$system.OBJ.DisplayError() を呼び出すことによって、エラー・メッセージの完全なテキストを取得できます。

 Do $system.OBJ.DisplayError(%objlasterror)

トラブルシューティング

.NET ゲートウェイの使用中に問題が発生するような場合は、ログ機能を常に有効にしておくことをお勧めします。インターシステムズのスタッフが問題のトラブルシューティングを行うために、ログが必要な場合があります。ログ機能を有効にするには、.NET ゲートウェイの開始時にログ・ファイルを指定します。コマンドラインから開始する場合でも、StartGateway() API メソッドを使用する場合でも、指定できます。

デバッグやテストに .NET ゲートウェイを使用しているときに、ターミナル・セッションが使用できなくなるという問題やターミナル・ウィンドウでの書き込みエラーの問題が発生することがあります。原因として、適切な切断処理が行われずに、.NET ゲートウェイ接続が終了したことが考えられます。この場合、その接続に使用したポートが開いたままになっている可能性があります。

この状況になっていると考えられる場合は、ポートを閉じるために、ターミナル・プロンプトで以下のコマンドを入力します。

 Close "|TCP|port"

ここで port は、閉じるポートの番号です。