Aufruf der API
Um die MapForce COM API aufrufen zu können, muss in Ihrer Applikation (oder Ihrem Skript) eine neue Instanz des Application-Objekts erstellt werden. Anschließend haben Sie über dieses Objekt durch Aufruf der benötigten Methoden und Eigenschaften (z.B. Erstellen eines neuen Dokuments, Öffnen eines vorhandenen Dokuments, Generieren von Mapping-Code usw.) Zugriff auf MapForce.
Voraussetzungen
Um das MapForce COM-Objekt in Ihrem Visual Studio-Projekt verfügbar zu machen, fügen Sie eine Referenz zur MapForce Typbibliotheksdatei (.tlb) hinzu. Die folgende Anleitung gilt für 2013, ist aber auch bei anderen Visual Studio-Versionen ähnlich:
1.Klicken Sie im Menü Projekt auf Verweis hinzufügen.
2.Klicken Sie auf Durchsuchen und wählen Sie die Datei MapForce.tlb im MapForce-Installationsordner aus.
Unter C:\Benutzer\<Benutzername>\Dokumente\Altova\MapForce2024\MapForceExamples\API\C# steht ein MapForce API-Beispiel-Client in C# zur Verfügung.
In Java steht die MapForce API über Java-COM Bridge-Bibliotheken zur Verfügung. Sie finden diese Bibliotheken im MapForce Installationsordner: C:\Programme (x86)\Altova\MapForce2023\JavaAPI (Beachten Sie, dass dieser Pfad gilt, wenn ein 32-Bit-MapForce auf 64-Bit-Windows ausgeführt wird. Passen Sie den Pfad andernfalls entsprechend an).
•AltovaAutomation.dll: ein JNI Wrapper für Altova Automation Server
•AltovaAutomation.jar: Java-Klassen für den Zugriff auf Altova Automation Server
•MapForceAPI.jar: Java-Klassen, die den Wrap für die MapForce Automatisch-Schnittstelle bilden
•MapForceAPI_JavaDoc.zip: eine Javadoc-Datei mit der Hilfe zur Java API
Um direkt vom Java-Code aus Zugriff auf den MapForce Automation Server zu erhalten, müssen sich die Bibliotheken im Java classpath befinden.
Unter C:\Benutzer\<Benutzername>\Dokumente\Altova\MapForce2024\MapForceExamples\API\Java steht ein MapForce API-Beispiel-Client in Java zur Verfügung.
In Skriptsprachen wie JScript oder VBScript kann das MapForce COM-Objekt über den Microsoft Windows Script Host aufgerufen werden (siehe https://msdn.microsoft.com/en-us/library/9bbdkx3k.aspx). Solche Skripts können mit einem Text-Editor geschrieben werden und müssen nicht kompiliert werden, da sie von dem mit Windows verpackten Windows Script Host ausgeführt werden. (Um zu überprüfen, ob der Windows Script Host ausgeführt wird, geben Sie in der Befehlszeile wscript.exe /? ein). Unter C:\Benutzer\<Benutzername>\Dokumente\Altova\MapForce2024\MapForceExamples\API\JScript steht ein MapForce API-Beispiel-Client in JScript zur Verfügung.
| Anmerkung: | Für die 32-Bit-Version von MapForce ist der registrierte Name oder der programmatische Identifier (ProgId) des COM-Objekts MapForce.Application. Für die 64-Bit-Version von MapForce ist der Name MapForce_x64.Application. Beachten Sie jedoch, dass das aufrufende Programm die CLASSES Registry-Einträge in seiner eigenen Registry Hive oder -Gruppe (32-Bit oder 64-Bit) aufruft. Wenn Sie daher Skripts über die Standardbefehlszeileneingabe und mit Windows Explorer auf einem 64-Bit-Windows-System ausführen, werden die 64-Bit-Registry-Einträge, welche auf die 64-Bit-Version von MapForce verweisen, aufgerufen. Wenn daher sowohl MapForce 32-Bit als auch die 64-Bit-Version installiert ist, ist eine spezielle Behandlung erforderlich, damit die 32-Bit-Version von MapForce aufgerufen wird. Angenommen, der Windows Skripting Host ist das aufrufende Programm, so gehen Sie folgendermaßen vor: |
1.Wechseln Sie in das Verzeichnis C:\Windows\SysWOW64.
2.Geben Sie in der Befehlszeile wscript.exe gefolgt vom Pfad zum gewünschten Skript ein, z.B:
wscript.exe "C:\Users\...\Documents\Altova\MapForce2024\MapForceExamples\API\JScript\start.js" |
Richtlinien
Es sollten in Ihrem Client Code die folgenden Richtlinien beachtet werden:
•Behalten Sie Referenzen auf Objekte nicht länger im Arbeitsspeicher, als notwendig. Wenn ein Benutzer zwischen zwei Calls Ihres Client eine Eingabe macht, besteht keine Garantie, dass diese Referenzen noch gültig sind.
•Denken Sie daran, dass bei einem Absturz Ihres Client Code Instanzen von MapForce möglicherweise noch im System verbleiben.
•Nähere Informationen, wie man lästige Fehlermeldungen vermeidet, finden Sie unter Behandlung von Fehlern.
•Geben Sie Referenzen explizit frei, wenn Sie Sprachen wie C++ verwenden.
Erstellen des Application-Objekts
Die Syntax zur Erstellung des Application-Objekts hängt von der Programmiersprache ab, wie in den Beispielen unten gezeigt:
C#
// Create a new instance of MapForce via its automation interface. |
Java
// Start MapForce as COM server. |
JScript
// Access a running instance, or create a new instance of MapForce. try { objMapForce = WScript.GetObject ("", "MapForce.Application"); // unhide application if it is a new instance objMapForce.Visible = true; } catch(err) { WScript.Echo ("Can't access or create MapForce.Application"); } |
VBA
' Create a new instance of MapForce. |
VBScript
' Access a running instance, or create a new instance of MapForce. |
Visual Basic
Dim objMapForce As MapForceLib.Application = New MapForceLib.Application |