Anlage 6 - Schnittstelle VIS - VAPI-.NET_Konfiguration.pdf

[Seite 1]

VIS VAPI-.NET

Konfiguration

Version: 6.5

Stand: 28. März 2024

[Seite 2]

© Copyright by PDV GmbH Haarbergstraße 73 99097 Erfurt

Alle Rechte vorbehalten. Sämtliche Angaben vorbehaltlich technischer Änderungen. Trotz sorgfältiger Prüfung wird für den Inhalt keine Haftung übernommen. Alle aufgeführten Warennamen sind eingetragen und als solche zu behandeln.

Im Interesse der besseren Lesbarkeit des Textes wird auf geschlechterspezifische Formulierungen verzichtet. Die männliche Form wird als generisches Maskulinum und damit ausdrücklich als Sammelbezeichnung für beide Geschlechter verwendet.

Nachdruck und Vervielfältigung – auch auszugsweise – nur mit Genehmigung der PDV GmbH, Erfurt

[Seite 3]

Inhaltsverzeichnis

Inhaltsverzeichnis

1 Einleitung ................................................................................................................ 4 1.1 Begleitende Dokumente ........................................................................................ 4 2 Software Development Kit ..................................................................................... 5 2.1 Konfiguration der Datei VAPI.dll.config .................................................................. 5 2.2 VAPI mittels COM ................................................................................................. 8 3 Proxy-Einstellung ................................................................................................. 12 4 VAPI-Schnittstelle ................................................................................................. 13 4.1 Stub-Generierung................................................................................................ 13 4.2 Sicherheit ............................................................................................................ 15 5 Konfigurationsbeispiel ......................................................................................... 16 5.1 VAPI-Client-Instanz erzeugen ............................................................................. 16 5.2 Authentifizierung gegenüber VIS ......................................................................... 17 5.3 Aufruf einer VAPI-Funktion .................................................................................. 18 5.4 Aufbau der VAPI-Samples-Methoden .................................................................. 20

3

[Seite 4]

Einleitung

1 Einleitung

1.1 Begleitende Dokumente

Tabelle 1: Begleitende Dokumente

4

[Seite 5]

Software Development Kit

Konfiguration der Datei VAPI.dll.config

2 Software Development Kit

Für eine einfache Nutzung des VAPI-Webservice stellt die PDV GmbH clientseitige Software Development Kits (SDK) bereit. Diese stellen eine Sammlung von Programmierwerkzeugen und Programmbibliotheken dar, welche die Arbeit mit VAPI erleichtern. Im Umfeld von C# steht Ihnen das .NET VAPI SDK zur Verfügung, welches die Windows Communication Foundation (WCF) nutzt.

2.1 Konfiguration der Datei VAPI.dll.config

In der Konfigurationsdatei VAPI.dll.config können Sie relevante Informationen definieren, welche bisher aus der Datei app.config der Anwendung bzw. auch der Datei machine.config des .NET-Frameworks entnommen wurden - insofern keine .NET- Anwendung im Einsatz war, z. B. bei der Verwendung von VAPI mittels COM.

Die Konfigurationen in der Datei VAPI.dll.config werden – wenn vorhanden – gegenüber den Einstellungen in der Datei app.config bevorzugt. Dies gilt jedoch nur für spezifische VAPI-Einstellungen. Framework Einstellungen werden nicht in der VAPI.config.dll definiert, sondern erfolgen in der app.config. Alternativ kann der interne Fallbackmechanismus verwendet werden.

Einstellung der Verbindungsdaten:

Aufgrund konfigurativer Besonderheiten der Kommunikationsplattform WCF wurden in der VAPI-Konfiguration (VAPI.dll.config) bereits Vorbereitungen getroffen, um einfach zwischen unverschlüsselter und verschlüsselter Verbindung wechseln zu können. Hierfür existieren zwei CustomBindings, die zwischen den Transportprotokollen httpTransport und httpsTransport unterscheiden:

5

[Seite 6]

Software Development Kit

Konfiguration der Datei VAPI.dll.config

Die Verwendung des jeweiligen Bindings wird ebenfalls in der VAPI.dll.config konfiguriert. Standardmäßig ist hier die unverschlüsselte Variante vapiWSPortMTOM festgelegt. Für die verschlüsselte Kommunikation ist im Attribut name entsprechend mit dem Wert vapiWSPortMTOMBindingSecure zu belegen.

Zusätzlich besteht die Möglichkeit das Binding in der jeweiligen VAPI-Anwendung festzulegen. Die zuvor genannte Einstellungsmöglichkeit wird dabei überschrieben. Hierfür ist der Schlüssel bindingName entsprechend dem folgenden Beispiel den Anwendungseinstellungen hinzuzufügen:

Diese Anwendungseinstellung kann dynamisch zur Laufzeit verändert werden. Dies ist insbesondere empfehlenswert, wenn innerhalb einer Anwendung Verbindungen zu Servern mit unterschiedlichen Konfigurationen (unverschlüsselt und verschlüsselt) aufgebaut werden müssen.

6

[Seite 7]

Software Development Kit

Konfiguration der Datei VAPI.dll.config

Anwendungseinstellungen (appsettings)

Im Bereich appsettings der VAPI.dll.config haben Sie die Möglichkeit Einstellungen für die VAPI-Anwendung zu definieren. Die hier vorgenommene Konfiguration wird in jedem Fall geladen und ersetzen die Werte der app.config (z.B. MyProgram.exe.config) der Anwendung, welche die VAPI.dll verwendet.

Standardmäßig stehen Ihnen in diesem Bereich die nachfolgenden Konfigurationsmöglichkeiten zur Verfügung:

Um die hier definierten Einstelllungen während der Laufzeit dynamisch zu ändern, können Sie die Einstellungen in der VAPI.dll.config mithilfe der VAPI-Methode ReConfig durch eine eigens angepasste Konfigurationsdatei ersetzen.

Für die Konfiguration der Schlüssel bindingName, bufferSize und receivedMessageSize können die im Abschnitt Einstellung der Verbindungsdaten genannten WCF-Standardwerte verwendet werden.

7

[Seite 8]

Software Development Kit

VAPI mittels COM

Konfiguration der Windows Communication Foundation (WCF)

In der VAPI.dll.config können zudem Konfigurationen für die Kommunikationsplattform WCF für eine Authentifizierung mittels Kerberos vorgenommen werden. Hierzu die folgenden Zeilen in der Konfiguration ergänzen und das Behavior am Endpunkt hinzufügen.:

2.2 VAPI mittels COM

Für die Verwendung von VAPI mittels COM stehen Ihnen im Unterordner COM des .NET VAPI SDK mithilfe der Dateien register.bat bzw. unregister.bat Batch-Skripte bei, mit denen die notwendigen Registrierungsschritte bzw. Unregistrierungsschritte vorgenommen werden können.

8

[Seite 9]

Software Development Kit

VAPI mittels COM

Die Verwendung von VAPI mittels COM wird nachfolgend anhand der COM-Schnittstelle von VBA in MS-Word (32-Bit) an Konfigurationsbeispielen erläutert. Die in den Beispielen verwendete Methode RUN ist dabei noch einmal separat aufgeführt. Es wird vorausgesetzt, dass VAPI in dem Projekt als Referenz hinzugefügt ist.

Beispiel: Laden der Verbindungsdaten aus der VAPI.dll.config

Beispiel: Verwendung der VAPI.set-Methoden

Die nachfolgende Konfiguration zeigt exemplarisch die Verwendung der VAPI-Methoden setMandant und setEndpoint, Hierbei werden die definierten Werte aus der Datei VAPI.dll.config überschrieben.

Sub VapiWS_man() MsgBox "run VapiWS setmandant setendpoint" Dim VAPI As VapiWS Set VAPI = Nothing Set VAPI = CreateObject("de.pdv.visnet.business.vapi.VapiWS") VAPI.setMandant "{Mandant-GUID}" VAPI.setEndPoint http://server:port/vis/{Mandant- GUID}/service/VapiWSMTOM Call Run(VAPI) Set VAPI = Nothing MsgBox "finished" End Sub

9

[Seite 10]

Software Development Kit

VAPI mittels COM

Beispiel: Verwendung der VAPI-Methode ReConfig

Über die Methode ReConfig in VAPI dient zum Überschreiben der Einstellungen in der VAPI-Konfiguration anhand einer extra Konfigurationsdatei. Die Datei muss dabei strukturell analog zur Datei VAPI.dll.config aufgebaut sein.

Sub ReConfig_success() MsgBox "run VapiWS with reconfig_success.config" Dim VAPI As VapiWS Set VAPI = Nothing Set VAPI = CreateObject("de.pdv.visnet.business.vapi.VapiWS") VAPI.ReConfig ("c:\tmp\reconfig.config") Call Run(VAPI) Set VAPI = Nothing MsgBox "finished" End Sub

10

[Seite 11]

Software Development Kit

VAPI mittels COM

Verwendung der VAPI-Methode RUN

Sub Run(ByRef vapi As IVapiWS) Dim result As Long Dim xml As String Dim options As Long Dim bo(0) As Long Dim file As Variant xml = "" xml = xml & "" xml = xml & "<Dokument SchemaId=""300"" MandantenName=""dummy"" Art=""12"">" xml = xml & "VAPI over COM" xml = xml & "" result = vapi.createBo(EBoType.EBoType_BO_TYPE_INCOMING, xml, -1, - 1, EExportImport.EExportImport_DEFAULT) xml = "" xml = xml & "" xml = xml & "<Dokument SchemaId=""300"" MandantenName=""dummy"" Art=""12"">" xml = xml & "" xml = xml & "" xml = xml & "<Binaries type=""attachment"" name=""bg.jpg"" visAttRefId=""1"">" xml = xml & "" xml = xml & "" xml = xml & "" xml = xml & "" vapi.addRequestAttachment "d:\images\bg.jpg" options = EExportImport.EExportImport_DEFAULT Or EExportImport.EExportImport_EXPORT_IMPORT_PRIMDOC_ATTACHMENTS vapi.updateBo result, xml, options bo(0) = result xml = vapi.exportBo(bo, options) result = vapi.getResponseAttachmentCount() If result > 0 Then vapi.saveResponseAttachment 0, "d:\debug\bg.jpg" End If Open "d:\debug\out.xml" For Output As #1 Write #1, xml Close #1 End Sub

11

[Seite 12]

Proxy-Einstellung

3 Proxy-Einstellung

Für VAPI können Sie zusätzliche Verbindungseinstellungen umgehen und die Schnittstelle dementsprechend auch mit einem Proxy-Server betreiben. Hierfür muss die Methode setProxy() auf der VAPI-Client-Instanz aufgerufen werden.

client.setProxy("string proxyServer", "string proxyExcludes");

Der Parameter proxyExcludes ist eine Liste, deren einzelne Elemente durch ein Semikolon ; getrennt werden.

Beispiel: client.setProxy("http://Beispiel", ".Beispiel.de;.Beispiel.com")

12

[Seite 13]

VAPI-Schnittstelle

Stub-Generierung

4 VAPI-Schnittstelle

Um komfortabel aus Fremdanwendungen über die VAPI-Schnittstelle auf VIS- Funktionalitäten zugreifen zu können, sollten die mitgelieferten Clientbibliotheken verwendet werden. Steht für die gewünschte Umgebung keine geeignete Clientbibliothek zur Verfügung, so kann mit Hilfe der mitgelieferten WSDL (Web Service Description Language) selbst ein Stub erzeugt werden. Das Vorgehen hierfür wird im nachfolgenden Kapitel exemplarisch beschrieben.

4.1 Stub-Generierung

Der VAPI-Webservice wird durch die mitgelieferten WSDL vollständig beschrieben. Auf Grundlage dieser Beschreibung ist das automatische Generieren eines sogenannten Stubs oder auch Proxys in nahezu jeder modernen Entwicklungsumgebung möglich.

Beim Einsatz von Microsoft Visual Studio erfolgt das Generieren eines C#-Stubs beispielsweise mit Hilfe des Tools WCF Web Service Reference Provider (SvxUtil.exe).

svcutil /out:Reference.cs http://<>:<>/vis/<>/service/VapiWSMTOM?wsdl

Alternativ können Sie Visual Studio auch ein Dienstverweis erzeugen. Hierzu öffnen Sie mit einem Rechtsklick auf das Projekt das Kontextmenü und wählen in der Funktion Hinzufügen den Eintrag Dienstverweis hinzufügen… aus.

13

[Seite 14]

VAPI-Schnittstelle

Stub-Generierung

Im sich öffnenden Dialog Dienstverweis hinzufügen sind folgende Konfigurationen vorzunehmen: • Im Feld Adresse tragen Sie die URL-Adresse der WSDL ein. • Im Feld Namespace geben Sie den gewünschten Namensraum der Klasse an.

Abbildung 1: Dialog Dienstverweis hinzufügen mit WSDL-Adresse und Namespace

Dem Projekt wird anschließend eine WCF-ServiceReferenz hinzugefügt. Die dabei generierten Dateien werden im Explorer von Visual Studio innerhalb des ausgewählten Projekts im Ordner Connected Services angezeigt.

14

[Seite 15]

VAPI-Schnittstelle

Sicherheit

4.2 Sicherheit

Das Verschlüsseln und Signieren der Nachricht erfolgt durch die Verwendung von WS- Security nach OASIS Standard 200401:

OASIS Web Services Security: SOAP Message Security 1.0

Für die Authentifizierung werden Kerberos-, x509-Zertifikate und das Basic-Verfahren unterstützt. Zur Erstellung eines Clients kann auf eine Bibliothek eines Drittherstellers zurückgegriffen werden. Empfohlen wird die Verwendung von Windows Communication Foundation (WCF).

15

[Seite 16]

Konfigurationsbeispiel

VAPI-Client-Instanz erzeugen

5 Konfigurationsbeispiel

Im folgenden Kapitel werden die Funktionalitäten der Clientbibliothek anhand von Beispielen aus dem Projekt VAPI-Samples näher erläutert. Einen Einstiegspunkt in die VAPI-Samples bietet die Klasse Program.cs. In dieser Klasse kann eine Client-Instanz erzeugt, sowie alle konfigurativen Einstellungen zur Authentifizierung vorgenommen werden. Weiterhin können Sie mithilfe der Klasse Program.cs den Aufruf von VAPI-Sample-Methoden vollziehen.

5.1 VAPI-Client-Instanz erzeugen

Um eine Client-Instanz zu erzeugen, müssen folgenden Werte bekannt sein: • VIS-Endpoint • VIS-Mandant

Diese Werte können Sie in der Datei VAPISettings.settings anpassen. Innerhalb der Program.cs erfolgt anschließend die Zuweisung der konfigurierten Settings zu den Parametern endpoint und mandant.

Die Erzeugung einer Client-Instanz kann über die VapiWS-Klasse sowie über die VapiWSMTOMClient-Klasse durchgeführt werden.

Beispiel VapiWS-Klasse:

String endpoint VAPISettings.Default.Mandant;

String mandant = VAPISettings.Default.SoapURL;

//1.Schritt: VAPI-Objekt erzeugen (z.B.VapiWS)

var client = new VapiWS (mandant, endpoint);

16

[Seite 17]

Konfigurationsbeispiel

Authentifizierung gegenüber VIS

5.2 Authentifizierung gegenüber VIS

Damit die Anfragen der Clientanwendung vom VIS-Server akzeptiert werden, muss sich die eben erzeugte VAPI-Client-Instanz gegenüber VIS authentifizieren. Hierfür bieten sich die folgenden drei Möglichkeiten an:

1 - Authentifizierung im Benutzerkontext von Windows

client.setSecurityType((int)EsecurityType.SECURTYPE_WINDOWS_AUTHENT);

2 - Authentifizierung über Kerberos

client.setSecurityType((int)ESecurityType.SECURTYPE_KERBEROS_AUTHENT);

3 - Authentifizierung mittels Basic-Authentifizierung

client.setSecurityType((int)ESecurityType.SECURTYPE_BASIC);

client.setBasicCredentials("<>","<>");

Innerhalb der VAPI-Samples werden Methoden bereitgestellt, die jeweils eine der drei zuvor aufgeführten Authentifizierungsmöglichkeiten beinhalten:

// Windows-Authentifizierung

var client = getClientWindowsAuth(mandant, endPoint);

// Kerberos-Authentifizierung

var client = getClientKerberosAuth(mandant, endPoint);

// Basic-Authentifizierung

var client = getClientBasicAuth(mandant, endPoint, username,

password);

Neben den Parametern mandant und endpoint werden bei der Basic-Authentifizierung außerdem die Parameter username und password benötigt. Diese müssen Sie jeweils im Klartext angeben.

17

[Seite 18]

Konfigurationsbeispiel

Aufruf einer VAPI-Funktion

5.3 Aufruf einer VAPI-Funktion

Innerhalb der VAPI-Samples sind alle VAPI-Funktionen in eigenständigen Klassen aufgeteilt. Um von der Program.cs eine VAPI-Funktion ausführen zu können, muss zuvor eine using-Anweisung der jeweiligen Klasse in den Namensraum der Program.cs integriert werden:

using static vapisamples.bo.cru.CreateBo;

Jede Klasse enthält eine oder mehrere VAPI-Sample-Methoden, wobei jede Methode einen in sich abgeschlossenen Anwendungsfall beinhaltet. Im nachfolgenden Beispiel zur Klasse createBo wird die Methode createBoAkte aufgerufen, die zur Erstellung einer Akte in VIS verwendet wird:

createBoAkte(client, vapiOptions);

Bei jedem Methodenaufruf wird mindestens das erzeugte VAPI-Client-Objekt (siehe Kapitel 5.1 VAPI-Client-Instanz erzeugen) übergeben. Manche Methoden, wie beispielsweise createBoAkte zum Erzeugen einer neuen Akte, benötigen zur Ausführung noch weitere Parameter. In diesem Fall handelt es sich um eine ExportImport-Option, die im Parameter vapiOptions übergeben wird.

Eine Übersicht zu den EExportImport-Optionen entnehmen Sie der technischen VAPI-SDK-Dokumentation. Diese finden Sie im Ordner des VAPI-SDKs. Wählen Sie dort den Unterordner Dokumentation aus und öffnen Sie die Datei index.html mit einem Doppelklick.

Abbildung 2: Aufruf der technischen VAPI-Dokumentation

18

[Seite 19]

Konfigurationsbeispiel

Aufruf einer VAPI-Funktion

Auf der Startseite ist eine Übersicht zu allen im VAPI-Client verfügbaren Klassen, Schnittstellen und Enumerationen ersichtlich. Um eine Auswahl der möglichen Optionen für den Export und Import zu erhalten, wählen Sie den Menüpunkt EExportImport im Abschnitt Enumerationen aus.

Abbildung 3: Ausschnitt der technischen VAPI-Dokumentation mit Abschnitt Enumeration

Anschließend wird Ihnen im Abschnitt Member eine Übersicht zu den verfügbaren EExportImport-Optionen angezeigt, aus der Sie die gewünschte Funktion für die createBo- Methode zum Erzeugen einer neuen Akte auswählen.

Abbildung 4: Ausschnitt der EExportImport-Optionen im Abschnitt Member

19

[Seite 20]

Konfigurationsbeispiel

Aufbau der VAPI-Samples-Methoden

5.4 Aufbau der VAPI-Samples-Methoden

Jede VAPI-Sample-Methode besteht aus zu konfigurierenden Parametern und einer VAPI-Funktion. Die Definition der jeweiligen Funktion und eine Erklärung ihrer Parameter können Sie in der technischen Dokumentation des VAPI-Clients einsehen. Aufbau und Verwendung der VAPI-Samples wird im Folgenden exemplarisch anhand der Methode createBo() erläutert.

So sehen Sie die Definition einer Methode in den VAPI-Samples ein:

1 - Navigieren Sie auf der Übersichtsseite der technischen VAPI-Dokumentation zu dem Menüpunkt VapiWS im Abschnitt Klassen.

Zwischenergebnis: Eine Übersicht mit den allgemeinen Klassendefinition, Konstruktoren und Methoden der VapiWS-Klasse wird angezeigt.

Abbildung 5: Abschnitt Klassen mit Menüpunkt VapiWS zur Implementierung der VAPI-Schnittstelle

20

[Seite 21]

Konfigurationsbeispiel

Aufbau der VAPI-Samples-Methoden

2 - Im Abschnitt Methoden wählen Sie anschließend die Methode createBo aus.

Ergebnis: Die Definition der Methode wird angezeigt.

Abbildung 6: Auszug aus der Definition der VapiWS-Klasse mit Methode createBo

21

[Seite 22]

Konfigurationsbeispiel

Aufbau der VAPI-Samples-Methoden

Neben genaueren Informationen zur Definition der Methode werden Ihnen hier zusätzlich die zur Ausführung benötigten Parameter angezeigt. Sie können die Parameter der Methode createBo nach Bedarf anpassen.

Abbildung 7: Definition und konfigurierbare Parameter der Funktion createBo in den VAPI-Samples

Nach Anpassung der Parameter und abschließender Ausführung des Programms, erhalten Sie entsprechend der vorgenommenen Konfigurationen eine VIS-ID des neu erstellten Objekts. Das Ergebnis können Sie anschließend in einer Konsolenausgabe (z. B. der Windows-Eingabeaufforderung) überprüfen.

Die nachfolgende Abbildung zeigt das Ergebnis der Erstellung einer neuen Akte mithilfe der VAPI-Funktion createBo in der Windows-Eingabeaufforderung.

Abbildung 8: Ergebnis der VAPI-Funktion createBo in der Windows-Eingabeaufforderung

22

[Seite 23]

Konfigurationsbeispiel

Aufbau der VAPI-Samples-Methoden

23