Come utilizzare le espressioni per l'esecuzione delle pipeline

BizTalk Server ha la possibilità di chiamare in modo sincrono una pipeline dall'interno di un'orchestrazione. In questo modo le orchestrazioni possono sfruttare l’elaborazione dei messaggi incapsulata nelle pipeline (sia di trasmissione che di ricezione) in base a un corpo di dati senza che sia necessario inviare tali dati tramite l’infrastruttura di messaggistica.

È possibile utilizzare questa funzionalità per consentire alle orchestrazioni di chiamare pipeline di trasmissione per aggregare alcuni messaggi in un singolo interscambio in uscita. Le orchestrazioni possono invece chiamare pipeline di ricezione per decodificare e disassemblare gli interscambi ottenuti all’esterno dell’infrastruttura di messaggistica senza implementare i costi di elaborazione dovuti al passaggio nel MessageBox.

Dettagli

Le orchestrazioni usano metodi nella classe XLANGPipelineManager (nello spazio dei nomi Microsoft.XLANGs.Pipeline ) per chiamare pipeline di invio o ricezione. Le pipeline di ricezione utilizzano singoli messaggi o interscambi e restituiscono zero o più messaggi, come quando le pipeline vengono eseguite nel contesto di ricezione dei messaggi all’interno della messaggistica BizTalk. Le pipeline di trasmissione utilizzano uno o più messaggi e restituiscono singoli messaggi o interscambi, come quando le pipeline vengono eseguite nel contesto di trasmissione dei messaggi all’interno della messaggistica BizTalk.

Chiamata di una pipeline di ricezione

Per chiamare una pipeline di ricezione dall'interno di un'orchestrazione, l'applicazione chiama il metodo ExecuteReceivePipeline() della classe XLANGPipelineManager . Questo metodo utilizza un singolo interscambio e restituisce una raccolta di zero o più messaggi (contenuti in un'istanza della classe ReceivePipelineOutputMessages ). La sintassi di questo metodo è descritta in dettaglio nelle informazioni di riferimento sulla libreria di classi .NET per la classe XLANGPipelineManager .

L’API per l’esecuzione di una pipeline di ricezione dall’interno di un’orchestrazione è la seguente:

// Execute receive pipeline

static public ReceivePipelineOutputMessages ExecuteReceivePipeline(System.Type receivePipelineType, XLANGMessage msg);

Una chiamata a una pipeline di ricezione viene in genere eseguita in una forma Espressione all'interno dell'orchestrazione.

Per chiamare una pipeline di ricezione dall’interno di un’orchestrazione, lo sviluppatore deve fare riferimento all’assembly della pipeline nel progetto di orchestrazione. Di seguito viene riportato l’esempio di un’orchestrazione che chiama una pipeline di ricezione:

Per un esempio più dettagliato, vedere l'esempio SDK Compose Message Processor (BizTalk Server Sample).

Nota

Una variabile di tipo ReceivePipelineOutputMessages può essere dichiarata solo all'interno di un ambito atomico in un'orchestrazione. Ciò è dovuto al fatto che le variabili di questo tipo non sono serializzabili, quindi non mantengono la persistenza dell’orchestrazione e le orchestrazioni non vengono mai rese persistenti durante l’esecuzione all’interno di ambiti atomici. Questo significa che è possibile eseguire le pipeline di ricezione solo all’interno di un ambito atomico.

Nota

Quando si chiama la pipeline PassThruReceive o il componente della pipeline personalizzata dall'interno di un'orchestrazione, è necessario dichiarare il tipo di variabile per il messaggio in arrivo come System.Xml. XmlDocument nonostante il tipo di messaggio in arrivo sia XML o meno. Pertanto, se il messaggio in ingresso utilizzato è un messaggio non XML e ad esempio si tratta di un messaggio in formato file flat, potrebbero verificarsi alcune eccezioni in quanto il motore di orchestrazione intende utilizzare System.Xml.XmlDocument per qualsiasi tipo di messaggio in ingresso nello scenario illustrato in precedenza.

Chiamata di una pipeline di trasmissione

Per chiamare una pipeline di invio dall'interno di un'orchestrazione, l'applicazione chiama il metodo ExecuteSendPipeline() della classe XLANGPipelineManager . Questo metodo utilizza una raccolta di uno o più messaggi (contenuti in un'istanza della classe SendPipelineInputMessages ) e restituisce un singolo interscambio. La sintassi di questo metodo è descritta in dettaglio nelle informazioni di riferimento sulla libreria di classi .NET per la classe XLANGPipelineManager . Poiché l'esecuzione di una pipeline di trasmissione produce un nuovo interscambio, la chiamata al metodo ExecuteSendPipeline() deve essere eseguita all'interno di una forma di assegnazione del messaggio, ad esempio:

L’API per l’esecuzione di una pipeline di trasmissione dall’interno di un’orchestrazione è la seguente:

// Execute a send pipeline

static public ExecuteSendPipeline(System.Type sendPipelineType, SendPipelineInputMessages inputMsgs, XLANGMessage msg);

Una chiamata a una pipeline di trasmissione deve essere eseguita in una forma Assegnazione messaggi all'interno dell'orchestrazione.

Per chiamare una pipeline di trasmissione dall’interno di un’orchestrazione, lo sviluppatore deve fare riferimento all’assembly della pipeline nel progetto di orchestrazione. Di seguito viene riportato l’esempio di un’orchestrazione che chiama una pipeline di trasmissione:

Nota

Quando si chiama la pipeline XMLTransmit predefinita, è necessario impostare la proprietà del contesto del messaggio XMLNORM.EnvelopeSpecName sul nome completo dello schema della busta. Ad esempio:

MyMessage(XMLNORM.EnvelopeSpecName) = "PipelineSchemas.POEnv, PipelineSchemas, Version=1.0.0.0, Culture=nuetral, PublicKeyToken=12e5cc95621c33e8";

Per un esempio più dettagliato, vedere l'esempio sdk Aggregator (BizTalk Server Sample).

Esecuzione pipeline - Differenze funzionali

L’esecuzione delle pipeline di trasmissione o ricezione chiamate dalle orchestrazioni è pressoché identica all’esecuzione delle stesse pipeline all’interno dell’infrastruttura di messaggistica (ad esempio su indirizzi di ricezione o porte di trasmissione). Esistono tuttavia alcune differenze funzionali che vengono illustrate di seguito.

Differenze all’interno delle fasi della pipeline

L’esecuzione delle fasi di una pipeline di trasmissione o ricezione che viene chiamata dall’interno di un’orchestrazione è pressoché identica all’esecuzione delle stesse fasi in cui la pipeline viene chiamata dall’infrastruttura di messaggistica BizTalk, tranne che per le eccezioni illustrate di seguito.

• Assembler/Disassembler: le fasi dell'assembler e del disassembler non elaborano i dati del profilo di rilevamento .

• Codificatore/decodificatore: il codificatore MIME firma digitalmente i messaggi usando il certificato configurato nell'host a cui è associato l'host. Il codificatore SMIME crittografa i messaggi mediante il certificato presente nel contesto del messaggio passato nella pipeline.

Risoluzione dello schema

Esistono due algoritmi di ricerca degli schemi supportati durante l’esecuzione di una pipeline da un’orchestrazione:

• Risoluzione in base al tipo

• Risoluzione in base al nome

  Nei casi in cui vengono distribuiti schemi duplicati, la logica dell’algoritmo per la sezione dello schema appropriato è identica a quella utilizzata durante l’esecuzione nel contesto dell’infrastruttura di messaggistica.

Pipeline transazionali

Le pipeline le cui fasi prevedono chiamate a componenti transazionali non includeranno alcun contesto transazionale disponibile. Qualsiasi chiamata a IPipelineContext.GetTransaction() genererà NotSupportedException. Questa condizione, anche se non preclude l’esecuzione di tali pipeline da un’orchestrazione, dovrà essere rilevata e gestita dalla pipeline.

Destinazione dei messaggi

Il controllo della destinazione dei messaggi tramite i componenti delle pipeline non è supportato in questo contesto. Se si impostano le proprietà di contesto MessageDestination o SuspendOnRoutingFailure , verrà generata un'eccezione XLANGPipelineManagerException .

Tipi di componenti delle pipeline

Per essere chiamati dall’interno di un’orchestrazione, i componenti delle pipeline devono essere basati su:

• .NET Framework v1.1

• .NET Framework v2.0

• .NET Framework v3.0

• .NET Framework v3.5

• .NET Framework v4.0

• .NET Framework v2.0

• COM

Restrizioni

Non è possibile eseguire i tipi di pipeline seguenti dall'interno di un'orchestrazione:

• Pipeline transazionali

• Pipeline reversibili

• Pipeline che chiamano l'API dell'intercettore BAM (verrà generata un'eccezione NotSupportedException ).

• Uguali istanze di pipeline non possono essere eseguite in diversi rami della forma parallela a meno che non vengano incluse in un ambito sincronizzato in ogni ramo.

• Pipeline esistenti (assembly) compilati con BizTalk Server SDK 2006.

Modalità di errore ed effetti

Tutti gli errori di esecuzione delle pipeline che avrebbero causato messaggi sospesi alla chiamata delle pipeline dall’interno di un’infrastruttura di messaggistica di BizTalk Server, causeranno invece la generazione di un’eccezione. L'eccezione generata è di tipo Microsoft.XLANGs.Pipeline.XLANGPipelineManagerException. Tale eccezione può essere gestita in un blocco catch all’interno dell’orchestrazione chiamante. Se l’orchestrazione non rileva l’eccezione generata, il motore XLANGs segnalerà un errore in cui sono incluse informazioni sull’eccezione generata.

L’eccezione esegue la formattazione dei messaggi di errore generati dai componenti della pipeline.

La proprietà Message della classe XLANGPipelineManagerException contiene i dettagli dell'errore di esecuzione della pipeline. I dettagli vengono indicati in base al formato seguente:

• Errore durante l'esecuzione del tipo di> pipeline<. Messaggio di errore formattato nei dettagli <dell'errore>.

  In questo messaggio, <il tipo di> pipeline è il nome della classe della pipeline e <il messaggio> di errore formattato è una descrizione dell'errore specifico che si è verificato durante l'esecuzione della pipeline.

  Ad esempio, se un'orchestrazione chiama una pipeline di ricezione e l'esecuzione della pipeline ha esito negativo perché nessuno dei componenti della pipeline riconosce il messaggio, i valori delle proprietà di XLANGPipelineManagerException sono:

Proprietà XLANGPipelineManagerException	Valore
Messaggio	Si è verificato un errore durante l’esecuzione della pipeline di ricezione "MyPipelines.ReceivePipeline". Dettagli errore: "Nessun componente della fase disassemble può riconoscere i dati.
Componente	String.Empty

Come altro esempio, se un'orchestrazione chiama una pipeline di trasmissione e l'esecuzione della pipeline ha esito negativo perché si verifica un errore di convalida, il testo nella proprietà Message di XLANGPipelineManagerException sarà:

Proprietà XLANGPipelineManagerException	Valore
Messaggio	Si è verificato un errore durante l’esecuzione della pipeline di trasmissione "MyPipelines.SendPipeline". Dettagli errore: "Impossibile convalidare il documento: "L'elemento <del nome> dell'elemento non è valido - Il valore dell'elemento valore <> non è valido in base al tipo di dati 'String' - Il vincolo Pattern non è riuscito"."
Componente	“Microsoft.BizTalk.Component.XmlValidator”