Open Menu

Synergex Blog

Exposing WCF Services using Synergy .NET

By Steve Ives, Posted on September 8, 2011 at 12:54 pm

In this post I will explain how you can use Synergy .NET to expose a WCF service. I’ll be showing you how to create WCF service and data contracts totally from scratch, using Synergy .NET. We’ll be defining new classes, not working with existing routines and records. That’s not to say that you can’t work with existing routines and records, in fact you may well chose to do so WITHIN a service that you create, but the focus of this post is on writing new code for the future.

This is the sixth in a series of posts relating to the various ways in which Synergy developers can use of Windows Communication Foundation (WCF) when building their applications. The posts in the series are:

  1. Building Distributed Apps with Synergy/DE and WCF
  2. Exposing WCF Services using xfNetLink .NET
  3. Hosting WCF Services in an ASP.NET Web Application
  4. Exposing WCF services using Synergy .NET Interop
  5. Self-Hosting WCF Services
  6. Exposing WCF services using Synergy .NET (this post)


In earlier posts I demonstrated how it was possible to expose WCF services using existing source code, either by transforming an xfNetLink .NET assembly into a WCF service, or by adding the traditional Synergy subroutines and functions that existed “underneath” an xfNetLink .NET assembly to a new Synergy .NET Interop project. There are valid use cases for both of these strategies, depending on what you’re starting with, however there are also some disadvantages to both approaches.

Perhaps the most significant disadvantage is that the external interface of the WCF service contracts that get exposed are defined by the parameters and return values of one or more traditional Synergy routines. And the data contracts are defined by Synergy record layouts defined in a repository. Also the actual WCF contracts that are exposed are under the control of the code generators that create the contracts, either GENCS, or the logic within the Interop project. This means that as a developer you’re kind of stuck with the defaults that those tools provide.

WCF has diverse capabilities which are defined and controlled through a large number of code and configuration options, and many of these are controlled via in-code attributes which are applied to the service and data contracts that make up a service. But when you work with services that are generated for you you don’t get to determine what options are used. So in some cases you might find that working with generated services is a little too restrictive.

This post will show how to create your own WCF services from scratch, in a way that makes all of the capabilities of WCF available to you.

The WCF Service Library Template

Although it has been possible to create WCF services with Synergy .NET since the product was introduced in version 9.5.1, the process became a lot easier in 9.5.1a. This was because we added a new project template called WCF Service Library. To create a new WCF service we simply start Visual Studio and create a new project based on the WCF Service Library template:


When you use the project template you create a new class library which is pre-configured appropriately for the development of WCF service and data contract classes.

imageOver and above a regular class library, a WCF Service Library development project will include:

  • References to the following .NET Framework assembles
    • System.Core
    • System.Runtime.Serialization
    • System.ServiceModel
    • System.Xml
  • An example of how to define WCF service and data contracts.
    • IService1.dbl
  • An example of how to implement the service defined by a service contract.
    • Service1.dbl


Before we go too much further let me make it clear that I don’t particularly like the example code that is provided by the project template, despite being the one who actually provided it for the distribution! But there is a good reason why the example code is the way that it is. That reason is that the example implements in Synergy the the exact same example that Microsoft provide when you create a new WCF Service Library using either C# or Visual Basic.

Service Contracts

So what do we have in the example? Most developers agree that it is good practice to separate the definition of a service contract from the actual implementation of the contract, and for service contracts this is achieved using an interface. In the example file called IService1.dbl you will find code like this:

WCF Service Contract
  1. import System
  2. import System.Collections.Generic
  3. import System.Runtime.Serialization
  4. import System.ServiceModel
  5. import System.Text
  7. namespace MyWcfServices
  9.     {ServiceContract}
  10.     public interface IService1
  12.         {OperationContract}
  13.         method GetData, string
  14.             required in val, int
  15.         endmethod
  17.         {OperationContract}
  18.         method GetDataUsingDataContract, @CompositeType
  19.             composite, @CompositeType
  20.         endmethod
  22.         ;;TODO: Add your service operations here
  24.     endinterface
  26. endnamespace


The example defines a WCF service in a class named Service1 and therefore, following accepted best practices, the name of the interface that defines the external view of the class is prefixed with a capital I. You will notice that the {ServiceContract} attribute is applied to the interface, which essentially means that any class which implements the interface will expose a WCF service contract.

Within the interface you will see that the example code defined two methods, named GetData and GetDataUsingDataContract. Both of these methods have the {OperationContract} attribute applied, which means that the methods will be exposed as operations of the WCF service … or in other words they are methods that a remote client accessing the service may call.

The GetData method accepts a single parameter which is an integer number, and has a return type of string.

The GetDataUsingDataContract method on the other hand has a single single parameter which is an object of type “CompositeType” and also returns an object of the same type. CompositeType is a class representing a complex data type (think OO version of a record) and is defined a little further down in the code:

By the way, you will notice that the methods that are described in the interface do not have accessibility specified. This is because by convention, all members of an interface are considered public. You will also notice that there is no procedure division specified … there is no PROC statement. This is because the role of an interface is simply to DEFINE requirements for a class, or rather for the external interface of a class. Interfaces do not include any logic … that will be added in a class which IMPLEMENTS the interface.

Data Contracts

Data contracts define complex data types (data classes) that can be passed from a client to a service or returned from a service back to a client, and are simply defined via a class with public properties of the appropriate types.

In the example the class named CompositeType has two public properties, one of type boolean named BoolValue, and one of type string named StringValue. As is often the case, the value of the public properties is propagated within the class by storing the actual value of the property in private variables, in this case the mBoolValue and mStringValue fields.

WCF Data Contract
  1. import System
  2. import System.Collections.Generic
  3. import System.Runtime.Serialization
  4. import System.ServiceModel
  5. import System.Text
  7. namespace MyWcfServices
  9.     ;;Use a data contract as illustrated in the sample below to
  10.     ;;add composite types to service operations
  11.     {DataContract}
  12.     public class CompositeType
  14.         private mBoolValue, Boolean, true
  15.         private mStringValue, String, "Hello "
  17.         {DataMember}
  18.         public property BoolValue, Boolean
  19.             method get
  20.             proc
  21.                 mreturn mBoolValue
  22.             endmethod
  23.             method set
  24.             proc
  25.                 mBoolValue = value
  26.             endmethod
  27.         endproperty
  29.         {DataMember}
  30.         public property StringValue, String
  31.             method get
  32.             proc
  33.                 mreturn mStringValue
  34.             endmethod
  35.             method set
  36.             proc
  37.                 mStringValue = value
  38.             endmethod
  39.         endproperty
  41.     endclass        
  43. endnamespace


What makes the CompositeType class a WCF data contract is the presence of the {DataContract} attribute immediately before the class declaration, and the {DataMember} attributes immediately before the declaration of each of the public properties. The {DataContract} attribute is used to ensure that it is possible to serialize an instance of the class for transmission over the wire between a client and a server, and the {DataMember} attributes define which members of the class will be included in that serialization, or in simpler terms, which members will be visible to client applications.

It should be noted that, despite being the case in the simple example provided by the project template, it is somewhat unusual to define multiple types within a single source file as is the case here. In a real application it is likely that each interface would be defined in its own source file, as would each data class. There is nothing technically wrong with the approach used in the example, and it does keep the definition of all of the contracts for a service together in one place, but you don’t have to do it that way.

Implementing a WCF Service

So in the simple example provided by the WCF Service Library project template we have looked at the definition of the service and data contracts for Service1 in the source file IService1.dbl. Now it’s time to look at the code that actually implements the service itself. That code is found in Service1.dbl.

WCF Service Implementation
  1. import System
  2. import System.Collections.Generic
  3. import System.Runtime.Serialization
  4. import System.ServiceModel
  5. import System.Text
  7. namespace MyWcfServices
  9.     public class Service1 implements IService1
  11.         public method GetData, String
  12.             required in val, int
  13.             endparams
  14.         proc
  15.             mreturn String.Format("You entered: {0}", val)
  16.         endmethod
  18.         public method GetDataUsingDataContract, @CompositeType
  19.             composite, @CompositeType
  20.             endparams
  21.         proc
  23.             if (composite==^null)
  24.                 throw new ArgumentNullException("composite")
  26.             if (composite.BoolValue)
  27.                 composite.StringValue = composite.StringValue + "Suffix"
  29.             mreturn composite
  31.         endmethod
  33.     endclass
  35. endnamespace


The code above is the code that implements Service1. You will notice that this is achieved by writing a class which implements the interface that describes the service contract that we talked about earlier.

Writing a class which implements an interface is simply a matter of ensuring that the class includes at least the members that are described by the interface … in this case the GetData and GetDataUsingDataContract methods. The class may also include other members not described in the interface, but MUST at least contain the members described by the interface.

You will also notice that both of the methods required by the interface are declared with PUBLIC accessibility. As mentioned earlier this is a requirement when implementing an interface. When we implement an interface we include the code that each method in the interface will execute, so here is where the actual functionality of the service is defined.

In the example code the GetData method simply takes the integer value that was received from the client and uses that value in a string which is returned to the client. So if a client application connects to an instance of this service and calls the GetData method passing a value of 5, the return value of the method call will be the string You Entered: 5.

The GetDataUsingDataContract method checks to ensure that an instance of the CompositeType class was received, than if the objects BoolValue property is set to true it appends the string Suffix to whatever is the current value of the objects StringValue property. The object is then returned via the method return value. Yea, I know, the dev at Microsoft must have been smoking something pretty questionable when they wrote this example. Something more meaningful would have been nice, but it is what it is!

Writing a WCF Service

So, there you have it. Writing a WCF service in Synergy .NET is pretty straight forward. You basically need to:

  1. Create a new assembly using the WCF Service Library project template.
  2. Define the external interface of your service via an interface that describes the service and operation contracts, and any data classes that may be required to define the data contracts that you need.
  3. Create a class which implements the service contract and includes the necessary functionality.

And remember we’re working in Synergy .NET here, so we have the full power of Synergy at out fingertips. If we need to access Synergy data that’s local to where the service will be hosted then we can go ahead and access that data directly, but if the data is remote then we can use xfServer to get to it – regardless of the system it resides on. We could also use an xfNetLink .NET assembly to allow us to get back into our traditional Synergy business logic, for all or part of the logic for the service. And of course we still have access to the SQL Connection API in order to access any relational databases that we may need to use. Of course we could also use other mechanisms in the .NET Framework to access a wide variety of data sources too.

Hosting the Service

If you’ve read the earlier posts in this series then you will already know that creating a WCF service is only part of the story, it also needs to be hosted somewhere. This has already been discussed in two earlier posts, so I don’t intend to repeat the information here.

Self-Hosting WCF Services

By Steve Ives, Posted on September 2, 2011 at 4:17 pm

Having defined a WCF service in code, and built that code into an assembly, a runtime instance of the service must be “hosted” somewhere in order for other application to be able to connect to and interact with the service. There are several ways to host WCF services. In an earlier post I described how to Host a WCF Service in an ASP.NET Web Application, which is a commonly used approach. But in some situations, for example if the only requirement for an IIS web server is to host a WCF service, it is preferable to host a service in a different way. In this post I will describe how to do just that, by leveraging capabilities of the .NET Framework which allow WCF services to be “self hosted”.

This is the fifth in a series of posts relating to the various ways in which Synergy developers can use of Windows Communication Foundation (WCF) when building their applications. The posts in the series are:

  1. Building Distributed Apps with Synergy/DE and WCF
  2. Exposing WCF Services using xfNetLink .NET
  3. Hosting WCF Services in an ASP.NET Web Application
  4. Exposing WCF services using Synergy .NET Interop
  5. Self-Hosting WCF Services (this post)
  6. Exposing WCF services using Synergy .NET

What is Self Hosting?

As its name suggests, self hosting a WCF service refers to the ability to host a WCF service within another application that you write, rather than hosting the service in a container such as that provided by Internet Information Services (IIS), or Windows Process Activation Services (WAS).

The .NET Framework provides various classes that can be used to host WCF Services within the context of a .NET application. This could be any type of .NET application, including console applications and desktop applications. However, in most cases WCF services need to be continually available, and it is often not convenient to host a service in a console or desktop application, because those applications typically execute in the context of a logged in user session.

A Windows Service application on the other hand can provide an excellent mechanism for hosting a WCF service. Windows Services are generally designed to automatically start when a system boots, stopped when the system is closed down, be continually available while the system is running, and are not associated with the desktop of any logged in user.

Since 9.5.1a Synergy .NET has included a project template which makes creating a Windows Service very easy, and as you are about to see, adding the code necessary to instantiate and host a WCF service is relatively straight forward.

Creating a WCF Service

In this post I’m assuming that you have already created a WCF service that you wish to host. If you have read the earlier posts in this series you will already know of two ways to create a WCF service, and in a later post I’ll show you another way.

Creating a Windows Service

Using Synergy .NET it is very easy to create a Windows Service. We provide a project template called “Windows Service”, and when you create a new project from the template you essentially have all of the code that you need to implement the service. Of course, apart from starting and stopping a service the default code that you get from the template doesn’t actually do anything … that’s where you come in!

You’ll need a Windows development system with the following products installed

  • Visual Studio 2010 Professional (or higher / later)
  • Synergy/DE 9.5.1a (or later)
  • Synergy Language Integration for Visual Studio 9.5.1a (or later)


Follow these steps to create a new Windows Service:

  • Start Visual Studio
  • From the menu, select File > New > Project.
  • From the installed templates list, select Synergy/DE.
  • From the project templates list select Windows Service.
  • Provide a name for the project and set its location.
  • Click the OK button to create the new project.



As you can see, in my example I have named my service MyWcfHostService and have created the project below my c:temp folder.

imageOnce the Windows Service project has been created, if you look in Solution Explorer you should see something like this:

You will notice that three source files were added to the project. In my example the file MyWcfHostService.dbl contains the code for the service itself, MyWcfHostServiceInstaller.dbl contains code used when the service is registered (installed), and Program.dbl is simply the main-line program that actually launches the service when the process starts.

Take a look at the main service source file (the one that ends …Service.dbl) and you will see that the code is relatively self explanatory. The class defined in the source file extends a parent class called ServiceBase. This means that our class has inherited a lot of functionality which essentially makes it a Windows Service.

You’ll also see that the class has a constructor method with the same name as the class itself, and the constructor calls a method called InitializeComponent, which sets various properties in order to configure various capabilities of the service.

private method InitializeComponent, void
    this.ServiceName = "MyWcfHostService"
    this.AutoLog = true
    this.CanPauseAndContinue = false
    this.CanHandlePowerEvent = false
    this.CanShutdown = false
    this.CanStop = true

All Windows services have the ability to be started, and as you can likely derive from the code, by default a new service has the ability to be stopped, but not to be paused and continued, or to respond to changes in the systems power state (mains vs. battery).

So, our new service can start, and it can be stopped. All we need to do is define what code should be executed when the service starts, and when the service stops. And if you scroll down a little you will notice that the code already contains place-holder event handlers where we can add whatever code we need:

protected override method OnStart, void
    byval args, [#]String
    ;;TODO: Add code to execute when the service is instructed to start
protected override method OnStop, void
    ;;TODO: Add code to execute when the service is instructed to stop

Our task is relatively straight forward. All we need to do is add whatever code is necessary to create and expose an instance of a WCF service in the OnStart method, and to stop the service in the OnStop method.

Referencing a WCF Service

The WCF service that we will be hosting has already been created in a separate assembly, so to get access to it we need to add a reference to that assembly in our Windows Service project.

  • In Solution Explorer, right-click on the References folder and from the context menu select Add Reference.
  • Wait for the Add Reference dialog to be displayed and load it’s data, which usually takes a few seconds.
  • Click on the Browse tab, then browse to the location of the assembly that contains your WCF service.
    • If your WCF service is defined in an xfNetLink .NET assembly then this is whatever folder you created the assembly in.
    • If your WCF service is defined in a Synergy .NET Interop project, or some other Visual Studio project, then you will generally find the assembly below that projects “bin” folder.
  • Select the assembly and click the OK button to add the reference to the assembly containing the WCF service.

Additional Steps for xfNetLink .NET WCF Services Only

If your WCF service is defined in an xfNetLink .NET assembly then there are two additional steps that you will need to complete.

Add a reference to xfNetLink .NET

Because your WCF service is defined in an xfNetLink .NET assembly, that assembly will require that your project also has a reference to the xfNetLink .NET assembly.

  • In Solution Explorer, right-click on the References folder and from the context menu select Add Reference.
  • Wait for the Add Reference dialog to be displayed and load it’s data, which usually takes a few seconds.
  • Click on the Browse tab, then browse to the location of the xfNetLink .NET assembly (xfnlnet.dll).
    • The assembly will normally be found under your Program FilesSynergexxfNLNet folder.
  • Select the assembly and click the OK button to add the reference.

Supply xfNetLink .NET Connection Information

Because your WCF service uses xfNetLink (to connect to xfServerPlus in order to execute your Synergy methods), you must tell xfNetLink where the instance of xfServerPlus is listening (host name or IP address, and port number). The best way to do this is via an application configuration (app.config) file.

  • In Solution Explorer, right click on your Windows Service project and from the context menu, select Add > New Item.
  • Select Application Configuration File and click the Add button.

Having added the configuration file to the project you need to specify the required configuration information, something like this:

<?xml version="1.0" encoding="utf-8"?>
    <sectionGroup name="xfnlnet">
      <section name="default" type="System.Configuration.NameValueSectionHandler, System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
      <add key="host" value="" />
      <add key="port" value="2356" />

Note: You can also use the Synergy .NET Configuration Utility to add this information to the file. Clearly you should replace the IP address and port number with the correct values for your own instance of xfServerPlus.

Hosting an Instance of the WCF Service

In the most basic form, self-hosting a WCF service in another application essentially turns that application into a web server. The web server capabilities are provided by a class in the .NET Framework called ServiceHost. This class is found in a namespace called System.ServiceModel, and is provided the System.ServiceModel.dll assembly.

The code that we’ll be adding will use these web server capabilities to expose a “WCF Endpoint” at a specified HTTP address.

In addition to exposing an endpoint which is an instance of your WCF service, you will usually also want to expose a second “metadata endpoint”. This allows other applications that may need to interact with your WCF service to download the metadata for your service. The metadata fully describes the service and its capabilities, and is made available automatically by WCF. Clients applications can use a standard protocol called Metadata Exchange (often referred to as MEX) in order to download a WCF services metadata from a metadata endpoint. In code, we use a second class called ServiceMetaDataBehavior to expose our services metadata. This class is in the System.ServiceModel.Description namespace, and is also in the System.ServiceModel.dll assembly.

If all of this is starting to sound really complicated, well it is! Luckily the .NET Framework hides most of these requirements from us, and does most of the work. Despite sounding really complicated, the code that we need to write is remarkably simple.

To self host a WCF service there are generally three main things you will need:

  • The URI for the endpoint for the service.
  • An instance of the ServiceHost class to expose your service at that URI
  • An instance of the ServiceMetaDataBehavior class to expose a metadata (MEX) endpoint.


So, lets write this thing:

  • Use the Add Reference dialog that you used earlier to add a reference to the Frameworks System.ServiceModel assembly.
  • At the top of the code in your …Service.dbl file, add the following two import statements:
import System.ServiceModel
import System.ServiceModel.Description
  • Somewhere inside the class, but NOT inside any method, add the following data declarations:
private baseAddress ,String
private host        ,@ServiceHost
private smb         ,@ServiceMetadataBehavior

In the procedure division of the OnStart method, add code like this:

protected override method OnStart, void
    byval args, [#]String
    ;;Define the URI for the service endpoint
    baseAddress = "http://" + Environment.MachineName + ":8080"

    ;;Create a ServiceHost instance for the WCF service
    host = new ServiceHost(
    &       ^typeof(spc2011.SynergyServer),
    &       new Uri(baseAddress))

    ;;Add a BasicHttp endpoint
    &       ^typeof(spc2011.ISynergyServer),
    &       new BasicHttpBinding(),
    &       "SynergyServer")

    ;;Create a ServiceMetaDataBehavior instance
    smb = new ServiceMetadataBehavior()
    smb.HttpGetEnabled = true
    smb.MetadataExporter.PolicyVersion = PolicyVersion.Policy15

    ;;Add a MEX endpoint

    ;;Start the listener


In my example, the namespace in which my WCF service is defined is “spc2011” and the name of the WCF service class is “SynergyServer”. You would need to:

  • Replace the reference to spc2011.SynergyServer with the namespace and class of your WCF service.
  • Replace the reference to spc2011.ISynergyServer with the namespace and interface of your WCF service.

IMPORTANT: When GENCS –W is used to create a WCF service, it applies the ServiceContract attribute to the CLASS that is created, rather than to the INTERFACE. So for xfNetLink .NET WCF services both of the above references should point to the CLASS.

Other than that, the code should work for any WCF service.

Now all that remains it to add the code to stop the WCF service when the Windows service stops. In the procedure division of the OnStop method, add this code:

protected override method OnStop, void

Build the Windows Service

It’s time to build the application and see how good your typing is!

  • In Solution Explorer, right-click on your Windows Service project and select Build.
  • Check the output window to make sure your application built correctly. You’re looking for something like this:


------ Build started: Project: MyWcfHostService, Configuration: Debug Any CPU ------
========== Build: 1 succeeded or up-to-date, 0 failed, 0 skipped ==========

If your application does not build correctly then you’ll need to review the instructions above and make sure that you completed the required steps.

Registering and Starting the Windows Service

Now that you have a Windows service there are only two more steps that you’ll need to complete before the service can be tested. Those steps are:

  • Register the service with Windows.
  • Start the service.

To register the service you’ll need to open a Visual Studio command prompt window and then go the the folder that contains your applications executable. This will generally be the binDebug or binRelease folder below your project. Once you’re there you should be able to register your service like this:

..binDebug> INSTALLUTIL MyWcfHostService.exe

Look for messages that indicate that the service was successfully installed, then start your service like this:

..binDebug> NET START MyWcfHostService

Look for messages indicating that the service was started correctly.

Testing the WCF Service

If your Windows service started correctly then your WCF service should now be running. To verify that it is, open a browser and navigate to the URI that was specified in the code.


You should see a WCF service home page similar to this:



If you see a service page like this then you should be able to start using the service. Of course we haven’t talked about how to do that yet … that’s for another day!

Remember to Stop The Service

You probably want to stop and unregister your Windows Service before you forget that it’s running. To do do, return to the Visual Studio command prompt and use commands like these:

..binDebug> NET STOP MyWcfHostService
..binDebug> INSTALLUTIL /u MyWcfHostService.exe

Exposing WCF services using Synergy .NET Interop

By Steve Ives, Posted on at 11:20 am

In this post I will explain how a WCF service can be created using a Synergy .NET Interop project. In my earlier post I explained how to use xfNetLink .NET to create a WCF service, which provided an easy way to create a WCF service for developers who were already using xfNetLink .NET and xfServerPlus. Now I want to show you an alternate approach that is somewhat similar in nature, but which does not require the continued use of xfNetLink .NET and xfServerPlus in final solution. Of course this might not be what you want if your Synergy server is a non-Windows system.

This is the fourth in a series of posts relating to the various ways in which Synergy developers can use of Windows Communication Foundation (WCF) when building their applications. The posts in the series are:

  1. Building Distributed Apps with Synergy/DE and WCF
  2. Exposing WCF Services using xfNetLink .NET
  3. Hosting WCF Services in an ASP.NET Web Application
  4. Exposing WCF services using Synergy .NET Interop (this post)
  5. Self-Hosting WCF Services
  6. Exposing WCF services using Synergy .NET

What is Synergy .NET Interop

Before we get started we better make sure you know what a Synergy .NET Interop project is. In a nutshell an Interop project is a way of creating a .NET assembly containing various classes, where the external interface of those classes is defined by a collection of Traditional Synergy xfServerPlus methods, and the Synergy records that are referenced by the parameters of those methods. The idea is that the classes exposed by the assembly created by an Interop project have the exact same external interface that would be created if those same methods were defined in a Method Catalog and exposed via xfServerPlus and xfNetLink .NET. So the primary use case for an Interop assembly is to allow developers with existing applications which use xfNetLink .NET and xfServerPlus to factor those tools out of their solution, resulting in a pure .NET application.

In the same way that GENCS has an optional –W command line switch which essentially transforms the resulting .NET assembly into a WCF service, the Synergy .NET Interop project has a project option which does the exact same thing.

So let’s get started. Here’s how to do it. Remember, an Interop project allows you to expose a Synergy .NET assembly based on one or more traditional Synergy methods and records, but there are some prerequisites:

  1. The Synergy methods must make use of the recently introduced attributes and documentation comments, so that the external interface of the method is entirely defined within the code. The Interop project does not use a Synergy Method Catalog. For more information on this you can refer to a blog post that I wrote back in 2009 called Wave Goodbye to the MDU.
  2. The records that are referenced by the parameters of the methods must be defined in a repository, but this would always have been the case if you were using xfServerPlus.
  3. Generally the data files that are accessed by your methods should be moved to the Windows server where the WCF service will be hosted, so that the files can be accessed locally. If your data files need to stay on a non-Windows server then of course you could use xfServer to access the files remotely.
  4. You’ll need to have a copy of the source code for the Synergy methods available on the Windows development system where you are using Synergy .NET.

These are the steps that you’ll need to complete in order to create a Synergy .NET Interop assembly from your existing Synergy methods and repository structure definitions:

Create an Interop Project

The first step in the process is to create a new Synergy .NET Interop Assembly project:

  • Open Visual Studio and create a new Synergy .NET Interop Project.
  • From the menu, select File > New > Project.
  • In the Installed Templates list select Synergy/DE > Interop.
  • Set the name and location of the new project as required (here I’m naming the project MyInteropAssembly and setting the location to my c:temp folder).
  • Click the OK button to create the new project.



When you create an Interop project a new source file called SynergyRoutines.dbl is automatically included in the project. This file contains various utility routines that are used by the interop project in order to expose the same interface that xfNetLink .NET does. You shouldn’t need to be concerned with this code, and shouldn’t modify it. Simply close the file.

Add Synergy Method Source Files

Having created the Interop project the next step is to add the source code for your Synergy methods to the project. Remember that the methods that you include in an Interop project are Traditional Synergy subroutines and functions that include whatever {xfMethod} and {xfParameter} attributes are required in order to completely document the external interface of the methods within the source files.

imageFor clarity when creating an Interop project I also like to include my method source files in a folder within the project, and I generally name the folder “Methods”. This is entirely optional though.

  • In solution Explorer, right-click on your Interop project and from the context menu select Add > New Folder.
  • Change the name of the folder to Methods and press enter.
  • Right-click on your new Methods folder and from the context menu select Add > Existing Item….
  • Use the resulting open file dialog to browse to the location of your Synergy method routines, select them all, and then click the Add button to add the routines to your project.

In Solution Explorer your project should now look something like the image on the right.

Before we move on let me make a couple of things clear. Firstly it is important that you know that when you add existing files to a project using Add > Existing Item, those files are COPIED into your project folders. If you prefer to leave the source files in their existing location then you can use Add > Reference Existing Item.

The second thing that you need to understand is that in the example I am using here the nature of the methods that I am using is relatively simple, and the methods don’t have external dependencies on other routines in libraries, don’t use include files, etc. If your methods do have such dependencies then you will need to decide how best to resolve those dependencies.

Set Environment Variables

It is likely that you will need to set some environment variables in order for your code to be able to compile and run. It is almost certain that you will need to at least set the environment variables that allow your repository to be located and accessed, and in the case of the code that I am using, at runtime an environment variable named DAT is used to specify the location of the data files that are accessed by the code.

Synergy .NET development projects include the ability to set environment variables in the development environment via properties of the project:

  • In Solution Explorer, right click on your project and from the context menu select Properties.
  • In the project properties dialog, to the left side, select the tab named Environment Variables.
  • Set whatever environment variables are required in order for your code to compile and run.
  • Save your changes by selecting File > Save from the menu.
  • Close the project properties dialog.

In the case of the code I am using for this example I needed to set the following environment variables:


By the way, the tools in Synergy .NET also honor the same mechanisms for setting environment variables as Traditional Synergy on the Windows platform. So if the environment variables that you need are already present in your system environment, or are provided by the synergy.ini or synuser.ini files then you won’t need to set them here.

Build an Interop Assembly

You should now be able to build your interop assembly.

  • In Solution Explorer, right-click on your project and from the context menu select Build.
  • Check the output window, you should see something like this:
------ Build started: Project: MyInteropAssembly, Configuration: Debug Any CPU ------
========== Build: 1 succeeded or up-to-date, 0 failed, 0 skipped ==========


imageIf your assembly did not build then you’ll need to resolve any errors that you may have before you proceed. The most likely cause for errors at this point will be external dependencies that are not catered for.

Check out what happened in your project. If you look in Solution Explorer you will notice that a new folder called GeneratedCode was created, and some new source files were added to the folder. These new files are at the center of how Interop projects work.

The method source files that you added to the project, in the Methods folder, were Traditional Synergy subroutines and functions. The job of an Interop project is to expose the functionality of those methods in the same way that xfNetLink .NET’s GENCS utility does, and GENCS creates .NET classes that represent the Synergy methods, and the data structures exposed by those Synergy methods.

The Interop project essentially does the same thing, except that where GENCS created C# code which uses xfNetLink .NET and xfServerPlus to call the Synergy methods, the Interop project creates Synergy .NET code which calls the Synergy methods directly.

In the code used in my example the Synergy methods that I added to the project were all part of an interface named “SynergyServer”. This was defined by the {xfMethod} attributes that were present in each of the source files that I included into the project. You will notice that the GeneratedCode folder now includes a source file named SynergyServer.dbl, and if you were to look in the source file you would see that it contains a class named SynergyServer, which in turn contains methods named GetAddressForUpdate, GetAllCustomers and so on. These methods correspond to the Synergy methods that I originally included in the project.

Additionally you will notice that the GeneratedCode folder also contains several source files which represent the record definitions which are exposed by the parameters of my methods. For each record that is exposed the interop project has created a class to represent that data structure. These classes are named Address, Address_type, Contact and so on.

However, if you were to look in the source files that have been generated into the GeneratedCode folder you might notice that these generated classes do not contain any ServiceContract, OperationContract, DataContract or DataMember attributes. In other words, the classes can’t currently be exposed via WCF.

Note: You should not make changes to any of the code in the GeneratedCode folder, because this code will be recreated each time you build the project. 

Expose a WCF Service

As I briefly discussed in an earlier post, in order for classes to be exposed via WCF it is necessary to apply various attributes to those classes:

Nature of Item Required Attribute
Class containing callable methods ServiceContract
Callable method OperationContract
Class defining a data structure DataContract
Accessible member in a data structure DataMember


In an Interop project, these attributes can be automatically added to the generated classes by enabling a project option called “Generate WCF Contracts”.

  • In Solution Explorer, right-click your project and select Properties.
  • In the project properties dialog, to the left side, select the tab named Interop.
  • Check the Generate WCF Contracts option.
  • In most cases it’s also a good idea to set the Generate out parameters property to out instead of the default value of “ref”.
  • Save your changes by selecting File > Save from the menu.
  • Close the project properties dialog.
  • In Solution Explorer, right-click on your project and from the context menu select Build.
  • Check the output window and make sure that your assembly built correctly.


Note: The default behavior of generating out parameters as ref is to maintain compatibility with what GENCS does by default, but when exposing a new WCF service to a new client application you would always want output parameters defined as type out.


Now take a look at the various source files in the GeneratedCode folder. You should notice that the ServiceContract, OperationContract, DataContract and DataMember attributes are present as required.

Host the Service

That’s it, you just used a Synergy .NET Interop project to define and create a WCF service. Of course before you can actually do anything with the service you will need to host it somewhere. One option is to host the service in an ASP.NET Web Application as described in my earlier post.

However, sometimes developers don’t want to have to setup and maintain an IIS web server simply to host a WCF service. Luckily there are other ways of hosting a WCF service that do not require IIS, and that will be the topic of the next post in this series.

Building Windows 8

By Steve Ives, Posted on August 29, 2011 at 1:50 pm

As Microsoft’s new Build Windows conference draws ever closer the rumor mill about what the focus of the conference will be is gathering momentum. This is due in no small part to the fact that with the conference only two weeks away there is still no published agenda. But that doesn’t seem to have deterred people from attending, I would estimate that there are generally over 10,000 delegates at these events, and this conference has been sold out since early August!

That being said it’s not too hard to figure out from the name of the conference that the focus will be on the next version of the Windows operating system, which Microsoft have “code named” Windows 8! What might be a surprise to a lot of people however is the scale of the change that is on the way next year, because from all available information it’s looking like the default Windows 8 experience will be VERY different from anything that Windows users have experienced in the past.

This suspicion was confirmed recently when Microsoft posted a video entitled “Building Windows 8 – Video 1” on one of their development team blogs. The video was also uploaded to YouTube, and I’ve embedded it in this post … take a look:

As you can see the default Windows 8 experience is very different, and is sure to bring some new challenges for developers who want to deploy applications that take advantage of the new capabilities of the platform. From Microsoft’s demonstration it is clear that traditional Windows applications will continue to be supported, so there is no need to panic, but as software developers we all need to be thinking about how a change of this magnitude could affect our businesses.

For some time now Microsoft has touted WPF and Silverlight as the flagship technologies of choice for building UI’s for .NET applications. But with Windows 8 is all that about to change? The video makes it clear that the primary UI technologies used to build Windows 8 applications are HTML5 and JavaScript, neither of which have a particularly strong toolset presence in Visual Studio 2010. So for many of the developers at the Build Windows conference the main question will be “what’s new in Visual Studio 2012 and .NET Framework 4.5 that will help me build applications for Windows 8?”.

Clearly Microsoft believe that mobile and tablet devices are going to become far more predominant in the future, and are actively planning for this by merging the various operating systems that are used on the various types of computing platforms. And of course they are not alone in this endeavor as Apple’s recent release of OS X Lion also somewhat takes this approach, although not quite to such a radical degree.

Of course there is another group of people who also have a bunch of work to do, and that’s the hardware vendors. If Windows 8 is to be successful one would assume that the default for personal computer and laptop screens will need to change to be predominantly touch-enabled devices. While it is clearly stated in the video that the new UI will work just fine with a mouse and a keyboard, I for one am very skeptical about how WELL it will work in that mode! And of course the availability of the hardware is only a part of the story … we must also consider how long it will take companies to replace existing hardware with new touch-sensitive devices.

Now don’t get me wrong … I’m not suggesting for one minute that there will be a big rush to do so, and I’m absolutely suggesting that a major change of this type could take many years … but for some of us, with certain types of applications, in certain market places, adopting these new capabilities could offer significant rewards.

By the way, I’m not a betting man but I’d lay good money on the fact that there will be a setting to disable the new Windows 8 UI in favor of reverting to Windows 7’s Aero UI, and I’d also be comfortable predicting that many corporations will be doing just that. So again, don’t panic! While the new UI may make for a fabulous demo, and may be a fantastic way of interacting with photos and videos, and browsing the web, will it really provide a suitable platform for presenting business software to commercial users? Actually, in some cases the answer will be a resounding YES … but in other cases the more traditional approach to presenting applications will continue to be far more appropriate.

Of course in order for Synergy developers to be ready for Windows 8, Synergex must be ready first. I will be attending the Build Windows conference, as will three of my colleagues from the Synergy Development team. We’ll do our best to keep you informed about what we learn.

By the way, if you’re interested in keeping track of what’s going on with Windows 8 then a good place to start is Microsoft Development’s Building Windows 8 BLOG. The blog has some interesting articles, and already has several more videos discussing these new features.

Hosting WCF Services in an ASP.NET Web Application

By Steve Ives, Posted on July 1, 2011 at 3:39 pm

There are several ways that you can use Synergy/DE tools to expose WCF services, but regardless of which way you decide to create a service, the next decision you have to make is how to host it. By hosting a WCF service you expos the service and make it possible to use it from other applications. In this post I will introduce you to one way that WCF services may be hosted, via an ASP.NET web application and an IIS web server. In a later post I will show you how to host WCF services without this requirement for an IIS web server.

This is the third in a series of posts relating to the various ways in which Synergy developers can use of Windows Communication Foundation (WCF) when building their applications. The posts in the series are:

  1. Building Distributed Apps with Synergy/DE and WCF
  2. Exposing WCF Services using xfNetLink .NET
  3. Hosting WCF Services in an ASP.NET Web Application (this post)
  4. Exposing WCF Services using Synergy .NET Interop
  5. Self-Hosting WCF Services
  6. Exposing WCF services using Synergy .NET


A WCF service is simply a collection of one or more classes in an assembly, but the whole point of implementing a WCF service is to make those classes available to be used by other applications. And those applications will often be located on different networked systems from the service itself. So, in order for a WCF service to be useful, it needs to be “hosted” somewhere, and that somewhere needs to be available on a network.

There are three basic ways that WCF services can be hosted:

  1. Inside a Web application located on a Web server.
  2. Using Windows Process Activation Services (WAS). This mechanism was introduced in Windows Server 2008 and provides a mechanism for hosting WCF services without requiring a Web server.
  3. Services can be “self” hosted by some custom .NET application. For example, developers often host WCF services inside a Windows Service application.

In this post I will show you the basics of hosting a WCF service in an ASP.NET web application. In a future post I will go on to show how to self-host services.

Setting up basic hosting for a WCF service inside an ASP.NET Web application is very easy, but as Synergy .NET doesn’t have support for creating Web applications you’ll have to use another .NET language, either C# or VB.NET. However, don’t worry about that too much, because there won’t actually be any code in the Web application!

  • Start Visual Studio 2010 and create a new ASP.NET application:
    • From the menu, select File > New > Project.
    • Under Installed Templates, select Visual C# > Web > ASP.NET Empty Web Application.
    • Chose the name and location for your new Web application.
    • Click the OK button to create the new project.
  • Add a new WCF Service to the project:
    • From the menu, select Project > Add New Item.
    • Under Installed Templates, select Visual C# > Web > WCF Service.
    • Enter the name for your new service. The name will be part of the service endpoint URI that the client connects to, so pick something meaningful. For example, if your service allows orders to be placed then you might name the service something like OrderServices.svc.
    • Click the Add button to add the new service to the project.

You will notice that three files were added to the project:


In addition to the service (.svc) file that you named, you will see two C# source files. These files were added because Visual Studio provided all of the files that you would need in order to expose a new WCF service that would be manually coded in these files. But what we’re trying to do is host a WCF service that already exists in another .NET assembly.

  • Delete the two C# source files by right-clicking on each and selecting delete.

In order to expose a WCF service that exists in another assembly, the first thing we need to do is add a reference to that assembly, to make the classes it contains available within the new Web application.

  • From the menu select Project > Add Reference and then select Browse.
  • Locate and select the assembly containing your WCF service and add a reference to your project.
  • If the assembly you selected was created using xfNetLink .NET then you will also need to add a reference to the xfnlnet.dll assembly, as is usual when using xfNetLink .NET

You’ll need to know that namespace and class name of the WCF service in your assembly. If you can’t remember this that double-click on the assembly that you just referenced and then use Object Browser to drill into the assembly and figure out the names. All that remains is to “point” the service file at your WCF service class.

  • Double-click on the service (.svc) file to edit it. You should see something like this:


Edit the file as follows:

  • Change Language=”C#” to Language=”Synergy”.
  • Change Service=”…” to Service=”YourNamespace.YourWcfClass” (obviously replacing YourNamespace and YourWcfClass with the namespace and class name of your WCF service).
  • Remove the CodeBehind=”…” item … there is no code-behind, the code is all in the other assembly.
  • Save the file.

So you should now have something like this:


If your service is based on an assembly created using xfNetLink .NET then you have one final configuration step to perform. You need to tell xfNetLink .NET how to connect to xfServerPlus. You can do this by using the Synergy xfNetLink .NET Configuration Utility (look in the Windows Start Menu) to edit the new web applications Web.config file. If your xfServerPlus service is not on the same machine as your new web application then you must specify a host name or IP address, and if xfServerPlus is not using the default port (2356) then you must also specify a port number. When you’re done, the Web.config file should contain a section like this:


That’s it, you’re done. You should now have a working WCF service!

  • To see if the service has really been hosted, right-click on the service (.svc) file and select View In Browser.

You should see the service home page, which will look something like this:


If you see this page then your service is up and running. By the way, the URI in your browsers address window is the URI that you would use to add a “Service Reference” to the service in a client application … but we’ll get on to that in a later post.

Of course, all we have actually done here is set up a web application to host a WCF service, but we’re using Visual Studio’s built in development web server (Cassini) to actually host the service. If you were doing this for real then you’d need to deploy your new web application onto a “real” IIS web server.

We’re not done with the subject of hosting WCF services; in fact we’ve only really scratched the surface. One step at a time!

In my next post in this series I will show you how to Expose a WCF services using Synergy .NET Interop.

Exposing WCF Services using xfNetLink .NET

By Steve Ives, Posted on at 1:40 pm

Following a recent enhancement to the product in Synergy 9.5.1, developers can now use xfNetLink .NET to create and expose Windows Communication Foundation (WCF) services. In this post I will describe how to do so.

This is the second in a series of posts relating to the various ways in which Synergy developers can use of Windows Communication Foundation (WCF) when building their applications. The posts in the series are:

  1. Building Distributed Apps with Synergy/DE and WCF
  2. Exposing WCF Services using xfNetLink .NET (this post)
  3. Hosting WCF Services in an ASP.NET Web Application
  4. Exposing WCF Services using Synergy .NET Interop
  5. Self-Hosting WCF Services
  6. Exposing WCF services using Synergy .NET


The basic approach is pretty easy; in fact it’s very easy. In 9.5.1 we added a new -w command line switch to the gencs utility, and when you use the new switch you wind up with a WCF service. I told you it was easy!

So, what changes when you use the gencs –w switch? Well, the first thing that changes are the procedural classes that are generated, the ones that correspond to your interfaces and methods in your method catalog, change in the following ways:

  1. Three new namespaces (System.Runtime.Serialization, System.ServiceModel and System.Collections.Generic) are imported.
  2. The class is decorated with the ServiceContract attribute. This identifies the class as providing methods which can be exposed via WCF.
  3. Methods in the class are decorated with the OperationContract attribute. This identifies the individual methods as being part of the service contract exposed by the class, making the methods callable via WCF.
  4. If any methods have collection parameters, the data type of those parameters is changed from System.Collections.ArrayList to System.Collections.Generic.List. Changing the collection data type is not strictly necessary in order to use WCF, but results in a more strongly prototyped environment which is easier to use, and offers more benefits to developers in terms of increased IntelliSense, etc.

The next thing that changes are any data classes, the ones that correspond to the repository structures that are exposed by the parameters of your methods, that are generated. These data classes change in the following ways:

  1. Two new namespaces are imported. These namespaces are System.Runtime.Serialization and System.ServiceModel.
  2. Each data class (which corresponds to one of your repository structures) that is generated is decorated with the DataContract attribute. This identifies the data class as a class which can be used in conjunction with a WCF service, and which can be serialized for transmission over the wire.
  3. Each public property (which corresponds to a field in the structure) is decorated with the DataMemeber attribute. This attribute identifies each property within the class as one which will be serialized, and as a result will be visible to client applications which use the WCF service.

By the way, if you use a Workbench “.NET Component Project” to create your xfNetLink .NET assemblies then there isn’t currently an option in the component information dialog to cause the new –w switch to be used. So, for the time being, what you can do is add the switch to the Workbench “Generate C# Classes” tool command line. To do this you would go into project properties for the component project, go to the Tools tab, select the “Generate C# Classes” tool, then add the –w at the end of the command line, like this:


We’ll be adding a new checkbox to the component information dialog in 9.5.3 later this year.

By the way, by using the gencs –w switch you make it possible to use the resulting classes as a WCF service, but you don’t have to do so … you can continue to use the classes as a regular xfNetLink .NET assembly also. Why would you want to do that? Well, I sometimes use gencs –w just to turn my collection parameters into generic lists!

I have submitted a working example to the Synergy/DE CodeExchange, contained within the zip file called Within the example, the following folders are relevant to exposing and consuming a WCF Service using xfNetLink .NET:

Folder / Project



Contains the Workbench development environment for xfServerPlus and the exposed Synergy methods. If you wish to actually execute the examples then you must follow the setup instructions in the readme.txt file.


Contains the Workbench project used to create the xfNetLink .NET client assembly with the WCF attributes.


Contains the Visual Studio 2010 solution containing an ASP.NET web application used to host the WCF service, as well as three example client applications, written in Synergy .NET, C# and VB.

So, the gencs –w command line switch you make it possible to use the resulting classes to directly expose a WCF service, but there is still the matter of how to “host” the service in order to make it accessible to remote client applications, and that’s what I will begin to address in my next posting.

Building Distributed Apps with Synergy/DE and WCF

By Steve Ives, Posted on June 22, 2011 at 1:22 pm

At the recent SPC’s in Chicago and Oxford several of the sessions that I presented were focused on networking, and in particular on the various tools and technologies that are available to Synergy developers to allow them to build and deploy distributed software applications. In particular I spent quite a bit of time talking about a technology called Windows Communication Foundation.

This is the first in a series of posts relating to the various ways in which Synergy developers can use of Windows Communication Foundation (WCF) when building their applications. The posts in the series are:

  1. Building Distributed Apps with Synergy/DE and WCF (this post)
  2. Exposing WCF Services using xfNetLink .NET
  3. Hosting WCF Services in an ASP.NET Web Application
  4. Exposing WCF Services using Synergy .NET Interop
  5. Self-Hosting WCF Services
  6. Exposing WCF services using Synergy .NET

What is WCF

WCF is a part of the .NET framework that provides a powerful and flexible way to implement network communication between the various parts of a distributed software application. For many years Synergy developers have been able to build distributed applications using xfServerPlus and xfNetLink. Many have done so, and have deployed a wide variety of applications based on these technologies. When developing a new .NET client application developers would use xfNetLink .NET to gain access to their Synergy business logic and data.

This approach has served us well over the years, will continue to do so, and is still the most appropriate solution in some scenarios. But in some other scenarios using WCF might now be more appropriate, and could help developers to broaden the capabilities of their applications in several key areas, some of which are:

WAN Communication

Because the communication between xfServerPlus and xfNetLink uses a custom protocol which operates on a “non-standard” port, it may not be appropriate for use over wide area networks and the Internet. The primary problem here is that there is a high chance that this communication would be blocked by firewalls, some of which may be outside of your control. WCF supports multiple network transport protocols, the most basic of which is HTTP. This means that it is designed with the Internet in mind, and is very suitable for implementing applications which communicate over the Internet.

Multiple Endpoints

Another advantage of WCF is that the same WCF service can be exposed via multiple “endpoints”, and each of these endpoints can be configured to use different communication protocols and mechanisms. For example a single service could be exposed via one endpoint which uses HTTP and SOAP which would be suitable for a wide variety of client applications to be able to access from anywhere (including via the Internet), while at the same time being exposed by a second endpoint which uses low-level TCP/IP communications and binary messaging protocols suitable for use by applications running on the same local network as the service, at much higher performance. A single client application could even be configured to dynamically switch between these endpoints based on the current location of the user.

More Client Options

When using xfServerPlus and xfNetLink, client applications must be written in a programming language which is able to use one of the supported xfNetLink clients (COM, Java or .NET), but because WCF services can be interacted with via “standard” protocols such as HTTP and SOAP there are many more client application possibilities, because almost all development environments and programming languages are able to use these basic protocols.

Asynchronous Support

WCF also provides the ability to easily support asynchronous communication between clients and servers. When a client application calls an xfServerPlus method the client must wait for the execution of the method to complete, and for any resulting data to be returned, before performing any other processing. Using WCF it’s easy to support asynchronous method support, where the client application can call a method and then continue with other processing, later receiving an event when the remote method has completed its operation and when any resulting data is ready for use. This approach can make client applications appear to be much more dynamic and responsive.

Bi-Directional Communication

In many distributed software applications interaction between the client and the server is initiated by some event in the client application which requires some subsequent processing in the server application. But in some situations it is necessary for the server application to be able to, at will, initiate some processing in the client application. Unfortunately xfServerPlus and xfNetLink don’t really address this use case, but it can be addressed with WCF, because WCF service endpoints can be “self-hosted” within any type of .NET application. This means that as well as a client application having the ability to interact with a WCF service on some server somewhere, the client can also expose a WCF service, which the server application (or in fact any other application) could interact with.

WCF is an extensive subject area, and in this BLOG I’m not even going to attempt to teach you about the specifics of using WCF. Instead I’m simply going to try to make you aware of some of the reasons that you might want to explore the subject further, and make sure that you know about the various ways that you can get started.

There are several ways that Synergy developers can utilize WCF in their applications, and I’ll briefly describe each of these mechanisms below.

WCF via xfNetLink .NET

In xfNetLink .NET 9.5.1 a new feature was introduced which gives developers a lot of additional flexibility in the way that they build their applications, or rather the way that they communicate between the various parts of the application. This new feature is enabled through a new command line parameter to the gencs utility (-w). When you use this new option, two things change.

When you use gencs –w, the first thing that changes is that various attributes are added to the wrapper classes that are created by gencs. These attributes in turn allow those generated classes (and the assembly that they are compiled into) to be directly exposed as a WCF service. Previously, if a Synergy developer wanted to expose a WCF service which in turn exposed their Synergy business logic and data, they have to manually “wrap” their xfNetLink .NET procedural and data classes in other classes which in turn exposed a web or WCF service.

The second change when using gencs -w is that any collections which are exposed by the application API are transformed from un-typed “ArrayList” collections, to more useful and flexible “Generic List” collections. This change will require a small amount of re-coding in any existing client applications, but results in a significantly enhanced development experience.

This mechanism is likely to be of interest to developers who already have an existing solution using xfNetLink .NET and xfServerPlus, and want to take advantage of some of the additional capabilities of WCF, or to developers who wish to expose a new WCF service where the server application exposes code running on a UNIX, Linux or OpenVMS server.

WCF via Synergy .NET Interop

Another way that Synergy developers can expose WCF services is via Synergy .NET’s “Interop” project. The primary purpose of an Interop project is to allow developers with existing xfServerPlus applications to migrate their existing Synergy methods to a native .NET environment. By adding their method source code to an interop project they are able to execute those methods directly in the .NET environment, instead of using xfNetLink .NET and xfServerPlus to execute the methods with traditional Synergy on a remote server.

The Interop project works by generating Synergy .NET “wrapper classes” for your traditional Synergy methods (subroutines and functions) and data structures (records). The external interface of these wrapper classes is very similar to that of the C# wrapper classes produced by xfNetLink .NET’s gencs utility. The primary goal of the Interop project is to allow developers to migrate existing applications from a mixed .NET / traditional Synergy environment to a 100% .NET environment, with only minor changes to the code of existing client applications.

When you create an Interop project in Visual Studio, one of the options that you have (via the project properties dialogs) is to “Generate WCF contracts”, and as discussed earlier in this article, the effect of this is to add various attributes to the generated wrapper classes so that they can be directly exposed as a WCF service.

So again, for Synergy developers, this approach can provide a quick-and-easy way to expose a WCF service based on existing code. Again, this approach is likely to be primarily of interest to those who already have xfServerPlus based applications running on the Windows platform.

WCF via Synergy .NET

Both of the previous approaches were primarily focused on those who already use xfServerPlus, and both provide an easy way to get started with WCF. However in both of the previous scenarios, the external interface of your WCF service is directly defined by the interface to your underlying traditional Synergy methods (subroutines and functions), and the WCF data contracts that are exposed are defined by the repository structures exposed by the parameters of those methods. So, while the WCF capabilities provided by xfNetLink .NET and by the Synergy .NET Interop project are easy to use, you don’t get full control over the exposed interface and data. If you want that finer level of control, or if you’re just getting started with server application development and don’t have existing xfServerPlus methods, there is a better way to go.

The third way that Synergy developers can leverage WCF is by using Synergy .NET to create an all-new WCF service with native .NET code. This task was possible in 9.5.1 when Synergy .NET was first introduced, but has been made much easier through the introduction of a new “WCF Service Library” project template in 9.5.1a.

Creating a new WCF service via a WCF Service Library is the way to go for developers who want to write an all-new service application, or who don’t mind a little extra effort to re-work some existing code in order to factor out some of the “wrapper” layers involved with the previous two approaches. As a result you will have full control of the resulting WCF service, and the contracts that it exposes.

Wrapping Up – For Now

So, as you can see, Synergy/DE is now providing you will all kinds of new and exciting things that you can do in your Synergy applications, and I firmly believe that WCF is one of the most important, and powerful. In the near future I will be writing several additional BLOG posts which will explain these three ways of exposing WCF services in more detail, and I’ll also try to provide more detail about WCF generally. So for now, be thinking about how your existing distributed applications are built, and what things you might wish to improve about them. Or be thinking about that all-new distributed application that you’ve wanted to get started on. If you’re thinking of enhancing or implementing a distributed application, then using WCF is almost certainly the way to go.

Free Stuff!

By William Hawkins, Posted on March 14, 2011 at 2:46 pm

It’s a rare occasion where anything is truely free. Most of the time it’s simply a way for a marketing company to obtain information about you, so they can provide (or bombard) you with information about products that you have no interest in purchasing. However, there are some occasions when “free” really does mean that there’s no additional cost. The Synergex CodeExchange is (IMHO) one of those gems.
In may last blog, I discussed the process of validating a large number of the CodeExchange submissions with Synergy 9.5 and Synergy for .Net. In this blog, I want to highlight a couple of new submissions that you may find useful.

SynArrayList – this submission contains a couple of subroutines that allow you to sort an ArrayList in Synergy, either using a bubble sort or dynamic memory/qsort. You probably won’t need to use both methods of sorting, but they provide code examples to allow you to create custom sort routines of your own. This submission also contains an example of extending the ArrayList class, and creating a new class that processes Synergy alpha types natively.  This allows you to avoid the requirement to box/unbox your alpha variables as you process a collection.  Of course, the underlying arraylist still requires object types, but you don’t have to be concerned about that. And it has sort() and reverse() methods and some other ArrayList method that are part of the ArrayList class in .NET

SourceTree – this submission builds a utility that will parse your source code, and generate a data file that records the subroutine/functions in your application that call other subroutines/functions.  This allows you to create documentation on where routines are used in your application.  It can also be used to generate a list of routines called by a particular subroutine/function/mainline and all the routines that are called by those routines.

I’m also working on some other CodeExchange submissions – examples include a file I/O class and a utlity to create the xfNetLink attributes that can decorate your code.  Watch this space!!!

The Final Chapter

By Richard Morris, Posted on December 17, 2010 at 6:00 am

Using Synergy in all aspects of a new WPF based development is really quite exciting.  But when you start to bring in code that was written many years ago you really begin to see the power of a truly cross platform capable development environment.

The task I started while working with White Knight was to create a simple application that managed the communications with their customer base – basically a very simple CRM system.  The brief was to have a great looking windows desktop application and write it in Synergy – oh, and use all their existing library routines, data layout include files and database files.

And the solution, if you’ve followed my earlier blogs, was to utilise the new 9.5 release of Synergy.  With Synergy 9.5 we have the Visual Studio Integration which, in a nut shell, is Synergy language inside the powerful Visual Studio development environment.  Using this environment we can craft our user interface utilising WPF controls and Synergy language to bind to our data classes.  So, that’s the UI sorted.

Using the Synergy .NET API I can continue to use my existing Synergy language routines to load my new WPF UI Library, and manage the data communication between my program and the UI controls using WPF’s powerful data binding techniques.  So that’s the existing program logic and data access sorted.

And the results:

A fully functional UI, all written in Synergy and XAML (the WPF portion of the UI) managing our SDBMS data and Synergy business and validation logic. 

So what about your application?  If it’s in need of a bit of a user interface upgrade, download the latest 9.5 release of Synergy and let your imagination run wild.  You’ll be surprised just how much you can do in a short space of time. 

As we head towards the end of 2010 we’ve already started our plans for SPC2011 – watch this space for details!  I’m really excited about the prospect of presenting these great new capabilities that Synergy offers.  I can’t believe how quickly this year has gone by.  I hope you all have a great holiday season and here’s to a bright WPF New Year!

.NET is a blast

By Richard Morris, Posted on November 23, 2010 at 3:19 pm

One great aspect about my job is not only helping people utilise Synergy to the full, but to see the results of their hard work. And there is no better place to do this than “at the coal face”. Today’s coal face is, of course, on the shop floor at White Knight laundry. I was given a guided tour after lunch to see just how the Synergy system tracks items through the process.

The washing machines are huge, several feet taller than me. I shudder to think just how many pairs of socks you can wash within one of them, and they have several, all lined up together. It’s no wonder they have to tag every single item. Once items are cleaned they are dried in large driers and then the cool automation happens. Sheets are taken out of the dryers and each is laid out in turn at one end of a machine. If you are quick enough and sprint around to the other side of these large machines out pop a beautifully pressed and folded sheet. The shirt press is a blast, literally. It’s a two stage operation. Firstly the collar and cuffs are placed onto a machine and pressed. Then the shirt is placed over a frame, then it’s whisked off and steam blasted through it, and out comes a perfectly pressed shirt fit for a king.

And so to our CRM development. Our first task was to build the White Knight core routines into a native .NET assembly, which is the equivalent of an executable library. This task was achieved within a couple of hours. After all, it’s the same Synergy Language just a new compiler. The current system runs under Synergy version 8.3 and this code, I would say, hasn’t changed much since version 5.9 days. It’s testament to the power of Synergy to be able to take this code and build it under a brand spanking new development environment called Visual Studio 2010! To successfully build the new assembly required a few code changes. The compiler caught parameter mismatch declarations and some over subscripting. All the modifications we made improved the stability of the code.

We are now ready to begin to integrate our tried and tested logic with our new WPF UI. But there is a little more work to do first. Our data is a little shy and we need to gently coax it from the dark depths of our SDBMS files. Remember, some of this data was written away to the file a long time ago and those little single alpha character chaps that store our Y or N values work just fine in Synergy land, but for WPF we need to coerce these values to native types. So we are writing some very simple classes that take our Synergy records and expose only the fields our UI will be interested in as native .NET types.

Now we are building the WPF interface and binding to our new Synergy classes, exposing our existing Synergy data…

Taking .NET to the cleaners

By Richard Morris, Posted on November 22, 2010 at 2:23 pm

Ding dong, “Laundry service”! Now you could be mistaken for thinking that I’m staying in a rather nice hotel, being called upon by the maid for my dirty laundry. Not so, I’m afraid, I’ll be taking my dirty ‘smalls’ home with me. But for one of our customers, this is their calling card. The customer is White Knight, based near London and their business is laundry, run by Synergy.

It’s true. People and many of them are well known celebrities, have their laundry collected every Monday and returned within a few days, cleaned dried and perfectly ironed. Some ten thousand “items” pass through the machines at this site and this is a small site. Their other sites handle in excess of two hundred thousand articles every week.

To manage this workload across all sites is a suite of Synergy programs running on a Linux machine. Traditional character based systems handle all aspects of the process from collection, cleaning through to delivery of the right items to the correct customers.

But things don’t always go right. So when the customers call in and say “you’ve washed the spots off my favourite pair of shorts” it all needs to be recorded and processed. This calls for a CRM (Customer Relations Management) system. And here is where I enter the story. White Knight has invited me down to assist them to begin to write a fully functional CRM system in Synergy. They want a Microsoft Windows desktop application with all the bells and whistles with access to new and existing Synergy data and logic. Easy!

So today we hatched a plan. Graham from White Knight was fully prepared for my visit with a functional specification, data layouts and design utilising xfServerPlus. “But for a desktop application?” I asked. “Why are we not using WPF (Windows Presentation Foundation) and .NET?” Because I’m not strong with C#, I know enough to do my web site!” Graham replied. Well, given the imminent release of Synergy v9.5 and the integration of Synergy Language within Microsoft Visual Studio 2010 it would be a perfect candidate. We’ve created our Visual Studio projects and begun to define our WPF User Interface in XAML. Our existing Synergy routines are being imported into a new class library project and we are crafting Synergy classes to facilitate the communication between our application elements. For those of you at SPC 2010 you’ll recognise this as the Model-View-ViewModel pattern!

And how did we do? Well I’ll update my blog over the next few days of how well we do, writing our first Synergy for .Net application…..

Challenges Facing Synergy Developers

By synergexadmin, Posted on May 19, 2010 at 4:09 pm

I was recently involved in a discussion concerning Synergy tools and technologies, and how our customers can best position themselves to take advantage of them. Somewhere along the way, I was asked for (or I volunteered – I don’t exactly remember) my opinion about the current software development landscape, and the challenges that face so many of our customers today.

I identified three areas of concern for our customer base and the future of their applications. And since you’re reading this, I assume that you are a Synergy customer, so hopefully what I had to say will strike a chord with you – either as a challenge you’ve already faced and overcome, or as an issue with which you’re currently grappling.

GUI is King

Yes, you’ve heard it a million times before, but unfortunately you’re going to keep hearing about it until you’ve updated the look and feel of your application. The continued survival of almost every solution boils down to implementing one of two main GUI choices: web technologies or Windows .NET (which means WPF, SilverLight or WinForms).

If you were reading that last part carefully, you’ll note that this discussion is not targeted solely at the *nix and OpenVMS operations; if you’re on Windows already, but are still using the same UI Toolkit displays that your app was using years ago (i.e., you’re not incorporating .NET technologies with the Synergy/DE .NET API), then you’re in the same boat as everyone else.

Arguments about the efficiency of character-based data entry are still valid, but they’re becoming less and less relevant (or realistic) – particularly if you’re using the speed of data entry as an excuse to allow the rest of your application to wallow. While you may have several “workhorse” data entry screens, chances are they make up a very small percentage of your overall application. Information displays, reports, “look-ups” or maintenance utilities have no reason to be tied down to a cell-based presentation.

GUI’s are simply too pervasive and too familiar to ignore, and purely cell-based software solutions cannot hope to compete for much longer. Even the most enthusiastic supporters of your application, the ones who can see beyond the green screen or the pseudo-Windows of Toolkit to the power of your application, will readily agree that it’s becoming more and more difficult to convince new hires (or prospective customers) of the superiority of your Synergy solution.

And I’m not just talking to the Synergy shops that develop vertical applications which are then distributed and sold; Synergy “end users,” the shops that have an in-house, custom-built Synergy solution, need to take note as well. Serious scrutiny of your Synergy application is coming with the next management or executive-level turnover.

Perception is Reality

We’ve all heard the term before, but I think it would be better stated as “People act on perception as if it is reality.”

One of the most common (mis)perceptions in today’s society is “newer is better.” It’s beat it into to us at every turn and in every advertisement, from New and Improved Acme glass cleaner to Next Best Thing flat panel televisions. And unfortunately, a cell-based UI isn’t doing you any favors in this department. Cell-based apps are generally looked at as “old,” “outdated,” “legacy,” or simply (my favorite) “DOS.” It’s this perception that gives rise to a host of other concerns and questions. Interoperability. Reliability. Power.

But perhaps the most dangerous questions are the ones that aren’t asked. If the users of your application generally see it as a throwback to a bygone era, then it’s possible – nay, likely – that it never even occurs to them to ask the right questions. Can it communicate with Brand X’s software? Can it display graphs that give a visual indication of the state of your sales? Does it offer a web service? Does it support ad hoc reporting? These questions are the sales points from competing software vendors, and rest assured that management has heard the pitches – whether it be the CEO at your customer’s company, or the management team of your own.

Remember: Your UI is the gateway to the power of your application. If it looks like something that was distributed on a 5 &frac14;” floppy, then it’s time to seriously rethink the front end of your application.
Now is the Time to Act

The current recession has made life difficult for almost everyone. Sales are down, money is tight, and thoughts of corporate expansion have been put on hold.

For the past two years or so, companies simply don’t have the money to invest in a brand new software solution, whether it be an ERP package to replace your in-house software, or a glossy, glitzy, Windows-and-SQL-based solution from your competitor. If you’re wise, you’ll look at this period as a reprieve from increasingly heavy competition, and as an opportunity to throw development efforts into high gear.

Use the time to ensure that your software has every last competitive edge when the wheels of the economy start moving again. Take advantage of the lull in sales and expansion, and incorporate the latest and greatest that Synergy has to offer. Put a GUI on your application – even if it needs to be one screen at a time. Use the Synergy.NET API to enhance the look and feel of the most commonly-used screens of your Toolkit application. Make the small investment in Synergy SQL Connect, and set up a data warehouse that can be used by SQL Reporting Services, or open up the data in your system to other commonly-used software by utilizing Synergy xfODBC. Create a web portal, add a web service or two, and take advantage of the APIs and web services of other software solutions to enhance your own.

In Conclusion…

I want it known for the record that I’m a huge fan of Unix/Linux, and absolutely love OpenVMS, so understand that I’m not advocating a switch to the Windows OS. Remember that you can still take advantage of the reliability and stability of both *nix and VMS backend systems, and just bolt on a Windows GUI client wherever appropriate. Heck, chances are that your users are already using Windows boxes running VT emulator software anyways, so there’s probably no hardware investment that need concern you.

And there are plenty of methods available to leverage your core systems and routines if you’re one of the many Synergy shops currently running a “green screen” solution. Investigate xfODBC, SQL Connect, xfServer and xfServerPlus. Install and play around with the (free) Synergy Data Provider for .NET, and get yourself acquainted with Windows- or web-based technologies, programming languages and development environments. Start cleaning up your code and separate that business logic from the UI components – it may not be as hard as you think.

A little research and a small investment in time will go a long way toward illuminating the path of a better, more robust and more marketable software solution.

Do you agree? Disagree? Have a story that’s relevant, or want to share your own challenges and solutions to the GUI problems or perceptions you’ve faced? Let us know about them, and let’s get the discussion started.

On The Conference Trail

By Richard Morris, Posted on March 28, 2010 at 9:45 pm

Can you believe it is four months since I posted my first blog from Microsoft TechED in Berlin?  Time certainly does fly by, and so does the changing world of software development.  At Synergex we are committed to ensuring that we keep abreast of advancing technologies, so that we can continue providing expert advice and direction to Synergy/DE developers. 

This week I’m in London, and for the start of the week I can actually say “sunny” London.  Considering the weather we have been having here recently, I can honestly say spring may just be on its way!  I’m in London attending DevWeek 2010.  A software developer’s conference sponsored by, but not presented by, Microsoft.  I say that to emphasise that this is not another TechED.  This conference focuses more on the people using the tools and technologies, the real people like you and me, and not just the products on offer.

DevWeek 2010 is a lot smaller, in attendee numbers, than the TechED conference.  There are hundreds of people here, not thousands.  It’s a lot more personal, and you get much more opportunity to “discuss” (read “ague my case”) with the presenters.  The first session I attended on Monday morning had twelve people in the room, so it’s a lot more intimate.  The content, however, is far from small scale, with some impressive solutions to today’s application requirements.

Monday was a pre-conference day and I spent it delving deep into Silverlight, Microsoft’s XAML/WPF based Web development and application deployment environment.  You can achieve many cool things very easily with just a line or two of code.  Did you know, using Silverlight, it’s possible to deploy your application to appear to run natively on an Apple MAC?

One thing this conference has again emphasised to me is the abstract between software development and design.  And by design I mean the user interface.  All us programmers believe we can “cut it” when it comes to UI development, and many of us can do a reasonable job.  But put today’s design tools into the hands of the UI designers and it’s amazing what they can produce.  And the ease at which you can then implement their “styles” into you application is astonishing!  My first “hello world” foray into UI design was to produce a form with a round ball like object on it, and of course the customary “Press Me” button.  Pressing the button caused the ball to drop from the top of the window to the bottom, and then bounce a couple of times before coming to a rest.  Using Microsoft’s Expression Blend made it far too easy.  It really is a simple case of draw the object (my ball), define the result (ball at bottom of window) and pick a transition (how it gets from top to bottom).  Add my button, and a couple of clicks later, it really does look like the ball is naturally falling (starts slow and speeds up) and then bounces a little as it comes to its final resting place.  And I have not written a single line of code!

OK, So I can hear you thinking “and the use of a bouncing ball is?”  Good question.  Not much, I agree, but the techniques can easily add such a visual edge to you application.  Consider if you created a button style, which you could apply, as a default, to all buttons within your application.  The style could, for example, make the button double in size, including the text, when you hover over it with the mouse, making it easier to read.  Maybe have a circular ripple effect when you press it.  What if the input control (field) on your form that had focus is automatically magnified, giving the user a clearer view of what’s being asked for, without obscuring other areas of the form.   Your options are endless, and from a software developers standpoint – no code changes.  The code to data bind you fields to your Synergy data remains the same, but the look can be infinitely customisable.

Ensuring we structure our UI design correctly, data bind our controls in the XAML and avoid all non-UI related code behind ensures that we can utilise these UI development tools to the full.  We’ll be presenting these cool techniques at this year’s SPC in October, so make sure you’ve booked your place!

How Did I Get Here?

By Richard Morris, Posted on March 22, 2010 at 9:41 pm

Well, that was the DevWeek that was.  As I mentioned in my last blog, it’s been my first time here, and it’s been a very informative and interesting conference.  Will I attend next year?  I’d like to think so.  But that decision is not mine to be made.  As many of you reading this know, it’s “Manny” who makes the decisions.

So how does he (or she for that matter – I too had a lady boss once) go about making such a decision?  Is it a case of “If I mention it enough, I’ll get to go?”  I’m not sure that one works, and it’s certainly not going to be too reliable!  I could try the tact of “if I request to go to everything I must get to go to something”, but information overload just takes up too much of your managers time.  My boss certainly doesn’t search the web and peruse the small ad’s looking for events to send me on, far from it!  He’s got much better things to do, like figuring out just how he can squeeze my two new, 23 inch, flat panel, high resolution, wide screen monitors that I’ve just ordered, into this month’s budget.

But I need to ensure I keep up to date with modern technologies and techniques.  Reading web articles, blogs and industry publications helps, and one of the biggest benefits of my job is working with such a diverse user base – you all have different and unique requirements, but can apply very similar solutions using Synergy and all its related capabilities.

So, my boss relies on me to investigate and review all the available options.  I must admit, although Synergex has a single office in California, it certainly has a global attitude to training and employee development – I’ve been to conference and training events in the US, and across Europe.

The factors which influence my decisions as to which conference or training event to attend come directly from the requirements from our user base, and the direction in which Synergy/DE is going.  There is little point it being an expert in a technology that is of little or no use to our users.

I learnt a lot this week, both by attending some really good sessions, and also by talking to presenters and other attendees.  My background is significantly different from many (ok all!) of the people I spoke to.  They live, breath and sleep Microsoft and .NET.  I don’t, but need to understand how best we can encapsulate these new technologies within Synergy/DE applications.

Now, what are your justifications for attending this year’s SPC in October?  Firstly, as soon as the agenda is published, review it and ask yourself “what in the agenda will help me to advance my application?” I bet you can find at least ten things.  If your application runs on Windows and you plan on sprucing up your UI, there are a number of sessions that will walk you through the process of implementing the latest super slick WPF interface.  And remember, all source code will be made available on Code Exchange.  Not running on Windows?  It’s lucky you have Synergy/DE then!  Many of this year’s sessions focus on non-Windows environments, and the latest OO capabilities within the language.  Beginning to implement simple OO practices within your application will greatly improve the quality of your code, and the speed at which you can develop it.  And it’s not difficult to get started using synergy OO concepts, and it can integrate seamlessly with your existing procedural code!

How many of you UNIX and OpenVMS developers have a PC on your desk, and use a telnet terminal emulator to edit and build your code?  You’ve seen Workbench, know just how powerful a development environment it is, so why not swap the emulator for Workbench? We’re developing a session that will show you just how easy it is to edit then remote build your source code from within Workbench.

Arm yourself with the facts.  Talk to “Manny”, and book your ticket to this year’s SPC!

One of the justifications I have for attending these conferences is that I can impart my new found knowledge and understating, through the SPC, to our customers – you!

Using Workbench to Build Applications on Remote Servers

By William Hawkins, Posted on February 18, 2010 at 4:21 pm

I recently went to a customer site, to help them integrate Workbench into their OpenVMS development environment.  As a source code editor, the “integration” is relatively simple, you just need to have NFS/CIFS/SAMBA installed, and use it to make your OpenVMS (or UNIX) drives look like they’re actually Windows drives.  However, when you want to compile or link your application, you either need to go back to your telnet window and build it there, or you can download the RemoteBuild utility from the SynergyDE CodeExchange.  There are two versions for OpenVMS out there right now, both provided by Chris Blundell from United Natural Foods Inc.

Synergex PSG decided that we wanted to provide a remote build facility that could talk to multiple environments using information from a single Workbench project.  We wanted to minimize any potential firewall issues (for companies that have internal firewalls), and we also wanted to build on the SynPSG.System classes (distributed with ChronoTrack – our SPC 2009 demonstration application) for the network communication.  For those of you unfamiliar with the SynPSG.System classes, they are a partial implementation of the Microsoft System classes written in Synergy, (so they work on all supported platforms,) but when we have Synergy for .Net available, we'll be able to use the native .NET framework System class without modifying code. (ok, we'll have to change the import statements, but that should be all.)

So PSG has posted our flavor of a remote building application into CodeExchange – it's called remoteServer.   There is a client component to install into Workbench, and a server component (written in Synergy) that runs on each development server.  If you have both SAMBA (or equivalent) and remoteServer installed and configured, you are able to compile your application on the remote system, and in the unlikely event of a compile error (I know, you never have any coding errors) you will be able to double click on the error on the output window, and go straight to that line of code in the source file on your remote server.

If you work in a multi-platform development environment, I would encourage you to go download any of the remote build offerings in CodeExchange, and start using the power of Workbench to help improve the productivity of your developers.

Page 1 of 212

Subscribe to the RSS Feed!

Recent Posts Categories Tag Cloud Archives