Composed Message Processor (esempio di BizTalk Server)
Lo scopo di questo esempio consiste nella creazione di un'applicazione processore di messaggi composti che elabora singole righe da messaggi aggregati.
In particolare, verrà creata una pianificazione dell'orchestrazione per eseguire le attività seguenti:
Ricezione di un messaggio di interscambio batch costituito da più ordini di acquisto.
Disassemblaggio del messaggio di interscambio in singoli documenti di ordine di acquisto.
Elaborazione di ogni documento e conversione di ogni ordine di acquisto in un messaggio di fatturazione.
Assemblaggio di tutti i messaggi di fatturazione in un interscambio batch.
Il passaggio 3 è semplificato nell'ambito dell'esempio. Ad esempio, in applicazioni più complesse è possibile che un'orchestrazione invii ordini di acquisto disassemblati a più sistemi di gestione scorte back-end e quindi, dopo avere raccolto tutte le risposte, le aggreghi in un messaggio di fatturazione in batch.
Per ulteriori informazioni sul modello processore di messaggi composti, fare riferimento a [1].
Scopo dell'esempio
Nella soluzione di esempio sono inclusi due progetti, che sono descritti in dettaglio nelle sezioni seguenti.
Pipeline e schemi
Il progetto di pipeline e schemi contiene:
Schemi file flat per l'interscambio dell'ordine di acquisto di input e per l'interscambio della fattura di output.
Mappa per trasformare il documento di ordine di acquisto in un documento fattura.
Pipeline di ricezione e trasmissione.
Schemi file flat per gli interscambi di input e output
L'applicazione di esempio verrà utilizzata con gli interscambi nel formato file flat. Di seguito sono riportati alcuni esempi di interscambio relativo all'ordine di acquisto e alla fattura:
Interscambio di ordine di acquisto (CMPInput.txt):
Northwind Shipping
Batch type:Purchase Orders
PO1999-10-20
US Alice Smith 123 Maple Street Mill Valley CA 90952
US Robert Smith 8 Oak Avenue Old Town PA 95819
Hurry, my lawn is going wild!
ITEMS,ITEM872-AA|Lawnmower|1|148.95|Confirm this is electric,ITEM926-AA|Baby Monitor|1|39.98|Confirm this is electric|1999-10-21
PO1999-10-21
US John Dow 123 Elm Street Mill Valley CA 90952
US July Dow 8 Pine Avenue Old Town PA 95819
Please ship it urgent!
ITEMS,ITEM398-BB|Tire|4|324.99|Wrap them up nicely,ITEM201-BB|Engine Oil|1|12.99|SAE10W30|1999-05-22
PO1999-10-23
US John Connor 123 Cedar Street Mill Valley CA 90952
US Sarah Connor 8 Grass Avenue Old Town PA 95819
Use cheapest shipping method.
ITEMS,ITEM101-TT|Plastic flowers|10|4.99|Fragile handle with care,ITEM202-RR|Fertilizer|1|10.99|Lawn fertilizer,ITEM453-XS|Weed killer|1|5.99|Lawn weed killer|1999-05-25
L'interscambio, o documento di ordine di acquisto, include un'intestazione che identifica il tipo di documenti che contiene:
Northwind Shipping
Batch type:Purchase Orders
Questo interscambio è costituito da tre documenti di ordine di acquisto. Un'istanza è costituita dalle informazioni indicate di seguito. Come si nota, contiene informazioni quali l'indirizzo di fatturazione e di spedizione e l'elenco degli articoli ordinati.
PO1999-10-20
US Alice Smith 123 Maple Street Mill Valley CA 90952
US Robert Smith 8 Oak Avenue Old Town PA 95819
Hurry, my lawn is going wild!
ITEMS,ITEM872-AA|Lawnmower|1|148.95|Confirm this is electric,ITEM926-AA|Baby Monitor|1|39.98|Confirm this is electric|1999-10-21
L'interscambio relativo alla fattura che verrà generato a questo scopo sarà analogo al seguente:
Northwest Shipping
DocumentTypes:Invoices
INVOICE1999-10-20
BILLTO,US,Alice Smith,123 Maple Street,Mill Valley,CA,90952
872-AA Lawnmower 1 148.95 Confirm this is electric
926-AA Baby Monitor 1 39.98 Confirm this is electric
INVOICE1999-10-21
BILLTO,US,John Dow,123 Elm Street,Mill Valley,CA,90952
398-BB Tire 4 324.99 Wrap them up nicely
201-BB Engine Oil 1 12.99 SAE10W30
INVOICE1999-10-20
BILLTO,US,John Connor,123 Cedar Street,Mill Valley,CA,90952
101-TT Plastic flowers 10 4.99 Fragile handle with care
202-RR Fertilizer 1 10.99 Lawn fertilizer
453-XS Weed killer 1 5.99 Lawn weed killer
Questo interscambio contiene un subset di informazioni prelevato dall'interscambio dell'ordine di acquisto e anche il formato dell'interscambio e dell'intestazione sono diversi.
L'intestazione risulta come segue:
Northwest Shipping
DocumentTypes:Invoices
E l'istanza del documento include quanto segue:
INVOICE1999-10-20
BILLTO,US,Alice Smith,123 Maple Street,Mill Valley,CA,90952
872-AA Lawnmower 1 148.95 Confirm this is electric
926-AA Baby Monitor 1 39.98 Confirm this is electric
In primo luogo è necessario creare gli schemi file flat per:
Documento di ordine di acquisto (PO.xsd)
Documento di fattura (Invoice.xsd)
Intestazione dell'ordine di acquisto (POHeader.xsd)
Intestazione della fattura (InvoiceHeader.xsd)
Per questo esempio verrà descritto il processo di creazione di schemi flat file. Per informazioni sulla creazione di schemi flat file da istanze di documento, fare riferimento alla sezione della documentazione "Creazione di uno schema di file flat da un'istanza di documento".
Mappa per la trasformazione di un documento di ordine di acquisto in un documento fattura
La mappa (PO2Invoice.btm) consente di trasformare un'istanza dell'ordine di acquisto in un documento fattura.
Pipeline di ricezione e trasmissione
La pipeline di ricezione (FFReceivePipeline.btp) contiene un componente disassembler del file flat utilizzato per elaborare un interscambio di ordine di acquisto. In particolare, per l'interscambio nel file CMPInput.txt, rimuove l'intestazione interscambio e produce tre documenti XML corrispondenti a tre ordini di acquisto.
Il disassembler del file flat nella pipeline di ricezione è configurato come segue:
Schema documento: PipelinesAndSchemas.PO
Schema intestazione: PipelinesAndSchemas.POHeader
Mantieni intestazione: False
Interscambio recuperabile: False
Schema trailer: (Nessuno)
Convalidare la struttura del documento: False
La pipeline di trasmissione (FFSendPipeline.btp) contiene un componente assembler di flat file utilizzato per creare l'interscambio della fattura aggregata.
L'assembler di file flat nella pipeline di trasmissione è configurato come segue:
Schema documento: PipelinesandSchemas.Invoice
Schema intestazione: PipelinesAndSchemas.InvoiceHeader
Mantieni il contrassegno di ordine dei byte: False
Set di caratteri di destinazione: (Nessuno)
Schema trailer: (Nessuno)
Pianificazione dell'orchestrazione
La pianificazione dell'orchestrazione (CMP.odx) è il punto in cui avviene l'elaborazione principale. Vengono eseguite in modo specifico le operazioni seguenti:
Viene eseguita la pipeline di ricezione per disassemblare l'interscambio dell'ordine di acquisto
Viene trasformato ogni messaggio di output della pipeline di ricezione
Viene eseguita la pipeline di trasmissione per assemblare un interscambio relativo alla fattura
Creazione della pianificazione dell'orchestrazione e definizione delle variabili globali
L'orchestrazione riceverà un interscambio flat file come input e invierà un interscambio flat file come output. È quindi necessario definire i messaggi di input e output (denominati rispettivamente InputInterchange e OutputInterchange) come indipendenti dal tipo, ovvero di tipo System.Xml.XmlDocument.
Inoltre, è necessario definire un ambito atomico in cui si eseguirà l'elaborazione dei messaggi. Questa operazione è necessaria perché la pipeline di ricezione può essere eseguita all'interno di un ambito atomico.
Esecuzione della pipeline di ricezione
Il passaggio successivo consiste nell'aggiunta di logica per l'esecuzione di una pipeline di ricezione per il messaggio ricevuto in un'orchestrazione. A questo scopo, viene innanzitutto dichiarata una variabile (denominata RcvPipeOutput) di tipo Microsoft.XLANGs.Pipeline.ReceivePipelineOutputMessages all'interno dell'ambito. La variabile è un enumeratore che consente di elaborare ciclicamente i messaggi di output della pipeline di ricezione. Tenere presente che per accedere a questo tipo e a tutti gli altri tipi di esecuzione di pipeline dall'orchestrazione è necessario aggiungere riferimenti agli assembly seguenti:
Microsoft.XLANGs.Pipeline.dll
Microsoft.BizTalk.Pipeline.dll
Non è garantito che la pipeline di ricezione venga sempre eseguita correttamente. È possibile che i messaggi siano in formato non corretto, con conseguente esito negativo dell'elaborazione della pipeline. Quando l'esecuzione di una pipeline ha esito negativo nell'orchestrazione, viene generata un'eccezione che può essere rilevata ed è possibile eseguire la logica di gestione degli errori. Per rilevare l'eccezione generata dalla pipeline, è necessario eseguire la pipeline con un ambito non atomico con gestione delle eccezioni. Il codice effettivo per l'esecuzione della pipeline viene richiamato da una forma Espressione all'interno di tale ambito.
Nella forma Espressione ExecuteRcvPipe scrivere la seguente riga di codice per eseguire la pipeline di ricezione:
RcvPipeOutput = Microsoft.XLANGs.Pipeline.XLANGPipelineManager.ExecuteReceivePipeline(typeof(PipelinesAndSchemas.FFReceivePipeline), InputInterchange);
È opportuno analizzare questa riga di codice in modo più dettagliato. Come si nota, viene chiamato un metodo statico ExecuteReceivePipeline che richiede come parametro un tipo di pipeline di ricezione da eseguire e un messaggio di input. Di conseguenza, produce un oggetto enumeratore con il set di messaggi di output. Il risultato viene assegnato a una variabile di tipo ReceivePipelineOutputMessages definita precedentemente nell'ambito.
È stato inoltre incluso un blocco per la gestione delle eccezioni per l'ambito di esecuzione della pipeline. Questo blocco rileva l'eccezione di tipo XLANGPipelineManagerException e successivamente, per semplicità, termina semplicemente un'istanza di orchestrazione con un messaggio di errore personalizzato.
In scenari più complessi possono essere eseguite ulteriori attività di gestione degli errori, quali la generazione di messaggi di notifica di errore e il relativo invio a un utente di business o a un amministratore tramite posta elettronica.
Trasformazione dei messaggi di output della pipeline
Dopo l'esecuzione della pipeline e la produzione del set di messaggi disassemblati, è necessario trasformare i singoli messaggi di output in un formato diverso.
Per utilizzare la trasformazione nell'orchestrazione è necessario definire due messaggi: input e output della trasformazione. Questi messaggi verranno definiti all'interno dell'ambito atomico. Il messaggio di input della trasformazione denominato TmpMessageIn sarà di tipo PipelinesAndSchemas.PO. Il messaggio di output della trasformazione denominato TmpMessageOut sarà di tipo PipeliensAndSchemas.Invoice. Verrà applicata la mappa PO2Invoice.btm definita nel progetto PipelinesAndSchemas.
Per mappare ogni messaggio di output della pipeline, è necessario eseguire la trasformazione all'interno del ciclo. Si utilizzerà una forma Ciclo con la condizione di uscita che segue:
RcvPipeOutput.MoveNext()
Il metodo MoveNext() è un metodo standard dell'interfaccia .NET IEnumerator che consente di spostarsi all'interno dell'insieme di messaggi di output della pipeline. Quando raggiunge la fine dell'insieme, restituisce false.
La prima forma di costruzione viene utilizzata per costruire un messaggio di orchestrazione TmpMessageIn dal messaggio di output della pipeline.
Codice nella forma di costruzione:
TmpMessageIn = null;
RcvPipeOutput.GetCurrent(TmpMessageIn);
In questo codice, il messaggio dell'orchestrazione viene inizializzato su null e quindi viene impostato sul messaggio corrente dall'insieme di messaggi di output della pipeline.
Nella seconda forma di costruzione viene eseguita la trasformazione effettiva di TmpMessageIn e viene costruito il messaggio TmpMessageOut di tipo PipelinesAndSchemas.Invoice.
Esecuzione della pipeline di trasmissione
L'ultimo passaggio di elaborazione nell'orchestrazione consiste nell'esecuzione della pipeline di trasmissione del flat file per assemblare tutti i messaggi XML trasformati in un interscambio flat file.
Per eseguire una pipeline di trasmissione è necessario utilizzare una variabile di tipo Microsoft.XLANGs.Pipeline.SendPipelineInputMessages denominata SendPipeInput che conterrà un insieme di messaggi di orchestrazione che devono essere elaborati in una pipeline di trasmissione.
Nell'ultima espressione del ciclo in cui è stata eseguita la trasformazione verrà scritto un codice che determinerà l'aggiunta di ogni messaggio trasformato a un insieme di messaggi per la pipeline di trasmissione:
SendPipeInput.Add(TmpMessageOut);
Analogamente alla parte in cui viene eseguita la pipeline di ricezione, il codice per l'esecuzione della pipeline di trasmissione viene posizionato all'interno di un ambito non atomico con un blocco di gestione delle eccezioni. Il codice di esecuzione della pipeline di trasmissione si trova nella forma Assegnazione messaggio del blocco di costrutto.
OutputInterchange = null;
Microsoft.XLANGs.Pipeline.XLANGPipelineManager.ExecuteSendPipeline(typeof(PipelinesAndSchemas.FFSendPipeline), SendPipeInput, OutputInterchange);
Il blocco di costrutto viene utilizzato per costruire il messaggio di output della pipeline OutputInterchange indipendente dal tipo, ovvero System.Xml.XmlDocument. Quindi, nella forma Assegnazione messaggio il messaggio costruito viene inizializzato su null. Successivamente, viene richiamato il metodo statico ExecuteSendPipeline per l'esecuzione di una pipeline di trasmissione. Questo metodo accetta come parametro un tipo di pipeline di trasmissione da eseguire, il messaggio di input e il riferimento al messaggio di output in cui verrà archiviato l'output della pipeline.
Come per l'esecuzione della pipeline di ricezione, anche in questo caso è presente un blocco di gestione delle eccezioni per l'ambito di esecuzione della pipeline. Questo blocco rileva l'eccezione di tipo XLANGPipelineManagerException e successivamente, per semplicità, termina semplicemente un'istanza di orchestrazione con un messaggio di errore personalizzato.
Percorso dell'esempio
Nella tabella seguente vengono elencati i file di questo esempio.
| File | Descrizione |
|---|---|
| Cleanup.bat | Viene utilizzato per annullare la distribuzione degli assembly e rimuoverli dalla Global Assembly Cache. Consente inoltre di rimuovere porte di trasmissione e ricezione. Consente infine di rimuovere le directory virtuali di Microsoft Internet Information Services (IIS), se necessario. |
| ComposedMessageProcessor.sln | File di soluzione Visual Studio per l'esempio. |
| ComposedMessageProcessorBinding.xml | File di associazione per l'esempio. |
| Setup.bat | Utilizzato per compilare e inizializzare l'esempio. |
| Nella cartella Orchestration: CMP.odx |
Orchestrazione che esegue la pipeline di ricezione per disassemblare il messaggio, trasforma ogni messaggio disassemblato e quindi esegue la pipeline di trasmissione per assemblare i messaggi in un interscambio. |
| Nella cartella Orchestration: Orchestration.btproj |
Progetto BizTalk per l'orchestrazione. |
| Nella cartella Orchestration: SuspendMessage.odx |
Orchestrazione utilizzata per sospendere i messaggi per i quali l'elaborazione della pipeline ha esito negativo. |
| Nella cartella PipelinesAndSchemas: CMPInput.xml, CMPOutput.xml |
Istanze dei documenti di input e output per l'esempio. |
| Nella cartella PipelinesAndSchemas: FFReceivePipeline.btp, FFSendPipeline.btp |
Pipeline di ricezione e trasmissione con componenti flat file. Queste pipeline vengono eseguite all'interno dell'orchestrazione. |
| Nella cartella PipelinesAndSchemas: Invoice.xsd, InvoiceHeader.xsd |
Schemi file flat per il documento di output e l'intestazione. |
| Nella cartella PipelinesAndSchemas: PO.xsd, POHeader.xsd |
Schemi file flat per il documento di input e l'intestazione. |
| Nella cartella PipelinesAndSchemas: PropertySchema.xsd |
Schema proprietà per l'esempio. |
Compilazione e inizializzazione dell'esempio
Utilizzare la procedura seguente per compilare e inizializzare l'esempio Compose.
Per compilare e inizializzare l'esempio Compose
In una finestra di comando passare alla seguente cartella:
<Percorso> esempi\Pipelines\ComposeMessageProcessor
Eseguire il file Setup.bat. Verranno eseguite le operazioni seguenti:
Crea le cartelle di input (In) e output (Out) dell'esempio nella cartella:
<Percorso> esempi\Pipelines\ComposeMessageProcessor
Compilazione di progetti di Visual Studio per l'esempio.
Creazione di una nuova applicazione denominata "CMP Sample" in cui vengono distribuiti gli assembly di esempio.
Creazione e binding dell'indirizzo di ricezione di BizTalk e delle porte di trasmissione e ricezione.
Integrazione e avvio dell'orchestrazione, abilitazione dell'indirizzo di ricezione e avvio della porta di trasmissione.
Se si sceglie di aprire e compilare i progetti dell'esempio senza eseguire il file Setup.bat, è necessario creare prima una coppia di chiavi con nome sicuro utilizzando l'utilità Nome sicuro di .NET Framework (sn.exe). Utilizzare questa coppia di chiavi per firmare gli assembly risultanti.
Prima di tentare di eseguire l'esempio, verificare che in BizTalk Server non siano stati segnalati errori durante il processo di compilazione e inizializzazione.
Per annullare le modifiche apportate da Setup.bat, eseguire le operazioni seguenti:
Arrestare e riavviare l'istanza dell'host dalla Console di amministrazione BizTalk Server.
Eseguire Cleanup.bat. È necessario eseguire Cleanup.bat prima di eseguire Setup.bat una seconda volta.
Esecuzione dell'esempio
Utilizzare la procedura seguente per eseguire l'esempio ComposedMessageProcessor.
Per eseguire l'esempio ComposedMessageProcessor
Copiare il file di testo CMPInput.txt che si trova nella cartella PipelinesAndSchemas. Incollarlo nella cartella In.
Osservare il file di testo creato nella cartella Out. Questo file contiene gli stessi record del CMPInput.txt, ma il formato dei dati nel file è diverso.
Quando il messaggio passa attraverso BizTalk Server, si verifica quanto segue:
Il messaggio viene disassemblato e convertito in messaggi XML. Ogni messaggio viene mappato a un formato diverso.
Tutti i messaggi mappati vengono assemblati e convertiti nel formato file flat.