AGETOR Wiki: .NET Integration Reference Guide

Welcome (anonymous guest) My Prefs

Contents

Project Documentation

Contact

About

This document describes how to integrate AGETOR with .NET applications by using the AGETOR Application Integration.

Audience

This guide is intended for programmers with some experience with .NET and Microsoft Visual Studio. A basic understanding of AGETOR Application Integration is also useful.

Acknowledgments

The software described in this document includes software developed by the Apache Software Foundation

and the IKVM software

developed by Jeroen Frijters.

Introduction

The AGETOR .NET Integration enables .NET applications to communicate remotely with other applications through the AGETOR Application Integration protocol. The application code does not need to deal with the details of sending data back and forth as this is handled by AGETOR Application Integration platform and by code generated by the IDL2CS tool.

The AGETOR .NET Integration is a implemented as native .NET assemblies and does not have any other runtime requirements than the .NET framework.

To make it easier to develop AGETOR AI enabled .NET applications, AGETOR .NET Integration generates solutions for Microsoft Visual Studio 2008 that contain the required communication classes as well as generated test classes that can be used as a basis for further development.

Installation

This section gives you information on how to install the AGETOR .NET Integration.

The newest version of AGETOR .NET Integration and other AGETOR software are always available at the AGETOR download center

IDL development

For developing and testing IDL files you need to install the AGETOR Development Kit and the AGETOR .NET Integration.

When you have installed the AGETOR Development Kit download the newest version of the AGETOR .NET Integration and copy the package into your AGETOR_HOME/install/packages directory. If you are upgrading an existing installation the existing configuration will be retained.

Windows: Open a command window with AGETOR_HOME/bin/prompt.bat and run installer.bat
Unix/Linux: Open a shell which has the right AGETOR® environment (e.g., by using a project script) and type installer
After the AGETOR® InstallTool has started open an Internet browser and point to http://<hostname>:8020
If prompted for login and password, please type in your login and password.
Under "Product(s) ready to install" click on "AGETOR .NET Integration" and follow the directions

.NET application development

Once the IDL has been created and Visual Studio solution generated, it is not necessary to have a full AGETOR installation to develop AGETOR integrated .NET applications. For application development, only the AGETOR .NET Integration runtime is required. A runtime installer can be downloaded from the AGETOR download center

. The installer has the filename AGETOR.NETSetup.msi.

Run the installer on the development machine.

The program will install the AGETOR .NET Integration assemblies in these places:

Global Assembly Cache
<Program files>/AGETOR/.NET Integration

Runtime environment

For running AGETOR integrated .NET applications only the runtime assemblies are required. These are installed with the runtime installer as described in the previous paragraph.

Developing with AGETOR .NET Integration

This section describes how to develop an AGETOR integrated .NET application. The process involves these steps:

Creation of an IDL file
Generation of .NET files (classes, projects and solution)
Development of the .NET application

IDL files

The IDL file defines the communication interface between the server and the client. IDL files should be placed in the AGETOR_HOME/app/idl folder. See the links below for more information on IDL files.

C# type mapping rules

This section describes how IDL types and method parameters are mapped to C#.

Mappings for simple types

In method parameters (and struct members) are passed by value. Out and inout method parameters are passed by reference.

IDL type	C# type (in parameter or struct member)	C# type(out/inout parameter)
boolean	bool	ref bool
char	char	ref char
octet	byte	ref byte
string<length>	string	ref string
short	int	ref int
long	int	ref int
float	float	ref float
double	double	ref double
Date	DateTime	ref DateTime

Struct mapping

IDL structs are mapped to C# classes with the struct members implemented as properties. Since an object is modified through its properties it is not necessary to pass struct out and inout methods parameters by reference in C# as it is the case with the simple types.

Struct attributes

Structs are generated with these attributes to make them COM enabled:

ClassInterface(ClassInterfaceType.AutoDual)
ComVisible(true)

Sequence mapping

IDL sequences are mapped to the class BordingData.Agetor.Orblib.Sequence. This class implements System.Collections.IList and it is also COM enabled. Sequences, like structs, are always passed by value in methods.

Limitations

IDL2CS has these limitations:

Only a single interface per IDL module is supported
Structs used by an interface must be declared in the same module
Inclusion of files is not supported

IDL2CS

When an IDL file has been created the next step is to generate the corresponding .NET files. For this purpose the IDL2CS tool is used. To generate .NET classes, projects and solution, do the following:

Open an AGETOR prompt, AGETOR_HOME/bin/prompt.bat
Type idl2cs <IDL filename>. You may leave out the .idl extension
Locate the generated files in AGETOR_HOME/app/cs/<IDL module name>

The solution file will have the name AGETOR_HOME/app/cs/<IDL module name>/<interface name>.sln.

Generated files

Generated code

The IDL2CS tool generates these C# types for each IDL interface:

Service interface
Test client
Test server
Service stub (client-side service proxy)
Service skeleton (invokes service)
UserControl, including Designer class (primarily for use with Dynamics NAV)

IDL2CS also generates a class for each IDL struct.

Generated Visual Studio solution and projects

The IDL2CS tool generates these Visual Studio 2008 projects for an IDL interface:

Base project (<interface name>Base) containing
- Service interface
- Service stub
- Service skeleton
- UserControl
- Structs
Client project (<interface name>Client) containing
- Test client
Service project (<interface name>Service) containing
- Test server

Testing

Before starting development of the .NET application is may be useful to test the basic setup with the generated test clients. This is easy in the AGETOR installation used for generating files.

Broker configuration

The client and server usually communicate through the AGETOR Broker. Therefore, the test service is added to the broker configuration, AGETOR_HOME/conf/broker.cfg. Add this line in the <SERVICES> section:

<SERVICE NAME="myservice" RPORT="102"/>

This assumes that your AGETOR installation is using the default port range, 20000. Otherwise, you must change the port number in the server project (Project properties -> Debug -> Start Options -> Command line arguments).

Add this line in the <ENVIRONMENT> section:

<QUESTION NAME="myservice" QNO="5001"/>

Remember to replace the QNO with the actual question number from your IDL file. You may use any name for your service as long as you use the same name in both the service and question definitions.

There is more information on Broker setup in the AGETOR Runtime Environment Guide.

Running the generated test programs

When the AGETOR Broker has been set up, you are ready to run the generated test programs:

Open the Visual Studio solution
Right-click on the solution and select "Set Startup Projects..."
Select "Multiple startup projects"
Set the client and the server project to "Start" or "Start without debugging"
Press <F5> to launch the programs
Press <enter> in the client window when the service has finished starting up (the test client will wait for input to allow the service to complete its startup)
The client should now invoke the service and both programs should output test messages

Creating applications

Creating a .NET client

To invoke an AGETOR service from a .NET client you need to obtain a reference to the remote service. This is acquired with the help of an ORB:

// Service host
string host = "localhost";

// AGETOR Broker port
int port = 20002;

// Create ORB to connect to service through the AGETOR Broker
ORB orb = new InternalORB(host, port);

// Get a reference to the remote service by giving the interface name as parameter
TestTypes service = (TestTypes)orb.getService("test.simple.service.TestTypes");

// Invoke method on the remote service
DateTime serviceDate = service.getDate();

Creating a .NET service

For a service you need an ORB that listens for incoming requests. We recommend using the multi-threaded ORB, dk.bording.inside.orb.ServerORB. In this example the main method creates the ORB and starts it up:

// The ORB instance
ServerORB orb;

public static void Main(String[] args)
{
	// Service instance
	TestTypesMTServer service = new TestTypesMTServer();
	
	try
	{
		// Create the ORB
		service.orb = ServerORB.makeServerORB(args);
		
		// Bind the ORB to the service so that method invocations are handled by the service
		service.orb.bind(service);
		
		// Let the service handle callback events (stop, start, info etc.)
		service.orb.setCallback(service);
		
		// Start the ORB to make it listen for incoming requests
		service.orb.run();
	}
	catch (RemoteException e)
	{
		e.printStackTrace();
	}
}

The service must implement the IDL interface to be able to handle the method invocations from the ServerORB. Usually you should also let the service class extend dk.bording.inside.orb.ServerORBEvents so it can handle callback methods.

Project attribute

The IKVM.Attributes.NoPackagePrefixAttribute attribute must be defined at assembly scope for projects using AGETOR .NET Integration:

[assembly: IKVM.Attributes.NoPackagePrefixAttribute]

Making Java environment variables available for AGETOR .NET Integration applications

Environment variables that are defined with the -D<name>=<value> syntax for a Java application can be made available for a stand-alone AGETOR .NET Integration executable by defining them in an app.config

file. The name of the variable must be prefixed

with ikvm:. The name of the file must be <exe name>.config, e.g., test.exe.config and it must be located in the same folder as the executable.

Example file:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
	<appSettings>
		<add key="ikvm:AGETOR_IPORT" value="20002" />
		<add key="ikvm:AGETOR_BROKER" value="localhost" />
		<add key="ikvm:AGETOR_ENV" value="agetor" />
	</appSettings>
</configuration>

You can then access AGETOR properties through the InsideProperties class, e.g.:

Parameters props = dk.bording.inside.InsideProperties.getInstance();
string host = props.getString("INSIDE_BROKER");
int port = props.getInt("INSIDE_IPORT");

Programming tips

Strong signing

In some environments (for example Microsoft IIS) you may need to sign the DLL from the base project with a strong name to be able to run the .NET Integration. This is due to security restrictions in those environments and you may get error messages that states that access to the base assembly has been denied.

There is more information on strong-name assemblies on MSDN's site.

VBScript

Variant parameters

If you invoke a method with a variant parameter of a type declared that is defined in an IDL, you must enclose the variant with an extra parenthesis in certain cases, e.g.:

Dim myObject
Set myObject = CreateObject("dk.bording.idl.test.MyObject")

service.getSomeValue "1000", "K50195", (myObject)

Notice the parentheses around myObject in the last line. For more information, see this discussion.

Content