Altova MapForce Server 2024 Advanced Edition

Beispiel: Ausführen eines Mappings mit Parametern

In diesem Beispiel wird gezeigt, wie Sie ein MapForce-Mapping zu einer MapForce Server-Ausführungsdatei (.mfx) kompilieren und diese über die MapForce API ausführen. Im Beispiel wird ein Szenario beschrieben, in dem der Name der Input-Datei im Mapping als Parameter verwendet wird. Siehe dazu auch die vorherigen Beispiele zu C#, C++, VB.NET, VBScript oder Java.

In diesem Beispiel wird zur Anzeige und zum Verständnis des ursprünglichen Mapping-Designs MapForce verwendet. Das Mapping wird mit MapForce zu einer MapForce Server Ausführungsdatei (.mfx) kompiliert. Auch Einstellungen wie relative anstelle von absoluten Pfaden werden in MapForce vorgenommen.

Die in diesem Beispiel verwendete Server-Plattform ist Windows. Es könnte sich hierbei entweder um denselben Rechner handeln, auf dem auch MapForce installiert ist, oder um einen anderen. Sie können dieses Beispiel auch auf einem Linux- oder Mac-Rechner (in Java) ausführen, vorausgesetzt, Sie passen die Windows-Pfade an Ihre jeweilige Plattform an.

Voraussetzungen

Für die Ausführung dieses Mappings gelten dieselben Voraussetzungen wie für die zuvor beschriebenen Beispiele für C#, C++, VB.NET, VBScript oder Java.

Vorbereiten von Mappings für die Server-Ausführung

Nachdem Sie MapForce installiert und zum ersten Mal gestartet haben, steht eine Reihe von Demo-Mapping-Design-Dateien unter dem folgenden Pfad zur Verfügung:

C:\Benutzer\<Benutzername>\Dokumente\Altova\MapForce2024\MapForce Examples

Der obige Pfad muss entsprechend geändert werden, wenn Sie eine andere Version vom MapForce haben.

Das in diesem Beispiel verwendete Mapping-Design hat den Namen FileNamesAsParameters.mfd. Wie Sie in der Abbildung unten sehen, handelt es sich hierbei um ein einfaches Mapping, in dem Daten beinahe unverändert aus einer XML-Quelldatei in eine XML-Zieldatei kopiert werden. Nur die Felder PrimaryKey und Name der XML-Zieldatei werden mit Konstanten aus dem Mapping befüllt.

FileNamesAsParameters.mfd

Das Mapping hat zwei Input-Parameter: InputFileName und OutputFileName. Damit in MapForce eine Vorschau auf das Mapping angezeigt werden kann, werden die Parameterwerte durch zwei Konstanten bereitgestellt. Wie weiter unten beschrieben, haben Sie die Möglichkeit, die Parameterwerte bei Ausführung des Mappings mit MapForce Server durch Ihre eigenen zu ersetzen.

Beachten Sie, dass der Dateiname laut Konfiguration sowohl für die Quell- als auch für die Zielkomponente des Mappings dynamisch aus dem Mapping abgerufen wird. In der obersten Zeile der Komponente steht dazu ein Datei <dynamisch> Input-Konnektor zur Verfügung, über den Daten aus dem entsprechenden Mapping-Parameter (InputFileName oder OutputFileName) ausgelesen werden. Sie können diese Option in MapForce durch Klicken auf die Schaltfläche Datei/String in der rechten oberen Ecke der Komponente definieren oder ändern. Beachten Sie, dass der als Parameter bereitgestellte Input-Dateiname eine physische XML-Datei, die die Input-Daten für das Mapping enthält (in diesem Beispiel Altova_Hierarhical.xml, aus demselben Ordner wie die Mapping-Design-Datei) referenzieren muss. Der Ausgabedateiname kann jeder gültige Name sein, z.B. Output.xml.

Bevor Sie das Mapping zu einer MapForce Server Ausführungsdatei (.mfx) kompilieren, sollten Sie normalerweise die Mapping-Einstellungen überprüfen. Klicken Sie mit der rechten Maustaste in einen leeren Bereich des Mappings und wählen Sie im Kontextmenü den Befehl Mapping-Einstellungen.

Ändern Sie die Einstellungen für dieses Beispiel wie oben gezeigt. Beachten Sie vor allem, dass alle absoluten Pfade zu im Mapping verwendeten Input- oder Output-Dateien relativ zur Mapping-Design-Datei (.mfd) aufgelöst werden, wenn Sie das Kontrollkästchen Pfade im generierten Code absolut machen deaktivieren. MapForce Server sucht zur Laufzeit im Arbeitsverzeichnis des Programms nach diesen Pfaden. Welches Standard-Arbeitsverzeichnis verwendet wird, hängt von der Plattform ab, über die Sie die MapForce Server API aufrufen. Im Fall einer C#-Applikation ist es dasselbe Verzeichnis wie das der ausführbaren Datei. Außerdem können Sie, wie weiter unten gezeigt, das Arbeitsverzeichnis mit Hilfe einer API-Eigenschaft namens WorkingDirectory (oder gegebenenfalls der Java-Methode setWorkingDirectory) ändern.

Anmerkungen:

•Im Dialogfeld "Mapping-Einstellungen" sind die einzigen Einstellungen, die sich direkt auf die Kompilierung der .mfx-Datei auswirken Pfade im generierten Code absolut machen und Zeilenenden.

•In diesem Mapping war es nicht notwendig, die einzelnen Mapping-Komponenten in MapForce zu bearbeiten, um absolute Pfade in relative zu ändern, da alle Pfade bereits relativ waren. Falls dies nicht der Fall ist, müssten Sie diesen zusätzlichen Schritt ebenfalls durchführen, siehe Vorbereiten von Mappings für die Server-Ausführung.

In diesem Beispiel wird das Verzeichnis C:\MappingExample als Arbeitsverzeichnis verwendet. Kopieren Sie daher die vom Mapping referenzierte Input-Datei Altova_Hierarchical.xml von C:\Benutzer\<Benutzername>\Dokumente\Altova\MapForce2024\MapForceExamples in das Arbeitsverzeichnis.

Sowohl bei der Quell- als auch bei der Zieldatei in diesem Beispiel handelt es sich um XML-Dateien. Die XML-Schema-Datei ist auf dem Server nicht vonnöten, da die Informationen daraus bei der Kompilierung in die .mfx-Datei eingebettet wurden. Wenn in Ihrem Mapping andere Komponententypen (z.B. Datenbanken) verwendet werden, gelten allenfalls zusätzliche Voraussetzungen, wie unter Vorbereiten von Mappings für die Server-Ausführung beschrieben.

Um das Mapping schließlich zu einer Server-Ausführungsdatei zu kompilieren, gehen Sie folgendermaßen vor:

•Klicken Sie im Menü Datei auf den Befehl Zu MapForce Server-Ausführungsdatei kompilieren und wählen Sie ein Zielverzeichnis aus. Das Zielverzeichnis ist in diesem Beispiel dasselbe wir das Arbeitsverzeichnis, nämlich C:\MappingExample.

In den folgenden Codefragmenten wird gezeigt, wie Sie das Mapping über die MapForce Server API von verschiedenen Umgebungen aus ausführen. Beachten Sie, dass beide Parameter in den unten stehenden Codefragmenten durch denselben Namen, den sie auch im Mapping-Design haben, referenziert werden. Außerdem hat der Parameterwert denselben Datentyp, der auch im Mapping definiert ist (in diesem Fall String).

Ausführen des Mappings über C++

Sie können die .mfx-Datei nun mit C++-Code, wie dem unten gezeigten, ausführen. Um diesen Code erfolgreich ausführen zu können, stellen Sie sicher, dass MapForce Server eine gültige Lizenz hat, siehe auch CLI-Befehl verifylicense.

C++

#include <iostream>
#include "atlbase.h"

// 32-bit MapForce Server
#import "progid:MapForce.Server"

int _tmain(int argc, _TCHAR* argv[])
{
CoInitialize( NULL );

try
{
//Create a MapForce Server object
MapForceServerLib::IServerPtr pMFS;
CoCreateInstance( __uuidof( MapForceServerLib::Server ), NULL, CLSCTX_ALL, __uuidof( MapForceServerLib::IServer ), reinterpret_cast< void** >( &pMFS ) );

//Set a working directory - used as a base for relative paths
pMFS->WorkingDirectory = "C:\\MappingExample";

//Prepare the parameters
pMFS->AddParameter("InputFileName", "Altova_Hierarchical.xml");
pMFS->AddParameter("OutputFileName", "Output.xml");

//Run the mapping
if (pMFS->Run("FileNamesAsParameters.mfx"))
std::cout << "Success - finished execution" << std::endl;
else
std::cout << pMFS->LastExecutionMessage << std::endl;

}
catch (_com_error& err )
{
BSTR bstrMessage;
(err).ErrorInfo()->GetDescription( &bstrMessage );
std::cout << "Exception occurred: " << _com_util::ConvertBSTRToString( bstrMessage ) << std::endl;

}

CoUninitialize();
return 0;

}

Ausführen des Mappings über C#

Sie können die .mfx-Datei nun mit C#-Code, wie dem unten gezeigten, ausführen. Um diesen Code erfolgreich ausführen zu können, fügen Sie zuerst in Visual Studio eine Referenz zur MapForce Server DLL hinzu, wie unter .NET-Schnittstelle beschrieben, und vergewissern Sie sich, dass MapForce Server eine gültige Lizenz hat, siehe auch CLI-Befehl verifylicense.

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

// Set the working directory - all relative paths will be resolved against it
objMFS.WorkingDirectory = "C:\\MappingExample";

//Prepare the parameters
objMFS.AddParameter("InputFileName", "Altova_Hierarchical.xml");
objMFS.AddParameter("OutputFileName", "Output.xml");

//Run the mapping
if (objMFS.Run("FileNamesAsParameters.mfx"))
System.Console.WriteLine("Success - finished execution");
else
System.Console.WriteLine(objMFS.LastExecutionMessage);
}
catch(System.Runtime.InteropServices.COMException ex)
{
System.Console.WriteLine("Internal Error: " + ex.Message);
}
}

Ausführen des Mappings über Java

Sie können die .mfx-Datei nun mit Java-Code, wie dem unten gezeigten, ausführen. Um dieses Codefragment erfolgreich ausführen zu können, stellen Sie sicher, dass:

•die Java-CLASSPATH-Umgebungsvariable eine Referenz zur MapForceServer.jar-Bibliothek enthält, wie unter Informationen zur Java-Schnittstelle beschrieben.

•MapForce Server eine gültie Lizenz hat, siehe auch CLI-Befehl verifylicense.

Java

public static void main(String[] args) {
try {
// Create a MapForce Server object
com.altova.mapforceserver.MapForceServer objMFS = new com.altova.mapforceserver.MapForceServer();

// Set the working directory - all relative paths will be resolved against it
// objMFS.setWorkingDirectory("/home/ubuntu/Downloads/MappingExample");
objMFS.setWorkingDirectory("C:\\MappingExample");

// Add the mapping parameters
objMFS.addParameter("InputFileName", "Altova_Hierarchical.xml");
objMFS.addParameter("OutputFileName", "Output.xml");

// Run the mapping
if ( objMFS.run( "FileNamesAsParameters.mfx" ) )
System.out.println( "Success - finished execution" );
else
System.out.println( objMFS.getLastExecutionMessage() );

} catch (Exception e) {
e.printStackTrace();
}

System.out.println("Finished execution");
}