9.2.2 API with C#

This section explains how to use the API with C# in Microsoft Visual Studio. A working knowledge of both the language and IDE are expected from the reader. As all required SOAP libraries and tools are in place by default with Visual Studio, it is considerable easier to get started with the MetaEdit+ API in C# than many other languages. Our example here was carried out in the professional version of Visual Studio but should work also with the free Visual Express version.

The C# implementation of our example – explained in the previous section – is presented in Listing 1:

01 using System;
02
03 namespace APIExampleApp
04 {
05   class APIExampleApp
06   {
07     static void Main()
08     {
09       MetaEditAPIPortTypeClient meServer = null;
10       METype graphType = new METype();
11       MEOop[] graphs = null;
12       METype objectType = new METype();
13       MEAny[] props = new MEAny[1];
14       MEAny[] values = new MEAny[1];
15       MEAny area, np;
16       MEAny newObjectAny = new MEAny();
17       MEOop newObject = new MEOop();
18       MEOop[] diagrams = null;
19       MEAny place = new MEAny();
20       MEAny nullAny = new MEAny();
21       MEAny textAny = new MEAny();
22
23       meServer = new MetaEditAPIPortTypeClient();
24
25       graphType.name = "WatchFamily";
26       try
27       {
28         graphs = meServer.allGoodInstances(graphType);
29       }
30       catch (Exception ex) { Console.WriteLine(ex.Message); Environment.Exit(1); }
31       if (graphs.Length == 0) Environment.Exit(2); // No WatchFamily graphs found
32       objectType.name = "Note [Watch]";
33       nullAny.meType = "MENull";
34       nullAny.meValue = "";
35       props[0] = nullAny;
36       textAny.meType = "Text";
37       textAny.meValue = "'A new note created by the API'";
38       values[0] = textAny;
39       np = area = nullAny;
40       try
41       {
42         newObjectAny = meServer.instProps(objectType, props, values, np, area);
43       }
44       catch (Exception ex) { Console.WriteLine(ex.Message); Environment.Exit(1); }
45       if (newObjectAny.meType != "MEOop") Environment.Exit(3); // Object not created
46       string[] tokens = newObjectAny.meValue.Split('_');
47       newObject.areaID = Convert.ToInt32(tokens[0]);
48       newObject.objectID = Convert.ToInt32(tokens[1]);
49       try
50       {
51         meServer.addToGraph(newObject, graphs[0]);
52       }
53       catch (Exception ex) { Console.WriteLine(ex.Message); Environment.Exit(1); }
54       try
55       {
56         diagrams = meServer.diagrams(graphs[0]);
57       }
58       catch (Exception ex) { Console.WriteLine(ex.Message); Environment.Exit(1); }
59       if (diagrams.Length == 0) Environment.Exit(4); // No existing diagrams found
60       place.meType = "Point";
61       place.meValue = "400,360";
62       try
63       {
64         meServer.addNewObjectRepFor(diagrams[0], newObject, 0, place);
65       }
66       catch (Exception ex) { Console.WriteLine(ex.Message); Environment.Exit(1); }
67       try
68       {
69         meServer.animate(graphs[0], newObject);
70       }
71       catch (Exception ex) { Console.WriteLine(ex.Message); Environment.Exit(1); }
72     }
73   }
74 }

Listing 1. Sample C# application using the API.

Lines 1-8 provide the usual C# header of imports and class and main method definition. After that, lines 9-21 contain the definitions of variables and line 23 initializes the connection to the MetaEdit+ API server. Steps 1 and 2 of the example are taken care of in lines 25–31: assign the string “WatchFamily” to graphType, pass that as parameter to allGoodInstances, store the returned graphs into the graphs array and check if everything went ok. Lines 32–39 prepare for calling instProps which is then carried out – with checks – in lines 40–45. The resulting newObjectAny is tokenized and newObject created in lines 46–48. Lines 49–53 add the newObject into the ‘WatchModels’ graph and lines 54–66 take care of adding the new representation to the respective diagram. Opening the graph and highlighting the newly-created Note object happens in lines 67-70.

To compile and try out the example, follow the instructions below:

1)	Save the WSDL file from the MetaEdit+ API Tool as `MetaEdit.wsdl` in an appropriate directory.
2)	Start a Visual Studio command prompt in that directory and create the SOAP library DLL by running the following commands:

SvcUtil /t:code MetaEdit.wsdl
csc /target:library /out:MetaEditAPI.dll MetaEditAPI.cs

3)	Rename `output.config` as `APIExampleApp.exe.config`
4)	Start Visual Studio and create a new C# console application project called APIExampleApp.
5)	Add the code from Listing 1 to the project and save it as `APIExampleApp.cs`.
6)	Add `MetaEditAPI.dll` and System.ServiceModel and WindowsBase .NET references as references to the project.
7)	Add `APIExampleApp.exe.config` to the project on the same level as the `APIExampleApp.cs` file. Select the `APIExampleApp.exe.config` file in the project, select Properties from its popup menu, and set ‘Copy to Output Directory’ to be ‘Copy always’. (If you cannot complete this step, e.g. because of changes after Visual Studio 2010, a workaround is to copy the .config file alongside the resulting .exe after each build.)
8)	Run build.
9)	Start the MetaEdit+ API server from the API Tool, make sure the ‘WatchModels’ WatchFamily diagram is closed, and run `APIExampleApp.exe`. The ‘WatchModels’ diagram will open with the new Note object highlighted (as in Figure 9–2).