1
(Noch nicht bewertet)
30. Oktober 2015
DataOne Blog

Movilizer .net connector: Einführung

Dieser Artikel befasst sich mit dem generellen Aufbau des Connectors, seinen wichtigsten Basisfunktionen, der Konfiguration und dem Einbinden in ein Projekt. Dazu werden ein Verständnis der Movilizer-Systemarchitektur und grundlegende C#-Kenntnisse beim Leser vorausgesetzt. Zukünftige Artikel werden dann die konkrete Anwendung beispielsweise zum Generieren von Movelets oder zum Abrufen und Verarbeiten von Daten behandeln.


Der Movilizer .net-Connector bietet eine C#-Schnittstelle zum Ansteuern von Funktionalitäten des Movilizer-Frameworks. Damit lassen sich beispielsweise Movelets erstellen, versenden und löschen und von Movelets erzeugte Replies und Datencontainer abfragen und verarbeiten. Darüber hinaus stellt er Klassen bereit, die als Grundlage für einen Windows-Service zum automatisierten Laden und Bearbeiten von Daten aus der Movilizer-Cloud dienen.

Dieser Artikel befasst sich mit dem generellen Aufbau des Connectors, seinen wichtigsten Basisfunktionen, der Konfiguration und dem Einbinden in ein Projekt. Dazu werden ein Verständnis der Movilizer-Systemarchitektur und grundlegende C#-Kenntnisse beim Leser vorausgesetzt. Zukünftige Artikel werden dann die konkrete Anwendung beispielsweise zum Generieren von Movelets oder zum Abrufen und Verarbeiten von Daten behandeln.

Aufbau

Der Connector enthält eine Reihe von Klassen zur Interaktion mit dem Movilizer-Webservice. Einige davon sind für uns von besonderem Interesse:

  • MWS.Data.Manager: Der DataManager ist die Grundlage für die Kommuniktation mit dem Movilizer-Webservice. Er stellt Funktionen zum Versenden, Zuweisen, Entziehen und Löschen von Movelets und dem Hochladen und Löschen von Masterdaten und Dokumenten bereit, kann Aufrufe an den Webservice absetzen und dessen Antworten in einer im Programm verwendbaren Form zurückliefern.
  • MWS.Log.LogFactory: Die Log-Factory ist die zentrale Sammelstelle für sämtliche Info-, Warnungs- und Fehlerausgaben des Connectors und kann auch für eigene Ausgaben angesprochen werden. Sie schreibt standardmäßig in das Windows Event Log. Über ein spezielles Interface ist es möglich, weitere Ziele für die Ausgabe zu definieren und bei der LogFactory anzumelden.
  • MWS.WebService.MovilizerWebServiceV11Service.cs: In dieser Datei sind alle bei der Kommunikation verwendeten Klassen wie Movelets, Questions, Answers, Masterdaten, Replies, Datencontainer, usw. definiert.
  • MWS.Templates.(…): Im Templates-Package findet sich für die meisten der eben genannten Klassen ein passendes Template, das genutzt werden kann, um z.B. ein einmal zur Laufzeit erstelltes Movelet für wiederholte Verwendung zwischenzuspeichern.

Natürlich enthält er Connector noch eine Vielzahl weiterer Klassen. Diese werden aber normalerweise nicht benötigt.

Genereller Kommunikationsablauf

Zur Kommunikation mit dem Web-Service nutzen wir die MWS.Data.Manager-Klasse. Diese besteht im Grunde genommen aus einer Reihe von Warteschlangen zum Erstellen, Ändern und Löschen von Movelets, Masterdaten und Dokumenten. Der Manager ist eine abstrakte Klasse, die bereits Methoden zum Einreihen von Anfragen in diese Wartschlangen enthält. Die Methode für die Verarbeitung ist jedoch nur abstrakt definiert und muss jeweils individuell implementiert werden. Dies soll in einem späteren Beitrag noch genauer beschrieben werden. An dieser Stelle ist für uns vor allem der allgemeine Ablauf eines solchen „Service Cycle“ interessant:

  1. Einlesen der Konfiguration für die Verbindung zum Web-Service
  2. Versenden aller gesammelten Anfragen an den Web-Service
  3. Empfangen und Bearbeiten der Antwort des Webservices

Hierbei ist besonders zu beachten, dass die Antwort des Webservices alle Nachrichten, Datencontainer und Replies enthält, die sich seit dem letzten Service Cycle auf der Cloud angesammelt haben. Das hat verschiedene Konsequenzen: Da die Daten nach dem Abruf durch den Connector aus der Cloud dort nicht mehr zur Verfügung stehen, muss der Manager in der Lage sein, alle verschiedenen Formate behandeln zu können – andernfalls geht der Zugriff darauf an dieser Stelle verloren und sie können nur noch manuell über das Portal angesehen werden. Ebenso muss diese Verarbeitung nach jedem Aufruf des Webservices über den Manager stattfinden, unabhängig davon, wo dieser im Programm stattfindet.

Einbinden in ein Projekt

In dieser Einführung verwenden wir Visual Studio als Entwicklungsumgebung. Dort erstellen wir eine neue Projektmappe über das Menü „Datei > Neues Projekt“.

Movilizer net connector Einfuehrung 1

Den Connector in der aktuellen Version 2.1.1 können wir uns aus Movilizer Confluence unter folgendem Link herunterladen:https://devtools.movilizer.com/confluence/display/DOC21/Download+Movilizer+Windows+Service+2.1.1

Movilizer net connector Einfuehrung 2

Wir entpacken das heruntergeladene Archiv und kopieren den Unterordner „NET_FWK_MovilizerWindowsService“ in unseren Projektordner. Nach einem Klick auf den Menüpunkt „Datei > Hinzufügen > Vorhandenes Projekt“ wählen wir das Visual-Studio-Projekt „NET_FWK_MovilizerWindowsService\NET_FWK_MovilizerWindowsService.csproj“. Dessen Dateien werden nun zu unserer Projektmappe hinzugefügt.

Movilizer net connector Einfuehrung 3

Damit wir sie nutzen können, erstellen wir in der Mappe ein weiteres Projekt (Windows Forms) und verknüpfen es mit dem Connector über einen Rechtsklick auf das Objekt „Verweise“ in diesem neuen Projekt.

Movilizer net connector Einfuehrung 4

Wenn wir das Projekt jetzt erstellen, wird der Connector als DLL in das Ausgabeverzeichnis unseres Projektes kompiliert.

Konfiguration

Bevor wir den Connector nutzen können, müssen wir sowohl auf dem Rechner, mit dem wir entwickeln, als auch auf dem, auf dem unsere Lösung später laufen soll, die Verbindungsdaten der zu nutzenden Cloud in die Registry eintragen. Dies funktioniert am einfachsten über die Datei „MovilizerWebService.reg“, die ebenfalls in dem Archiv enthalten ist. Wir öffnen sie mit einem normalen Texteditor (z.B. notepad) zum Bearbeiten und passen die Werte bei „Web Service Host“, „System ID“ und „System Password“ entsprechend an. Der Schlüssel „Service Time Interval“ erlaubt uns außerdem zu bestimmen, in welchem Rhythmus (in Millisekunden) die Service Cycles ausgeführt werden sollen, wenn der Connector im Rahmen eines periodisch ablaufenden Windows Services verwendet wird.

Movilizer net connector Einfuehrung 5

Danach lesen wir die Konfiguration durch Doppelklick auf die Datei im Explorer in die Registry ein. Der Connector liest sie dort automatisch aus und verwendet sie zur Verbindung mit der Movilizer-Cloud.

Zusammenfassung

Wir sind nun so weit, dass wir den Connector in unserem Projekt verwenden können. Wie dies genau geht, wird in den kommenden Beiträgen genauer erläutert werden.

Ich freue mich auf Ihr Feedback!


Introduction

The Movilizer .net connector exposes an interface for accessing functions of the Movilizer framework from C#-based applications – e.g. to create, send and delete Movelets and to receive and work through replies and data containers. It also contains classes that serve as boilerplate code for a Windows service that automatically pulls data collected on the Movilizer cloud and processes it.

This article gives you an introduction to the general architecture of the connector, its basic functionalities, configuration and integration into a project. In doing so, working knowledge of the Movilizer system architecture and C# is assumed. Future articles will explain the actual development, e.g. in order to generate movelets or to download and process data.

Structure of the connector

The connector consists of a collection of classes that allow you to easily interact with the Movilizer web service. Some of them are of special interest for us:

  • MWS.Data.Manager: The data manager lays the foundation for the communication with the Movilizer web service by providing methods to send, assign and delete movelets, upload and delete master data and documents, post requests to the web service and convert its responses to the corresponding .net objects.
  • MWS.Log.LogFactory: The log factory collects every info, warning and error message issued by the connector. It can be used for your own output as well. By default, the factory writes the messages to the Windows event log, but it also offers an interface to define your own destinations.
  • MWS.WebService.MovilizerWebServiceV11Service.cs: This file contains all necessary classes – movelets, questions, answers, master data, replies, data containers and more.
  • MWS.Templates.(…): For most of the aforementioned classes, there exists a corresponding template that can be used e.g. in order to store a movelet generated during runtime for repeated use.

Of course there are lots of other classes, but they are usually not needed.

Web service access

We rely on the MWS.Data.Manager class to handle the communication with the Movilizer web service. Basically, it consists of several queues to create, change and delete movelets, master data and documents. The manager is an abstract class that already comes with methods to manipulate these queues, whereas the actual processing needs to be implemented manually. This will be explained in greater detail later on – for now, we will have a look at how these so-called “service cycles” proceed in general:

  1. Read the configuration data for the web service connection
  2. Send the collected requests to the web service
  3. Receive and process the web service’s responses

At this point, it is important to know that the response contains every message, data container and reply delivered to the cloud since the last service cycle. Since the data can be pulled from the cloud only once, the manager is required to handle all these different data formats – even those not relevant for our application. After that, they can only be accessed manually using the portal. This also means that the processing has to be done every single time we call the web service, no matter when and where it happens.

Linking the connector to a project

We use Visual Studio as our IDE in this tutorial. To begin, create a new solution using the “File > New solution” menu item.

Movilizer net connector Einfuehrung 6

The next thing you need is the Movilizer .net connector, which is available from Movilizer Confluence under the following link: https://devtools.movilizer.com/confluence/display/DOC21/Download+Movilizer+Windows+Service+2.1.1

Movilizer net connector Einfuehrung 7

Download and extract the archive and copy the subfolder “NET_FWK_MovilizerWindowsService” into the solution folder. Now you can import the connector into the project by navigating to “File > Add > Existing project” and selecting file “NET_FWK_MovilizerWindowsService\NET_FWK_ MovilizerWindowsService.csproj“. After that, the connector’s source files appear in the solution explorer.

Movilizer net connector Einfuehrung 8

To use them, create a new project and link the connector to that project by right-clicking on its “References” item.

Movilizer net connector Einfuehrung 9

Whenever we build the project, Visual Studio will generate a DLL file containing the connector and place it in the project’s output folder.

Configuration

Finally, the connector needs to know the web service’s URL and the connection credentials. They are read from the registry every time a service cycle is executed. To add them to the registry, open the file “MovilizerWebService.reg”, which is also included in the archive, with any text editor and change the values for “Web Service Host”, “System ID” and “System Password” according to your setup. Besides, the key “Service Time Interval” enables you to specify the duration of the intervals (milliseconds) in which the service cycle will be run if the connector is used as a part of a periodically working Windows service.

Movilizer net connector Einfuehrung 10

Save the changes and store the keys in the registry by double-clicking on the file in the Windows Explorer.

Conclusion

You are now ready to use the connector in the project. This will be explained in future articles.

I am looking forward to your feedback!

Ein Gedanke zu „Movilizer .net connector: Einführung“

Schreiben Sie einen Kommentar

Ihre E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.