Probleme beim Adapterentwurf
Die Adapterkonfiguration wird in der Datenbank für Einmaliges Anmelden (SSO) gespeichert, wenn der Benutzer die Konfiguration während der Entwurfszeit ändert. Zur Laufzeit ruft die Messaging-Engine die Konfiguration des Adapters ab und sendet sie an den Adapter. Vier Arten von Informationen zur Konfiguration werden an den Adapter gesendet:
Empfangshandlerkonfiguration
Empfangsspeicherort-Konfiguration (Endpunkt)
Sendehandlerkonfiguration
Sendespeicherort-Konfiguration (Endpunkt)
Handlerkonfiguration senden und empfangen
Die Handlerkonfiguration eines Adapters wird dem Adapter bei der Implementierung des optionalen IPersistPropertyBag übermittelt. Laden der Schnittstelle. Die Handlerkonfiguration wird nur einmal gesendet. Wenn also die Handlerkonfiguration des Adapters geändert wird, nachdem der BizTalk-Dienst gestartet wurde, wird der Adapter nicht aktualisiert. Im Allgemeinen behandelt der Adapter die Handlerkonfiguration als Standardkonfiguration. Die Endpunktkonfiguration überschreibt die Handlerkonfiguration jeweils nach Endpunkt.
Im folgenden Codefragment wird die Analyse der Konfiguration dargestellt. Die Konfiguration des Adapters befindet sich in der Eigenschaft, die an den Load-Aufruf in der Zeichenfolgeneigenschaft AdapterConfig übergeben wird. Dieser Eigenschaftswert enthält ein XML-Dokument, das die Konfiguration des Adapters darstellt. Der Adapter muss diese Konfiguration in eine Dokumentobjektdarstellung (DOM - Document Object Model) oder in einen XML-Reader laden und zum Abrufen der einzelnen Eigenschaften XPath verwenden.
public class MyAdapter : IBTTransport,
IBTTransportConfig,
IBTTransportControl,
IPersistPropertyBag,
IBaseComponent
{
...
// Handler configuration properties...
private int defaultBatchSize = 0;
private string defaultHeader;
// IPersistPropertyBag.Load() implementation...
public void Load(IPropertyBag pb, int pErrorLog)
{
// The adapter configuration is in the property
// “AdapterConfig” in the form of an Xml blob...
object obj = null;
pb.Read("AdapterConfig", out obj, 0);
// Create a DOM and load the Xml blob...
XmlDocument dom = new XmlDocument();
string adapterConfig = (string)obj;
dom.LoadXml(adapterConfig);
// XPath the individual properties...
XmlNode node =
document.SelectSingleNode(“/Config/batchSize”);
defaultBatchSize = int.Parse(node.InnerText);
node = document.SelectSingleNode(“/Config/header”);
defaultHeader = node.InnerText;
}
}
Konfigurieren der Empfangsspeicherorte
Informationen zur Standortkonfiguration werden an einen Adapter über die Implementierung von IBTTransportConfig übermittelt. Diese Schnittstelle enthält die drei Methoden AddReceiveEndpoint, UpdateEndpointConfig und RemoveReceiveEndpoint. Die Messaging-Engine benachrichtigt den Adapter darüber, welche Endpunkte er überwachen muss, um Nachrichten zu empfangen. Wird die Konfiguration eines einzelnen Endpunkts geändert, wird der Adapter darüber informiert. Im Gegensatz dazu wird der Adapter über Änderungen der Handlerkonfiguration nicht informiert. Dementsprechend ist der Adapter nicht für die Verarbeitung von Dienstfenstern zuständig, da BizTalk-Server Endpunkte hinzufügt oder entfernt, wenn Dienstfenster aktiviert oder deaktiviert werden.
AddReceiveEndpoint
Wenn ein Adapter mit der Überwachung eines Endpunkts beginnen muss, ruft die Engine IBTTransportConfig.AddReceiveEndpoint auf und übergibt den URI des Empfangsspeicherorts, einen Eigenschaftenbehälter, der die Konfiguration des Adapters für diesen Endpunkt enthält, und einen zweiten Eigenschaftenbehälter, der BizTalk Server spezifische Konfiguration für diesen Endpunkt enthält. Der Adapter muss den URI als BizTalk Server Systemeigenschaft InboundTransportLocation in den Nachrichtenkontext schreiben.
Das Lesen der Eigenschaften des Empfangsspeicherorts aus der Eigenschaftensammlung des Adapters entspricht dem oben erläuterten Lesen der Handlerkonfiguration. Die an den Adapter übergebene BizTalk Server-Konfiguration enthält eine einzelne Eigenschaft, TwoWayReceivePort, die angibt, ob der Port unidirektional oder bidirektional ist. Das folgende Codefragment erläutert, wie anhand der Eigenschaftensammlung von BizTalk Server überprüft werden kann, ob der Empfangsport uni- oder bidirektional kommuniziert:
public void AddReceiveEndpoint(
string url,
IPropertyBag adapterConfig,
IPropertyBag bizTalkConfig )
{
...
// The property "TwoWayReceivePort" in the BizTalk Config
// property bag indicates whether the port is one or two
// way...
// Add receive location to config cache (not shown here)
object obj = null;
bizTalkConfig.Read("TwoWayReceivePort", out obj, 0);
if ( null != obj )
this.twoWay = (bool)obj;
}
UpdateEndpointConfig
Wenn die Konfiguration eines aktiven Empfangsspeicherorts geändert wird, verwendet die Engine die UpdateEndpointConfig-API , um den Adapter zu benachrichtigen, dass er eine andere Konfiguration verwenden muss. Die Konfiguration wird in vollem Umfang an den Adapter gesendet, einschließlich der BizTalk Server-spezifischen Konfiguration.
RemoveReceiveEndpoint
Wenn ein Empfangsspeicherort nicht mehr aktiv ist, wird der Adapter über RemoveReceiveEndpoint benachrichtigt. Nachdem der Adapter von RemoveReceiveEndpoint zurückgegeben wurde, darf er diesen URI nicht mehr verwenden, um Nachrichten an die Engine zu senden.
Sendeportkonfiguration
Die Messaging-Engine schreibt die Sendeport-Konfiguration in den Kontext der Nachricht im Namespace des Adapters, bevor die Nachricht an den Adapter gesendet wird. Der Adapter ist dafür verantwortlich, die Konfiguration, die er künftig zur Steuerung der Nachrichtenübermittlung verwendet, zu lesen und zu überprüfen. Für Sendeadapter, die Sendevorgänge mit Batchverarbeitung unterstützen, können für verschiedene Sendeports bestimmte Nachrichten in demselben Batch enthalten sein. Der Adapter muss daher in der Lage sein, diese "gemischten" Batches zu verarbeiten.
Das folgende Codefragment veranschaulicht, wie der OutboundTransportLocation-Wert gelesen wird, der der URI für den Sendeport ist. Beschrieben wird außerdem, wie die XML-Datei vom Typ "Blob", die die Konfiguration des Adapters enthält, und anschließend die einzelnen Eigenschaften gelesen werden.
...
private static readonly PropertyBase UriProperty =
new BTS.OutboundTransportLocation();
private string propertyNamespace =
"http://schemas.mySchemas.com/MyAdapter/myadapter-properties";
private string uri;
private string headers;
private int timeOut = 1000;
private void ReadSendPortConfig(IBaseMessage msg)
{
// Read the OutboundTransportLocation,
// i.e. the send port uri....
uri = (string)msg.Context.Read(
UriProperty.Name.Name, UriProperty.Name.Namespace);
// Read the adapters configuration Xml blob from
// the message...
XmlDocument locationConfigDom = null;
object obj = msg.Context.Read(
"AdapterConfig", this.propertyNamespace);
// If this is a dynamic send there will not be
// any configuration...
if ( null != obj )
{
locationConfigDom = new XmlDocument();
locationConfigDom.LoadXml((string)obj);
this.headers = Extract(
locationConfigDom, "/Config/headers", true);
this.timeOut = ExtractInt32(
locationConfigDom, "/Config/timeOut", true);
}
}
// Helper method to XPath string properties...
private static string Extract(
XmlDocument document, string path, bool required)
{
XmlNode node = document.SelectSingleNode(path);
if (!required && null == node)
return String.Empty;
if (null == node)
throw new ApplicationException(string.Format(
"No property was found at {0}", path));
return node.InnerText;
}
// Helper method to XPath int32 properties...
private static int ExtractInt32(
XmlDocument document, string path, bool required)
{
string s = Extract(document, path, required);
return int.Parse(s);
}
Implementierungstipp: Adapter sollten im Allgemeinen die OutboundTransportLocation-Nachrichtenkontexteigenschaft verwenden, um die Adresse zu bestimmen, an die die Nachricht gesendet werden soll. Dadurch kann der Adapter Übertragungen mit statischen Sendevorgängen und Übertragungen mit dynamischen Sendevorgängen einheitlich behandeln. Außerdem vereinfacht dies das Ändern von Adressen in Produktionsbindungsdateien.
XSD
Vier XSD-Dateien, die im SDK-Dateiadapterbeispiel enthalten sind, behandeln in erster Linie die Adapterkonfiguration: ReceiveHandler.xsd, ReceiveLocation.xsd, TransmitLocation.xsd und TransmitHandler.xsd.
In den folgenden Themen wird jede dieser Dateien erläutert und beschrieben, wie sie geändert werden können.