Altova MapForce Server 2024 Advanced Edition

Navigation: MapForce Server API > .NET Interface

C# Example

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

Prerequisites

•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)	Input	Output
TokenizeString.mfx	AltovaTools.xml	AltovaToolsFeatures.csv
SimpleTotal.mfx	ipo.xml	String
ClassifyTemperatures.mfx	Temperatures.xml	Temperatures_out.xml

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.

namespace MapForceServerAPI_sample
{
class Program
{
static void Main(string[] args)
{
try
{
// Create a MapForce Server object
Altova.MapForceServer.Server objMFS = new Altova.MapForceServer.Server();

// Set a working directory - used as a base for relative paths (you may need to adapt the path to the installation folder)
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\\MapForceServer2020\\bin\\MapForceServer.exe";
// objMFS.ServerPath = "C:\\Program Files\\Altova\\MapForceServer2020\\bin\\MapForceServer.exe";

System.Console.WriteLine("Running " + objMFS.ProductNameAndVersion + ".\");

// 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", "Default" ); // "gc" can be used as short name for "globalresourceconfig"

// ----------------------------------------------------------------------------------
// An example with input and output paths stored inside the MFX file
System.Console.WriteLine("\Executing TokenizeString.mfx...");
if (objMFS.Run("TokenizeString.mfx"))
System.Console.WriteLine("Successfully generated file 'AltovaToolFeatures.csv'.");
else
{
// execution failed. maybe no write permissions in working directory? Run this program as administrator.
System.Console.WriteLine(objMFS.LastExecutionMessage);
}

// ----------------------------------------------------------------------------------
// An example creating a simple output so that we can retrieve the result explicitly
System.Console.WriteLine("\Executing SimpleTotal.mfx...");
if (objMFS.Run("SimpleTotal.mfx"))
System.Console.WriteLine("Mapping result is: " + objMFS.GetOutputParameter("total"));
else
{
// execution failed (e.g. somebody deleted file ipo.xml)
System.Console.WriteLine(objMFS.LastExecutionMessage);
}

// ----------------------------------------------------------------------------------
// 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("\Executing ClassifyTemperatures.mfx with parameter 'lower' set to '10' ...");
objMFS.AddParameter("lower", "10");
if (objMFS.Run("ClassifyTemperatures.mfx"))
System.Console.WriteLine("File Temperatures_out.xml has been written successfully.");
else
{
// execution failed. maybe no write permissions in working directory? Run this program as administrator.
System.Console.WriteLine(objMFS.LastExecutionMessage);
}
}
catch (System.Runtime.InteropServices.COMException ex)
{
System.Console.WriteLine("Internal Error - " + ex.Message);
}
}
}
}