Problemi relativi alla progettazione degli adapter
La configurazione dell'adapter viene archiviata nel database SSO (Single Sign-On) quando l'utente vi apporta modifiche durante la fase di progettazione. In fase di esecuzione, il motore di messaggistica recupera la configurazione dell'adapter e la passa all'adapter. Agli adapter vengono passati quattro tipi di informazioni di configurazione:
Configurazione del gestore di ricezione
Configurazione dell'indirizzo di ricezione (endpoint)
Configurazione del gestore di trasmissione
Configurazione dell'indirizzo di trasmissione (endpoint)
Configurazione dei gestori di trasmissione e ricezione
La configurazione del gestore di un adattatore viene recapitata all'adattatore nella relativa implementazione dell'IPersistPropertyBag facoltativo. Interfaccia di caricamento . La configurazione del gestore viene passata una sola volta, in modo che, se la configurazione del gestore dell'adapter viene modificata dopo l'avvio del servizio BizTalk, l'adapter non venga aggiornato. Il modello comune prevede che l'adapter consideri la configurazione del gestore come predefinita; la configurazione degli endpoint esegue l'override della configurazione del gestore per ogni singolo endpoint.
Nel frammento di codice seguente viene illustrata l'analisi della configurazione. La configurazione dell'adapter si trova nella proprietà passata alla chiamata di caricamento nella proprietà string AdapterConfig. I valore di questa proprietà contiene un documento XML che rappresenta la configurazione dell'adapter. L'adapter deve caricare questa configurazione in un modello DOM (Document Object Model) o un lettore XML e utilizzare XPath per recuperare le singole proprietà.
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;
}
}
Configurazione dell'indirizzo di ricezione
Le informazioni sulla configurazione della posizione di ricezione vengono recapitate a un adattatore nell'implementazione di IBTTransportConfig. Questa interfaccia contiene i tre metodi AddReceiveEndpoint, UpdateEndpointConfig e RemoveReceiveEndpoint. Il motore di messaggistica notifica all'adapter su quali endpoint deve restare in ascolto per ricevere messaggi. Quando la configurazione di un singolo endpoint viene modificata, l'adapter riceve la notifica della modifica dell'endpoint in questione, diversamente da quanto avviene per la configurazione del gestore, le cui modifiche non vengono notificate all'adapter. Allo stesso modo, l'adapter non deve necessariamente gestire le finestre di servizi, poiché BizTalk Server aggiunge o rimuove gli endpoint quando le finestre di servizi diventano attive o inattive.
AddReceiveEndpoint
Quando un adattatore deve iniziare l'ascolto su un endpoint, il motore chiama IBTTransportConfig.AddReceiveEndpoint passando l'URI della posizione di ricezione, un contenitore di proprietà contenente la configurazione dell'adattatore per tale endpoint e un secondo contenitore di proprietà contenente BizTalk Server configurazione specifica per tale endpoint. L'adapter deve scrivere l'URI nel contesto del messaggio come proprietà di sistema BizTalk Server InboundTransportLocation.
La lettura delle proprietà dell'indirizzo di ricezione dall'elenco proprietà dell'adapter viene eseguita esattamente come la lettura della configurazione del gestore descritta dettagliatamente in precedenza. La configurazione BizTalk Server passata all'adapter contiene una singola proprietà, TwoWayReceivePort, che indica se la porta è unidirezionale o bidirezionale. Nel frammento di codice seguente viene illustrato come valutare se la porta di ricezione è unidirezionale o bidirezionale dall'elenco proprietà di BizTalk Server:
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
Quando la configurazione di una posizione di ricezione attiva viene modificata, il motore usa l'API UpdateEndpointConfig per notificare all'adapter che deve usare una configurazione diversa. All'adapter viene passata l'intera configurazione, inclusa la configurazione specifica di BizTalk Server.
RemoveReceiveEndpoint
Quando un percorso di ricezione non è più attivo, la scheda viene notificata tramite RemoveReceiveEndpoint. Dopo aver restituito l'adapter da RemoveReceiveEndpoint , non è più consentito usare tale URI per inviare messaggi nel motore.
Configurazione della porta di trasmissione
Il motore di messaggistica scrive la configurazione per la porta di trasmissione nel contesto del messaggio nello spazio dei nomi dell'adapter, prima di recapitare il messaggio all'adapter. È responsabilità dell'adapter leggere e convalidare la configurazione, che poi utilizzerà per controllare la trasmissione del messaggio. Per gli adapter di trasmissione che supportano trasmissioni in batch, i messaggi destinati a diverse porte possono trovarsi nello stesso batch, quindi l'adapter deve gestire batch "misti".
Il frammento di codice seguente illustra come leggere OutboundTransportLocation che rappresenta l'URI per la porta di invio. Viene inoltre illustrato come leggere il blob XML contenente la configurazione dell'adapter e quindi le singole proprietà.
...
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);
}
Suggerimento per l'implementazione: Gli adattatori devono usare in generale la proprietà del contesto del messaggio OutboundTransportLocation per determinare l'indirizzo a cui inviare il messaggio. In questo modo, l'adapter può gestire trasmissioni statiche e dinamiche in modo coerente. Questo semplifica inoltre la modifica degli indirizzi nei file di associazione di produzione.
XSD
Quattro file XSD inclusi nell'esempio dell'adattatore file SDK gestiscono principalmente la configurazione della scheda: ReceiveHandler.xsd, ReceiveLocation.xsd, TransmitLocation.xsd e TransmitHandler.xsd.
Negli argomenti seguenti vengono illustrati tutti e quattro i file e viene descritto come sia possibile modificarli: