Come usare le espressioni per eseguire le pipeline

BizTalk Server ha la possibilità di chiamare in modo sincrono una pipeline dall'interno di un'orchestrazione. Ciò consente alle orchestrazioni di sfruttare l'elaborazione dei messaggi incapsulata all'interno di una pipeline (invio o ricezione) su un corpo di dati senza dover inviare tali dati tramite l'infrastruttura di messaggistica.

È possibile usare questa funzionalità per consentire a un'orchestrazione di chiamare una pipeline di invio per aggregare diversi messaggi in un singolo interscambio in uscita. Al contrario, un'orchestrazione potrebbe chiamare una pipeline di ricezione per decodificare e disassemblare un interscambio ottenuto all'esterno dell'infrastruttura di messaggistica, senza incorrere nei costi di elaborazione associati al passaggio attraverso la MessageBox.

Dettagli

Le orchestrazioni usano metodi nella classe XLANGPipelineManager (nello spazio dei nomi Microsoft.XLANGs.Pipeline ) per chiamare pipeline di invio o ricezione. Una pipeline di ricezione utilizza un singolo messaggio o un interscambio e restituisce zero o più messaggi, proprio come quando la pipeline viene eseguita nel contesto di ricezione di un messaggio all'interno della messaggistica BizTalk. Una pipeline di invio utilizza uno o più messaggi e restituisce di nuovo un singolo messaggio o interscambio, proprio come quando la pipeline viene eseguita nel contesto dell'invio di un messaggio all'interno della messaggistica BizTalk.

Chiamare 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 è:

// 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 è riportato un esempio di orchestrazione che chiama una pipeline di ricezione:

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

Annotazioni

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 e pertanto non sopravviverebbero alla persistenza dell'orchestrazione e le orchestrazioni non vengono mai mantenute durante l'esecuzione all'interno di un ambito atomico. Ciò significa che una pipeline di ricezione può essere eseguita solo all'interno di un ambito atomico.

Annotazioni

Quando si chiama la pipeline PassThruReceive o un componente della pipeline personalizzato dall'interno di un'orchestrazione, è necessario dichiarare come System.Xml.XmlDocument il tipo di variabile del messaggio in arrivo, indipendentemente dal fatto che il tipo di messaggio in arrivo sia XML o meno. Pertanto, è possibile che si verifichi un'eccezione se si tenta di operare su di esso se il messaggio in arrivo è un messaggio non XML, ad esempio un messaggio in formato file flat. Ciò è dovuto al fatto che il motore di orchestrazione intende usare System.Xml.XmlDocument per qualsiasi tipo di messaggio in arrivo nello scenario descritto in precedenza.

Chiamata di una pipeline di trasmissione

Per chiamare una pipeline di trasmissione 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 è:

// Execute a send pipeline

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

Una chiamata ad una pipeline di invio deve essere eseguita in una forma di 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. Esempio di orchestrazione che chiama una pipeline di trasmissione:

Annotazioni

Quando si chiama la pipeline XMLTransmit predefinita, è necessario impostare la proprietà del contesto del messaggio XMLNORM. EnvelopeSpecName per il nome completo dello schema Envelope. Per esempio:

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

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

Esecuzione della pipeline - Differenze comportamentali

L'esecuzione di una pipeline di invio o ricezione quando viene chiamata da un'orchestrazione è principalmente uguale a quando la stessa pipeline viene eseguita all'interno dell'infrastruttura di messaggistica (ad esempio, nella posizione di ricezione o nella porta di trasmissione). Esistono tuttavia alcune differenze comportamentali indicate di seguito.

Differenze nelle fasi della pipeline

L'esecuzione delle fasi all'interno di una pipeline di invio o ricezione chiamata dall'interno di un'orchestrazione è quasi identica all'esecuzione di tali fasi quando la pipeline viene chiamata dall'infrastruttura di messaggistica BizTalk, ad eccezione di quelle indicate di seguito per ciascuna fase.

• 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 usando il certificato nel contesto del messaggio passato nella pipeline.

Risoluzione dello schema

Durante l'esecuzione di una pipeline da un'orchestrazione sono supportati due algoritmi di ricerca dello schema:

• Risoluzione per tipo

• Risoluzione in base al nome

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

Pipeline transazionali

Le pipeline le cui fasi chiamano componenti transazionali non avranno un contesto transazionale disponibile. Qualsiasi chiamata a IPipelineContext.GetTransaction() genererà NotSupportedException. Ciò non impedisce l'esecuzione di una pipeline del genere tramite un'orchestrazione, ma significa che la pipeline dovrà rilevare e gestire questa situazione.

Destinazione messaggio

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

Tipi di componenti della pipeline

Per poter essere chiamati dall'interno di un'orchestrazione, è necessario che i componenti della pipeline siano basati sugli elementi seguenti:

• .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 all'interno di un'orchestrazione:

• Pipeline transazionali

• Pipeline recuperabili

• Le pipeline che chiamano l'API dell'intercettore BAM causeranno la generazione di un'eccezione NotSupportedException.

• La stessa istanza della pipeline non può essere eseguita in rami diversi della forma parallela, a meno che non venga inserita in un ambito sincronizzato in ogni ramo.

• Pipeline esistenti (assemblies) sviluppate con l'SDK di BizTalk Server 2006.

Modalità di guasto ed effetti

Qualsiasi errore nell'esecuzione della pipeline che avrebbe comportato un messaggio sospeso se questa pipeline fosse stata chiamata all'interno dell'infrastruttura di messaggistica di BizTalk Server, genererà invece un'eccezione. L'eccezione generata è di tipo Microsoft.XLANGs.Pipeline.XLANGPipelineManagerException. Questa eccezione generata può essere gestita in un blocco catch all'interno dell'orchestrazione chiamante. Se l'orchestrazione non rileva l'eccezione generata, il motore XLANGs segnala un errore il testo del quale include le 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. Questo dettaglio è nel formato seguente:

• Si è verificato un errore durante l'esecuzione della pipeline di tipo < tipo di pipeline >. Dettagli sull'errore <nel messaggio formattato>.

  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à XLANGPipelineManagerException saranno:

Proprietà XLANGPipelineManagerException	Valore
Messaggio	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	Errore durante l'esecuzione della pipeline di trasmissione "MyPipelines.SendPipeline". Dettagli errore: "Impossibile convalidare il documento: "Il nome dell'elemento <> non è valido - Il valore <valore dell'elemento> non è valido in base al tipo di dati 'String' - Il vincolo 'Pattern' non è stato rispettato.""
Componente	"Microsoft.BizTalk.Component.XmlValidator"