Getting started with MetaEdit+ API and C#

While updating some of our testing code for MetaEdit+ API clients, I wrote the following short primer on how to get started with API in C#:

GETTING STARTED WITH METAEDIT+ API AND C#

The following example program was written in C# and employing the .NET framework and tools, using (mostly) .NET version v3.5. Please note that there seems to be a lot of compatibility issues between various .NET versions, especially how WSDL is translated and compiled and how things are named in the code generated from the WSDL, so changes are very likely required to get this example work in other versions.

In order to compile this example, you need .NET framework and SDK with SvcUtil.exe (to translate the WSDL as C#) and the C# compiler csc.exe. Before building the actual example code, you need first to export the MetaEdit+ API WSDL for your client and start the MetaEdit+ API server:

1) Login MetaEdit+ (select "Demo" repository and open the "Digital Watch" project)

2) From the Main Launcher select Repository | API Tool (or click the API Tool button in toolbar) -> API Tool opens

3) Press "Save WSDL" button and save MetaEditAPI.wsdl into the directory of your API client's source code

4) Press "Start Server" button to start the server. (If your firewall shows a query, choose to allow connections. MetaEdit+ listens for incoming TCP connections on port 6390 by default.)

Now your MetaEdit+ API is up and running, waiting for connection.

As the .wsdl file is just the SOAP interface definition in XML, you need to first compile it to a .cs and from there to a .dll, which is then linked with your client program. Working from the command line, execute the following commands (add paths if needed - e.g. C:\Program Files\Microsoft SDKs\Windows\v6.0A\bin\SvcUtil.exe and C:\WINDOWS\Microsoft.NET\Framework\v3.5\csc.exe):

SvcUtil.exe /t:code MetaEditAPI.wsdl

csc /target:library /out:MetaEditAPI.dll MetaEditAPI.cs

The compilation of MetaEditAPI.cs generates also a configuration file called output.config. Rename this file as APIClient.config and make a copy called APIClient.exe.config - some .NET/Windows versions look for one name, others for the other :-(.

Here then is the code listing for our little example program, APIClient.cs (follow the comments to figure out what it does):

using System;
using System.Net;
using System.IO;
using System.Text;
using System.Collections;
using System.Drawing;
using System.ComponentModel;
using System.Windows.Forms;
using System.Data;

public class APIClient
{
  public static int Main()
  {
    /// Set the variable and initialize connection to MetaEdit+ API
    MetaEditAPIPortTypeClient meServer = new MetaEditAPIPortTypeClient();

    /// Variable holding "2008Models" graph's oid 
    MEOop wModels = new MEOop();
    wModels.areaID = 22;
    wModels.objectID = 962;

    /// Tell MetaEdit+ API to open the "2008Models" diagram
    meServer.open(wModels);

    /// Variable holding the properties for "2008Models"
    MEOop[] wModelProps = meServer.allProperties(wModels);

    /// Temporary variable for holding property type
    METype propType = new METype();
    
    /// Temporary variable for holding property
    MEAny prop = new MEAny();

    /// Print out all information (name, type, value) of
    /// properties of "2008Models" graph
    for (int i=0; i<wModelProps.GetLength(0); i++)
    {
      propType = meServer.type(wModelProps[ i ]);
      prop = meServer.valueAt(wModels, i+1);
      Console.WriteLine("Property name: " + meServer.typeName(propType));
      Console.WriteLine("Property type: " + prop.meType);
      Console.WriteLine("Propery value: " + prop.meValue);
      Console.WriteLine("");
    }

    Console.WriteLine("==================");

    /// Variable for objects in "2008Models" graph
    MEOop[] objects = meServer.objectSet(wModels);

    /// Print out the type and first property value for
    /// each object in "2008Models" graph
    foreach(MEOop obj in objects)
    {
      Console.WriteLine("Object Type: " + meServer.typeName(meServer.type(obj)));
      Console.WriteLine("First property value: " + meServer.valueAt(obj, 1).meValue);
      Console.WriteLine("");
    }

    return 0;
  }
}

Compile this with the following command:

csc /out:APIClient.exe APIClient.cs /reference:MetaEditAPI.dll

When you run the resulting APIClient.exe, it should connect to the listening API server in MetaEdit+, open up the diagram for "2008Models" graph and print out all kinds of information about its content. Please note that it is not necessary to open the diagram in order to access the data within the graph - I just added that to show some more capabilities provided by the API.

The apparent advantage of C# is the easy setup when compared to C++ and Java that require additional libraries to be installed and present. With C#, you get a lot of "dirty work" covered by the .NET framework. Its draw-back is, of course, that it is Windows-only.

Hope this helps!

Rise

Edit January 14th 2011: Missing information added.

Edit June 3rd 2011, Steven Kelly: Added paths & info about name change to APIClient.exe.config

Edited by stevek - 03.Jun.2011 at 15:46