Altova MapForce Server 2024 

Visual Basic .NET Example

Home Prev Top Next

The following example illustrates how to run a mapping execution file (.mfx) from VB.NET code. On Windows, the example files are available at the following path: C:\Program Files\Altova\MapForceServer2024\etc\Examples.



MapForce Server is installed and licensed

If you are creating a new Visual Studio project, add a reference to the MapForce Server assembly (see .NET Interface). You can skip this step if you are running the existing MapForce Server API example, because the example already references the MapForce Server assembly.

On the Build menu of Visual Studio, click Configuration Manager and set a correct build platform, for example Debug | x86  (or Debug | x64, if applicable). Do not use "Any CPU" as platform.

If you have installed MapForce Server 64-bit, then the application which calls the API (such as the sample one below) must also be built for the 64-bit platform in Visual Studio. Also, the path to the MapForce server executable must be adjusted accordingly in the code.


The example solution is in the "Program Files" directory, which requires administrative rights. Either run Visual Studio as administrator, or copy the solution to a different folder where you don't need administrative rights.


Running the mapping code

The code below runs three server execution files (.mfx). The table below lists the input files expected by each .mfx file, and the output that will be created after execution.


Execution file (.mfx)













If you have Altova MapForce, you can optionally take a look at the original mappings from which the .mfx files were compiled in order to understand them better. These are called TokenizeString1.mfd, SimpleTotal.mfd, and ClassifyTemperatures.mfd, respectively. You can find the mappings in the following directory: C:\users\<user>\Altova\MapForce2024\MapForceExamples.


The example below does the following:


It creates a new instance of Altova.MapForceServer.Server. This is the object you will subsequently be working with.

It sets a working directory where execution takes place. Input files are expected to exist in this directory if you referred to them using a relative path. Output files will also be created in this directory (see the table above).

It runs TokenizeString.mfx. The file path is supplied as argument to the Run method (notice that the path is relative to the working directory that was set previously). Upon successful execution, a .csv file representing the mapping output will be created in the working directory.

It runs SimpleTotal.mfx. Again, the file path is relative to the working directory. This mapping produces a string output, so we call the GetOutputParameter method to get the string output.

It runs ClassifyTemperatures.mfx. This mapping expects a parameter as input, which was supplied with the help of the AddParameter method.


Option Explicit On
Module Program
  Sub Main()
          'Create a MapForce Server object;
          Dim objMFS As Altova.MapForceServer.Server = New Altova.MapForceServer.Server
          'Set a working directory - used as a base for relative paths for the MapForce server execution (.mfx) file.
          'objMFS.WorkingDirectory = "C:\Program Files (x86)\Altova\MapForceServer2020\etc\Examples"
           objMFS.WorkingDirectory = "..\..\.."
          'Default path to the MapForce Server executable is the installation path (same dir with the MapForceServer.dll)
          'In case you moved the binaries on the disk, you need to explicitly set the path to the .exe file
          'objMFS.ServerPath = "C:\Program Files (x86)\Altova\MapForceServer2024\bin\MapForceServer.exe"
          'objMFS.ServerPath = "C:\Program Files\Altova\MapForceServer2024\bin\MapForceServer.exe"
          'Set global resource file and configuration, if your mapping uses global resources
          'objMFS.SetOption("globalresourcefile", "GlobalResources.xml") '"gr" can be used as short name for "globalresourcefile"
          'objMFS.SetOption("globalresourceconfig", "Config2") '"gc" can be used as short name for "globalresourceconfig"
          'An example with input and output paths stored inside the MFX file
          System.Console.WriteLine(vbCrLf & "Executing TokenizeString.mfx...")
          If (objMFS.Run("TokenizeString.mfx")) Then
              System.Console.WriteLine("Successfully generated file 'AltovaToolFeatures.csv'.")
              'execution failed. maybe no write permissions in working directory? Run this program as administrator.
          End If
          'An example creating a simple output so that we can retrieve the result explicitly
          System.Console.WriteLine(vbCrLf & "Executing SimpleTotal.mfx...")
          If (objMFS.Run("SimpleTotal.mfx")) Then
              System.Console.WriteLine("Mapping result is: " & objMFS.GetOutputParameter("total"))
              'execution failed (e.g. somebody deleted file ipo.xml)
          End If
          'an example with parameterized input
          ' the default of 'lower=5' gets changed to the value '10'
          ' mfx reads file Temperatures.xml and writes its output to Temperatures_out.xml.
          System.Console.WriteLine(vbCrLf & "Executing ClassifyTemperatures.mfx with parameter 'lower' set to '10' ...")
        objMFS.AddParameter("lower", "10")
          If (objMFS.Run("ClassifyTemperatures.mfx")) Then
              System.Console.WriteLine("File Temperatures_out.xml has been written successfully.")
              'execution failed. maybe no write permissions in working directory? Run this program as administrator.
          End If
       Catch ex As Exception
          System.Console.WriteLine("Internal Error - " & ex.Message())
      End Try
  End Sub
End Module

© 2018-2024 Altova GmbH