Bereitstellen eines benutzerdefinierten Adapters

Artikel
05/04/2023

Eine vollständige Adapterinstallation besteht aus folgenden Schritten:

Überprüfen der Abhängigkeiten. Das Installationsprogramm für den MSMQ-Adapter überprüft zum Beispiel, ob der lokale MSMQ-Dienst vorhanden ist, weil das Laufzeitmodul des Adapters davon abhängig ist.
Einrichten des lokalen Dateisystems. Dies umfasst das Erstellen von Installationsordnern und das Kopieren von Binär- und Unterstützungsdateien. Stellen Sie sicher, dass Zugriff auf Ordner besteht und Berechtigungen für den Dateizugriff richtig konfiguriert sind.
Installieren verwalteter Assemblys im globalen Assemblycache des Systems.
Erstellen von Registrierungsschlüssel für den Adapter.

Hinweis

Bei einem 32-Bit-Adapter ruft die BizTalk Server-Verwaltungskonsole die benutzerdefinierte Adapterkonfiguration über die Verzweigung HKEY_CLASSES_ROOT in der Registrierung ab. Wenn ein 32-Bit-Adapter auf einem 64-Bit-Server installiert wird, verwendet die BizTalk Server-Verwaltungskonsole stattdessen die Verzweigung HKEY_CLASSES_ROOT\Wow6432Node\ für Adapterkonfigurationsdaten.
Hinzufügen des Adapters zu BizTalk Server. Dies bedeutet neue Einträge in der BizTalk-Verwaltungsdatenbank für den Adapter sowie für das Eigenschaftsschema, das die Eigenschaften wiedergibt, die der Adapter höher stuft. Dieser Schritt wird manchmal manuell in der BizTalk Server-Verwaltungskonsole ausgeführt.

Ausnahmen

Bei Teilinstallationen von BizTalk Server muss das Adapter-Installationsprogramm die Abhängigkeiten u. U. nicht überprüfen. Bei einer Installation etwa, die nur aus den Verwaltungstools besteht, muss das Adapterinstallationsprogramm die Abhängigkeiten des Adapter-Laufzeitmoduls nicht überprüfen, weil dieses nicht verwendet wird. Das Gleiche gilt bei einer Installation, die nur das Laufzeitmodul von BizTalk Server enthält. In diesem Fall muss das Adapterinstallationsprogramm die Abhängigkeiten der Adapter-Entwurfszeitkomponente nicht überprüfen.

In Umgebungen mit mehreren BizTalk Server-Computern wird der letzte Schritt in der vorangehenden Liste (Hinzufügen des Adapters zu BizTalk Server) nur bei der Adapterinstallation auf dem ersten BizTalk Server-Computer ausgeführt. Das liegt daran, dass alle BizTalk Server-Dienstinstanzen gemeinsam dieselbe BizTalk-Verwaltungsdatenbank nutzen (mit dem Standardnamen "BizTalkMgmtDB"). Wenn Adapter anderen BizTalk-Servern in derselben Gruppe hinzugefügt werden, schlagen die zusätzlichen Schritte fehl.

Installieren der Adapterassemblys im globalen Assemblycache

Um mehrere BizTalk Server umfassende Hostumgebungen mit unterschiedlichen Installationspfaden für Adapter zu unterstützen, müssen die Adapterassemblys im globalen Assemblycache des Systems installiert werden.

Bei der Adapterinstallation und -konfiguration wird ein neuer Adaptereintrag in der Tabelle "adm_adapter" der BizTalk-Verwaltungsdatenbank (mit dem Standardnamen "BizTalkMgmtDB") erstellt. Dieser Eintrag enthält alle Referenzinformationen, die von BizTalk Server für Lauf- und Entwurfszeit verwendet werden.

Die Felder InBoundAssemblyPath und OutboundAssemblyPath werden von der BizTalk Server Runtime verwendet, um herauszufinden, wo die Adapterbinärdateien geladen werden. Da es für eine BizTalk Server-Gruppe nur eine BizTalk-Verwaltungsdatenbank gibt, müssen alle BizTalk-Server in der Gruppe diese Information gemeinsam nutzen. Wenn Sie den Adapter auf unterschiedlichen BizTalk-Servern in der Gruppe installieren möchten, müssen Sie auf jedem dieser Server den gleichen Installationspfad verwenden. Wenn sich der lokale Installationspfad vom Pfad unterscheidet, der in der BizTalk-Verwaltungsdatenbank gespeichert ist, können die Adapterbinärdateien nicht von BizTalk Server geladen werden.

Signieren Sie die Assembly des Adapters stets mit einem starken Namen, und legen Sie die Adapterassembly bei der Adapterinstallation mithilfe der Datei Gacutil.exe im globalen Assemblycache des Systems ab. Stellen Sie sicher, dass Sie die Felder InBoundAssemblyPath und OutboundAssemblyPath null oder leer lassen.

Verwenden des Frameworks für die Adapterkonfiguration

BizTalk Server stellt einen Mechanismus zum Generieren von Eigenschaftenblättern für die Benutzeroberfläche (Ui) der Adapterkonfiguration bereit. Er basiert auf einer XSD-Definition (XML-Schemadefinition) der Konfigurationseigenschaften. Der Einsatz dieses Frameworks stellt Adapterentwickler vor beträchtliche Probleme. Dieser Abschnitt enthält einen Vorschlag dazu, wie einige dieser Probleme effektiv umgangen werden können.

Verwenden von benutzerdefinierten Eigenschaften-Editoren für alle wichtigen Eigenschaften

Es ist unmöglich, Eigenschaften im Eigenschaftenblatt wirksam zu validieren. Das Framework versucht, die Validierungsregeln für die Benutzeroberfläche mithilfe von XSD-simpleType-Einschränkungen zu definieren. Die einfachen Regeln für den Höchst- und Mindestwert werden angewendet, doch die Einschränkung für reguläre Ausrücke für Felder mit Zeichenfolgen wird nicht unterstützt. Außerdem werden die Daten vor Anwendung der Einschränkung in CLR-Typen (Common Language Runtime) konvertiert. Das bedeutet, dass auf der Benutzeroberfläche manchmal ein kryptischer Typkonvertierungsfehler angezeigt wird statt eines Fehlers infolge eines außerhalb des Gültigkeitsbereiches liegenden Wertes. Alles in allem ist die Validierungslogik nicht sehr leistungsstark.

Viele Adapterentwickler lösen dieses Problem damit, dass sie benutzerdefinierte Eigenschaften-Editoren für die Haupteigenschaften auf ihren Eigenschaftenblättern schreiben. Wenn es (wie so oft) eine Reihe von untereinander abhängigen Eigenschaften gibt, kann der benutzerdefinierte Eigenschaften-Editor die Ergebnisse in einem einzigen Feld zusammenfassen, und diese können später vom Laufzeitmodul getrennt werden. Dies ist die einzige Möglichkeit, den erforderlichen (wenngleich allgemein nach wie vor simplen) benutzerdefinierten Code in die Oberfläche einzufügen.

Benutzerdefinierte Eigenschaften-Editoren sind relativ einfach zu schreiben, und in der Eigenschaft der XSD kann angemerkt werden, dass die Editoren zu verwenden sind. Die Anmerkung verweist auf eine Assembly, die den Einstiegspunkt des Eigenschaften-Editors verfügbar macht, und sie ist so codiert, dass ein CLR-Formular angezeigt wird. Nun können Sie eine normale Benutzeroberfläche schreiben und die herkömmlichen Tools verwenden, die Visual Studio zum Generieren von Oberflächen bietet.

Der folgende Code zeigt, wie mithilfe der XSD ein benutzerdefinierter Eigenschaften-Editor hinzugefügt wird:

<xs:element name="queueDetails" type="xs:string" minOccurs="0">  
    <xs:annotation>  
        <xs:appinfo>  
           <baf:designer>  
               <baf:displayname _locID="queueName">Queue Definition</baf:displayname>  
               <baf:description _locID="receiveQueueDesc">Details of MQSeries Server, Queue Manager and Queue from where you want to receive messages.</baf:description>  
               <baf:category _locID="mqsCategory">MQSeries</baf:category>  
               <baf:editor assembly="Microsoft.BizTalk Server.Adapter.MQSAdmin.dll">Microsoft.BizTalk Server.Adapter.MQSAdmin.MQSUITypeEditor</baf:editor>  
            </baf:designer>  
        </xs:appinfo>  
    </xs:annotation>  
</xs:element>

Der Code, auf den verwiesen wird, sollte folgendermaßen aussehen:

public class MQSUITypeEditor : System.Drawing.Design.UITypeEditor  
{  
public override System.Drawing.Design.UITypeEditorEditStyle GetEditStyle  
(System.ComponentModel.ITypeDescriptorContext context)   
{  
return System.Drawing.Design.UITypeEditorEditStyle.Modal;  
}  
public override object EditValue (System.ComponentModel.ITypeDescriptorContext context,  
System.IServiceProvider provider, object value)   
{  
Form qdForm = new QueueDefinitionForm(value);  
IWindowsFormsEditorService service =   
(IWindowsFormsEditorService)provider.GetService(typeof(IWindowsFormsEditorService));  
DialogResult dialogResult = service.ShowDialog(qdForm);  
//…  
}  
}  
class QueueDefinitionForm : System.Windows.Forms.Form   
{  
//  traditional UI code goes here!  
}

Das Verwaltungs-Laufzeitmodul muss die Assembly finden können, auf die in der XSD verwiesen wird, daher müssen Sie sie dem globalen Assemblycache hinzufügen.

Share via