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:

image

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
  6.  
  7. namespace MyWcfServices
  8.  
  9.     {ServiceContract}
  10.     public interface IService1
  11.         
  12.         {OperationContract}
  13.         method GetData, string
  14.             required in val, int
  15.         endmethod
  16.         
  17.         {OperationContract}
  18.         method GetDataUsingDataContract, @CompositeType
  19.             composite, @CompositeType
  20.         endmethod
  21.         
  22.         ;;TODO: Add your service operations here
  23.         
  24.     endinterface
  25.     
  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
  6.  
  7. namespace MyWcfServices
  8.  
  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
  13.  
  14.         private mBoolValue, Boolean, true
  15.         private mStringValue, String, "Hello "
  16.         
  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
  28.         
  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
  40.  
  41.     endclass        
  42.  
  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
  6.  
  7. namespace MyWcfServices
  8.     
  9.     public class Service1 implements IService1
  10.         
  11.         public method GetData, String
  12.             required in val, int
  13.             endparams
  14.         proc
  15.             mreturn String.Format("You entered: {0}", val)
  16.         endmethod
  17.         
  18.         public method GetDataUsingDataContract, @CompositeType
  19.             composite, @CompositeType
  20.             endparams
  21.         proc
  22.             
  23.             if (composite==^null)
  24.                 throw new ArgumentNullException("composite")
  25.             
  26.             if (composite.BoolValue)
  27.                 composite.StringValue = composite.StringValue + "Suffix"
  28.             
  29.             mreturn composite
  30.             
  31.         endmethod
  32.         
  33.     endclass
  34.     
  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.


Lights, Camera, Action!

By Richard Morris, Posted on June 16, 2011 at 3:04 am

Now, thinking that once the Synergex Success Partner Conference (http://spc.synergex.com) is over, and we are all sat basking in the glory of the survey results (thanks to everyone who filled them in – the cheques are in the post!), sipping alcohol-free Pina Colada’s, you couldn’t be further from the truth.

Once the conference is over, that’s when the real work begins.  One of the first tasks if to begin the planning for next year’s conference – honestly.  It takes a full twelve months to plan, organise and deliver the SPC.  Reading the conference surveys helps us to first decide where to hold the conference.  Sometimes suggestions like “Somewhere sunny, but don’t tell the boss!” are not the most helpful.  Based on the feedback we receive we can also begin to sketch out a proposed agenda.  The agenda is also heavily influenced by future  developments which introduce new features and capabilities within the language – and there are some cool features in the pipeline so keep an eye on future blogs.

But before we can start next year’s planning, we need to complete the final tasks of this year’s conference, and that’s getting all the available information to everyone who attended.
The session slides have been posted on the Synergex web site.  All code samples are on the Synergex Code Exchange, and based on feedback from the Chicago conference I’ve created  videos for each of my conference presentations. So, light the lights check the sound levels and get the clapper board ready…

If you want to re-visit the User Interface opportunities presentation you can see a 20 minute video at

http://www.synergyde.com/services/education/product_video.aspx?video=ui_opportunities.

This video shows the evolution of a simple Synergy cell based program from the OpenVMS/UNIX cell based environment through the UI Toolkit, Windows and WPF, to a Native Synergy.NET desktop application.  The same Synergy logic is then utilised in a Silverlight Browser based client and finally a Windows Phone 7 app!

Giving your User Interface a “New Lick of Paint” is possible with Synergy and WPF.  There are two presentations on this subject, and really need to be viewed in order.  The first is “What, Why and How of MVVM” (http://www.synergyde.com/services/education/product_video.aspx?video=what_why_and_how_of_mvvm).  This video takes you through the basics of the Model, View, ViewModel design pattern and how to implement it within your existing Synergy applications.

The second video is called “Building Targeted UI’s” (http://www.synergyde.com/services/education/product_video.aspx?video=building_targeted_uis).  This builds on the first MVVM video and demonstrates what you can begin to achieve with your new Synergy based WPF applications.

My final SPC 2011 session was titled “Cool Framework Features”.  During the presentation I demonstrated some simple ways to enhance your existing applications with .NET
framework features, and there are two videos to show you how.  The “Cool Framework Features – PDF” (http://www.synergyde.com/services/education/product_video.aspx?video=cool_framework_features__pdf) video shows you how to fully automate the production of PDF documents using a printer driver called Win2PDF, the Synergy Windows Printing API, and the Synergy .NET API to set Windows Registry settings.

A second video from this session is called “Cool Framework Feature – XML” (http://www.synergyde.com/services/education/product_video.aspx?video=cool_framework_features__xml).  This video shows how to implement the .NET Validating XML parser into your Synergy applications to load, parse and
validate an XML document given a XML schema.

Take a look at the videos and let me know what you think.  If there are any subjects you’d like to see covered either at the SPC or even in video format please let me know.


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!!!


.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…


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!


What’s in my library?

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

The obvious answer that springs to mind is "books", but some may respond "what sort of library?".  Of course, in this context, I'm really referring to a library containing Synergy object code. 

When referring to Synergy subroutines and functions, on both Windows & Unix, you can perform a "listdbo" or "dblibr -t" on the object file/object library and peruse the output to see the names of your routines.  However, when referring to methods (in classes/namespaces), the name used is mangled.  This mangling process takes the fully qualified name of the method, the return type, and all the parameter types, and reduces it down to a mangled name.  In a lot of cases, you can look at the mangled name and stand a chance of actually recognizing the name of the routine, but decoding the parameters in your head may require the use of illegal drugs.

For example, if you see a mangled name of '7SYNPSG5CORE11UTILITIES3CC6SYNCC11GETCCNAME_O7SYSTEM7STRINGI', you could intuitively see that it's probably this routine: 'SYNPSG.CORE.UTILITIES.CC.SYNCC.GETCCNAME(I)@SYSTEM.STRING'. 

But what about this one: '7SYNPSG5CORE11UTILITIES3CC6SYNCC11GETCCNAME_O7SYSTEM7STRINGSP0P1P2P39CARDTYPE'?  It’s the "same" overloaded routine, but it has a SYNPSG.CORE.UTILITIES.CC.CARDTYPE parameter instead of an integer parameter.  Similarly, if you saw '7SYNPSG5CORE11UTILITIES8WORKING9SHOWFORM_XO7SYSTEM7STRING', you could probably see that it's 'SYNPSG.CORE.UTILITIES.WORKING.SHOWFORM(@SYSTEM.STRING)'.  Now, what if you saw this '7SYNPSGCR1UTLTESWRKNGSHW9HTGB13'?   Well, it's surprisingly the same SHOWFORM method, but it's been mangled beyond recognition.  The term used here at Synergex is "crushed".  In fact, if you have a crushed name, it's basically impossible to determine the original method name. If the mangled name of the method is too long for the environment, the mangled name is crushed down to the maximum size permissible.  OpenVMS has a limit of 31 characters, 64-bit systems have a 188 character limit, and 32-bit systems have a 200 character limit. Actually, the limit is one character less, because we use the rule that if the name is exactly the maximum size, it must be a crushed name.  As the last 7 characters of a crushed name is a checksum, on OpenVMS you’re only left with 24 characters for a human “readable” name.

So how, exactly, does a mangled name become a crushed name? Well, characters are removed, one by one, until the name is exactly the correct length. First non-alphanumeric characters are removed, then vowels, then letters from the name of your first born child, then random letters based on the cycle of the moon, until you eventually get a name that fits. So, with only 31 characters for method ames, the OpenVMS users out there will have to become accustomed to seeing crushed (i.e. indecipherable) method names inside Shared Image Libraries.  If you need to create an OpenVMS Shared image library, I would recommend creating an object library, and using the make_share.com file to convert to a shared image library.  However, you may need to review the use of the MATCH qualifier on your shared image libraries, as method names can change with the modification of a parameter (or return) type. So changing a method to (for example) have an additional optional parameter will cause a new method name to be created.  Unless you rebuild your application to see (and use) the new name, you could find that the application starts giving “routine not found” errors.

You might think that not knowing the name of the routine would be a problem – it's not really, because the compiler has a consistent supply of the same high quality drugs, and given a constant method signature, will always generate the same crushed name.  So it really doesn't care that that your code said  "object.showform(1)", because it'll know that you really want to call the method '7SYNPSGCR1UTLTESWRKNGSHW9HTGB13' from your library.

For most developers out there, the actual name of the method inside a library is unimportant, but I though the more curious of you out there would be interested in this.


RSS

Subscribe to the RSS Feed!

Recent Posts Categories Tag Cloud Archives