Using your Synergy .NET assembly: The basics

We have included examples in both C# and—where there is a sufficient difference in the code—in VB. If you are using pooling, also refer to Writing code that uses pooled objects.

1.

Reference the Synergy assembly in your Visual Studio project

Before using the assembly, you’ll need to add a reference to it in your Visual Studio project. After you’ve referenced the assembly, you can view its methods using Visual Studio’s Object Browser. You’ll see your own methods, along with the xfNetLink .NET utility methods.

If any of your methods pass structures as parameters, you must also add a reference to xfnlnet.dll in your project.

If you are using pooling, you must also add a reference to System.EnterpriseServices in your project. The xfNetLink .NET classes use this namespace.

2.

Designate the namespace(s) you are using

In your C# code, include the using keyword, followed by the namespace(s) of your assemblies, so that you can more easily access the classes in your assembly. For example:

using ABCComputers.ConsultPro;

If you are using VB, use the Imports keyword to designate the namespace(s) you will be using. For example:

Imports ABCComputers.ConsultPro

3.

Instantiate an instance of the procedural class

Your Synergy .NET classes can be instantiated using the standard mechanism for the language you are using. The examples below show how to instantiate an AppLogin() object named “userSess”.

For example, in C#:

AppLogin userSess = new AppLogin();

For example, in VB:

Dim userSess As New AppLogin()

4.

Connect to xfServerPlus

When you make a connection to xfServerPlus, the xfServerPlus process creates a dbs (or dbr if XFPL_DBR is set). Once created, this dbs continues to run and process requests from the client until the connection is closed, and then the dbs is closed by the xfServerPlus process.

There are several ways to establish a connection with xfServerPlus.

• Use connect(). This is the recommended method. It enables you to make several calls using the same connection before disconnecting. The advantages to using connect() are improved performance; the ability to maintain state between calls; and the option to share the connection with other objects (see next bullet). For example, in C#:

userSess.connect();

• Share a connection. Two or more objects can share a connection. This method improves performance because several objects are sharing the same xfServerPlus session rather than each object making its own connection. To share a connection, you must first establish it with connect(), and then use the getConnect() and shareConnect() methods.

In the examples below, we instantiate two new procedural classes and use the connect() method to establish a connection for one of them. We then instantiate the aConnection object to hold the connection and use the getConnect() method of the userSess object to get it. Finally, we call the shareConnect() method of the userRoutines object and pass the aConnection object. You can pass the same aConnection object multiple times to share the connection among several objects.

In C#:

AppLogin userSess = new AppLogin();
Consultant userRoutines = new Consultant();
userSess.connect();
object aConnection = null;
aConnection = userSess.getConnect();
userRoutines.shareConnect(aConnection);

In VB:

Dim userSess As New AppLogin()
Dim userRoutines As New Consultant()
userSess.connect()
Dim aConnection As Object
aConnection = userSess.getConnect()
userRoutines.shareConnect(aConnection)

• Create the connection automatically. When you make a call using one of the Synergy methods in your assembly, the connection is created automatically and then disconnected when the call is complete. This is the easiest way to connect because it makes access to xfServerPlus completely transparent. However, this method does not allow you to maintain state between calls. In addition, it requires more overhead because a connection is opened and closed for each call. If you use this method and experience performance problems, you may want to use an explicit connect() instead.

In the examples below, the userRoutines object is instantiated, and then the postCharge() method is called, without first calling the connect() method.

In C#:

Consultant userRoutines = new Consultant();
userRoutines.postCharge(charge, return_msg);

In VB:

Dim userRoutines As New Consultant()
userRoutines.postCharge(charge, return_msg)

5.

Invoke methods in the component

Make calls to your Synergy methods and pass the necessary parameters. If you generated API documentation for your assembly, it will include the information necessary to use the methods, such as the parameter data types. In addition, Visual Studio’s IntelliSense® will show you the method signature as you code.

Parameters that were not flagged as required in the SMC were converted to required parameters when you generated the C# classes because you must always pass all parameters in .NET.

The examples below show how to invoke the login() method in the userSess object.

In C#:

string userID = "MFranklin";
string password = "abc123";
userSess.login(userID, password);

In VB:

Dim userID As New String("MFranklin")
Dim password As New String("abc123")
userSess.login(userID, password)

6.

Disconnect from xfServerPlus

If you connected to xfServerPlus using the connect() method, you must disconnect using the disconnect() method. If you have multiple objects sharing a connection, xfServerPlus will not completely close the connection and release the license until all objects are disconnected. Although an explicit disconnect is not required when you use an automatic connection, you may want to call disconnect() before exiting your application to ensure the connection is correctly disposed of.

For example, in C#:

userSess.disconnect();