Cómo usar expresiones para ejecutar canalizaciones

BizTalk Server tiene la capacidad de llamar de manera síncrona a una canalización desde dentro de una orquestación. Esto permite que las orquestaciones utilicen con eficacia el procesamiento de mensajes encapsulado dentro de una canalización (ya sea de envío o recepción) aplicándolo a un conjunto de datos sin la necesidad de enviar esos datos a través de la infraestructura de mensajería.

Puede usar esta función para habilitar que una orquestación llame a una canalización de envío para agregar varios mensajes en un único intercambio de datos saliente. Por el contrario, una orquestación podría llamar a una canalización de recepción para descodificar y desensamblar un intercambio obtenido fuera de la infraestructura de mensajería, sin incurrir en los costos de procesamiento de pasar por el cuadro de mensaje.

Detalles

Las orquestaciones usan métodos en la clase XLANGPipelineManager (en el espacio de nombres Microsoft.XLANGs.Pipeline ) para llamar a canalizaciones de envío o recepción. Una canalización de recepción consume un único mensaje o un intercambio y produce cero o más mensajes, al igual que cuando la canalización se ejecuta en el contexto de recibir un mensaje dentro de la mensajería de BizTalk. Una canalización de envío consume uno o varios mensajes y produce un único mensaje o intercambio, de nuevo, al igual que cuando la canalización se ejecuta en el contexto de enviar un mensaje dentro de la mensajería de BizTalk.

Llamar a una canalización de recepción

Para llamar a una canalización de recepción desde dentro de una orquestación, la aplicación llama al método ExecuteReceivePipeline() de la clase XLANGPipelineManager . Este método consume un único intercambio y devuelve una colección de cero o más mensajes (contenidos en una instancia de la clase ReceivePipelineOutputMessages ). La sintaxis de este método se detalla en la referencia de la biblioteca de clases de .NET para la clase XLANGPipelineManager .

La API para ejecutar una canalización de recepción desde dentro de una orquestación es:

// Execute receive pipeline

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

Normalmente, una llamada a una canalización de recepción se realizaría en una forma expresión dentro de la orquestación.

Para llamar a una canalización de recepción desde dentro de una orquestación, el desarrollador debe hacer referencia al ensamblado de canalización en el proyecto de orquestación. A continuación se muestra un ejemplo de una orquestación que llama a una canalización de recepción:

Para obtener un ejemplo más detallado, consulte el ejemplo del SDK procesador de mensajes compuestos (ejemplo de BizTalk Server).

Nota:

Una variable de tipo ReceivePipelineOutputMessages solo se puede declarar dentro de un ámbito atómico en una orquestación. Esto se debe a que las variables de este tipo no son serializables y, por tanto, no sobrevivirían a la persistencia de la orquestación, y las orquestaciones nunca se conservan mientras se ejecutan dentro de un ámbito atómico. Esto significa que una canalización de recepción solo se puede ejecutar dentro de un ámbito atómico.

Nota:

Al llamar a la canalización PassThruReceive o al componente de canalización personalizado desde una orquestación, debe declarar el tipo de variable para el mensaje entrante como System.Xml.XmlDocument a pesar de que el tipo de mensaje entrante es XML o no. Por lo tanto, es posible que encuentre una excepción si intenta operar en él si el mensaje entrante es un mensaje que no es XML, como un mensaje de formato de archivo plano. Esto se debe a que ese motor de orquestación pretende usar System.Xml.XmlDocument para cualquier tipo de mensaje entrante en el escenario descrito anteriormente.

Llamar a una canalización de envío

Para llamar a una canalización de envío desde una orquestación, la aplicación llama al método ExecuteSendPipeline() de la clase XLANGPipelineManager. Este método consume una colección de uno o varios mensajes (contenidos en una instancia de la clase SendPipelineInputMessages ) y devuelve un único intercambio. La sintaxis de este método se detalla en la referencia de la biblioteca de clases de .NET para la clase XLANGPipelineManager . Dado que la ejecución de una canalización de envío produce un nuevo intercambio, la llamada al método ExecuteSendPipeline() debe realizarse dentro de una forma de asignación de mensajes, como tal:

La API para ejecutar una canalización de envío desde dentro de una orquestación es:

// Execute a send pipeline

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

Una llamada a una canalización de envío debe realizarse en una forma de asignación de mensajes dentro de la orquestación.

Para llamar a una tubería de envío desde una orquestación, el desarrollador debe referenciar el ensamblado de la tubería en el proyecto de orquestación. Ejemplo de una orquestación que llama a una canalización de envío:

Nota:

Al llamar a la canalización predeterminada XMLTransmit, debe establecer la propiedad de contexto del mensaje XMLNORM.EnvelopeSpecName al nombre completamente cualificado del esquema Envelope. Por ejemplo:

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

Para obtener un ejemplo más detallado, consulte el agregador de ejemplo del SDK (ejemplo de BizTalk Server).

Ejecución de canalización: diferencias en el comportamiento

La ejecución de una canalización de envío o recepción cuando es llamada por una orquestación es, en su mayoría, la misma que cuando se ejecuta dentro de la infraestructura de mensajería (es decir, en la ubicación de recepción o en el puerto de envío). Sin embargo, hay ciertas diferencias de comportamiento que se indican a continuación.

Diferencias en las fases de canalización

La ejecución de las etapas dentro de una canalización de envío o recepción a la que se llama desde una orquestación es casi idéntica a la ejecución de esas etapas cuando se llama a la canalización desde la infraestructura de mensajería de BizTalk, con las excepciones indicadas a continuación por etapa.

• Ensamblador/Desensamblador: las fases de ensamblador y desensamblaje no procesarán los datos del perfil de seguimiento .

• Codificador o descodificador: el codificador MIME firma digitalmente los mensajes mediante el certificado configurado en el host con el que está asociado el host. El codificador SMIME cifra los mensajes utilizando el certificado en el contexto del mensaje pasado a la tubería de procesamiento.

Resolución de esquemas

Hay dos algoritmos de búsqueda de esquema que se admiten cuando se ejecuta un pipeline desde una orquestación.

• Resolución por tipo

• Resolución por nombre

  En los casos en los que se implementan esquemas duplicados, la lógica del algoritmo para seleccionar el esquema adecuado es idéntica a la que se usa al ejecutarse en el contexto de la infraestructura de mensajería.

Tuberías transaccionales

Canalizaciones cuyas fases llaman a componentes transaccionales no tendrán disponible un contexto transaccional. Cualquier llamada a IPipelineContext.GetTransaction() producirá NotSupportedException. Esto no impide la ejecución de dicha canalización desde una orquestación, pero significa que la canalización tendrá que detectar y controlar esta situación.

Destino del mensaje

No se admite el control del destino del mensaje por componentes de canalización en este contexto. Si se establecen las propiedades de contexto MessageDestination o SuspendOnRoutingFailure, se producirá una Excepción XLANGPipelineManagerException.

Tipos de componentes de canalización

Los componentes de la canalización deben basarse en los siguientes criterios para poder ser llamados desde dentro de una orquestación.

• .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

Restricciones

Los siguientes tipos de canalizaciones no pueden ejecutarse dentro de una orquestación.

• Canalizaciones transaccionales

• Canalizaciones recuperables

• Tuberías que invocan la API del interceptor de BAM (se lanzará una excepción de tipo NotSupportedException).

• La misma instancia de canalización no se puede ejecutar en diferentes ramas de la forma paralela a menos que se coloque en un ámbito sincronizado en cada rama.

• Canalizaciones existentes (ensambles) construidas contra el SDK de BizTalk Server 2006.

Modos de Fallo y Efectos

Cualquier error en la ejecución de la canalización que habría dado lugar a un mensaje suspendido si se llamara a esta canalización desde la infraestructura de mensajería de BizTalk Server en su lugar provocará una excepción. La excepción producida es de tipo Microsoft.XLANGs.Pipeline.XLANGPipelineManagerException. Esta excepción lanzada se puede gestionar en un bloque de captura dentro de la orquestación que la invoca. Si la orquestación no detecta la excepción lanzada, el motor XLANG notifica un error cuyo texto incluye la información de la excepción lanzada.

La excepción da formato a los mensajes de error generados por los componentes de la tubería.

La propiedad Message de la clase XLANGPipelineManagerException contiene detalles del error de ejecución de la canalización. Este detalle tiene el formato siguiente:

• Error al ejecutar la canalización tipo< de canalización>. Detalles de error <mensaje de error con formato>.

  En este mensaje, <el tipo> de canalización es el nombre de la clase de canalización y <el mensaje> de error con formato es una descripción del error específico que se produjo durante la ejecución de la canalización.

  Por ejemplo, si una orquestación llama a una canalización de recepción y se produce un error en la ejecución de esa canalización porque ninguno de los componentes de la canalización reconoce el mensaje, los valores de las propiedades de XLANGPipelineManagerException serían:

Propiedad de XLANGPipelineManagerException	Importancia
Mensaje	Error al ejecutar la canalización de recepción "MyPipelines.ReceivePipeline". Detalles del error: "Ningún componente de fase de desensamblaje puede reconocer los datos.
Componente	Cadena.Vacía

Como otro ejemplo, si una orquestación llama a una canalización de envío y se produce un error en la ejecución de esa canalización porque se produce un error de validación, el texto de la propiedad Message de XLANGPipelineManagerException sería:

Propiedad de XLANGPipelineManagerException	Importancia
Mensaje	Error al ejecutar la canalización de envío "MyPipelines.SendPipeline". Detalles del error: "No se pudo validar el documento: "El <nombre del elemento> es inválido - El <valor del elemento> no es válido según su tipo de datos 'String' - Fallo en la restricción de patrón."
Componente	"Microsoft.BizTalk.Component.XmlValidator"