After you install MapForce, an example MapForce API client project for C# is available in the directory C:\Users\<username>\Documents\Altova\MapForce2024\MapForceExamples\API.
To compile and run the example, open the solution .sln file in Visual Studio and run Debug | Start Debugging or Debug | Start Without Debugging.
Note: | If you have a 64-bit operating system and are using a 32-bit installation of MapForce, add the x86 platform in the solution's Configuration Manager and build the sample using this configuration. A new x86 platform (for the active solution in Visual Studio) can be created in the New Solution Platform dialog (Build | Configuration Manager | Active solution platform | <New…>). |
When you run the example, a Windows form is displayed, containing buttons that invoke basic MapForce operations:
•Start MapForce
•Create a new mapping design
•Open the CompletePO.mfd file from the ...\MapForceExamples folder (note that you may need to adjust the path to point to the \MapForceExamples folder on your machine)
•Generate C# code in a temp directory
•Shut down MapForce
Code listing
The listing is commented for ease of understanding. The code essentially consists of a series of handlers for the buttons in the user interface shown above.
using System; using System.Collections.Generic; using System.ComponentModel; using System.Data; using System.Drawing; using System.Linq; using System.Text; using System.Windows.Forms; namespace WindowsFormsApplication2 { public partial class Form1 : Form { public Form1() { InitializeComponent(); } // An instance of MapForce accessed via its automation interface. MapForceLib.Application MapForce; // Location of examples installed with MapForce String strExamplesFolder; private void Form1_Load(object sender, EventArgs e) { } // handler for the "Start MapForce" button private void StartMapForce_Click(object sender, EventArgs e) { if (MapForce == null) { Cursor.Current = Cursors.WaitCursor; // if we have no MapForce instance, we create one a nd make it visible. MapForce = new MapForceLib.Application(); MapForce.Visible = true; // locate examples installed with MapForce. int majorVersionYear = MapForce.MajorVersion + 1998; strExamplesFolder = Environment.GetEnvironmentVariable("USERPROFILE") + "\\My Documents\\Altova\\MapForce" + Convert.ToString(majorVersionYear) + "\\MapForceExamples\\"; Cursor.Current = Cursors.Default; } else { // if we have already an MapForce instance running we toggle its visibility flag. MapForce.Visible = !MapForce.Visible; } } // handler for the "Open CompletePO.mfd" button private void openCompletePO_Click(object sender, EventArgs e) { if (MapForce == null) StartMapForce_Click(null, null); // Open one of the sample files installed with the product. MapForce.OpenDocument(strExamplesFolder + "CompletePO.mfd"); } // handler for the "Create new mapping" button private void newMapping_Click(object sender, EventArgs e) { if (MapForce == null) StartMapForce_Click(null, null); // Create a new mapping MapForce.NewMapping(); } // handler for the "Shutdown MapForce" button // shut-down application instance by explicitly releasing the COM object. private void shutdownMapForce_Click(object sender, EventArgs e) { if (MapForce != null) { // allow shut-down of MapForce by releasing UI MapForce.Visible = false; // explicitly release COM object try { while (System.Runtime.InteropServices.Marshal.ReleaseComObject(MapForce) > 0) ; } finally { // avoid later access to this object. MapForce = null; } } } // handler for button "Generate C# Code" private void generateCppCode_Click(object sender, EventArgs e) { if (MapForce == null) listBoxMessages.Items.Add("start MapForce first."); // COM errors get returned to C# as exceptions. We use a try/catch block to handle them. try { MapForceLib.Document doc = MapForce.ActiveDocument; listBoxMessages.Items.Add("Active document " + doc.Name); doc.GenerateCHashCode(); } catch (Exception ex) { // The COM call was not successful. // Probably no application instance has been started or no document is open. MessageBox.Show("COM error: " + ex.Message); } } delegate void addListBoxItem_delegate(string sText); // called from the UI thread private void addListBoxItem(string sText) { listBoxMessages.Items.Add(sText); } // wrapper method to allow to call UI controls methods from a worker thread void syncWithUIthread(Control ctrl, addListBoxItem_delegate methodToInvoke, String sText) { // Control.Invoke: Executes on the UI thread, but calling thread waits for completion before continuing. // Control.BeginInvoke: Executes on the UI thread, and calling thread doesn't wait for completion. if (ctrl.InvokeRequired) ctrl.BeginInvoke(methodToInvoke, new Object[] { sText }); } // event handler for OnDocumentOpened event private void handleOnDocumentOpened(MapForceLib.Document i_ipDocument) { String sText = ""; if (i_ipDocument.Name.Length > 0) sText = "Document " + i_ipDocument.Name + " was opened!"; else sText = "A new mapping was created."; // we need to synchronize the calling thread with the UI thread because // the COM events are triggered from a working thread addListBoxItem_delegate methodToInvoke = new addListBoxItem_delegate(addListBoxItem); // call syncWithUIthread with the following arguments: // 1 - listBoxMessages - list box control to display messages from COM events // 2 - methodToInvoke - a C# delegate which points to the method which will be called from the UI thread // 3 - sText - the text to be displayed in the list box syncWithUIthread(listBoxMessages, methodToInvoke, sText); } private void checkBoxEventOnOff_CheckedChanged(object sender, EventArgs e) { if (MapForce != null) { if (checkBoxEventOnOff.Checked) MapForce.OnDocumentOpened += new MapForceLib._IApplicationEvents_OnDocumentOpenedEventHandler(handleOnDocumentOpened); else MapForce.OnDocumentOpened -= new MapForceLib._IApplicationEvents_OnDocumentOpenedEventHandler(handleOnDocumentOpened); } } } } |