Tutorial: Utilizar sobres XML (básicos)

En este ejemplo se demuestra un desensamblado de sobre XML básico implementando parte de un sistema de seguimiento de errores ficticio. El ejemplo cumple los requisitos siguientes:

1. Los mensajes de error se registran en varias ubicaciones físicas de la compañía y se envían a una ubicación central para su procesamiento en varios sistemas de servidor.

2. Los mensajes de error escriben en formato XML.

3. Un mensaje de error se puede enviar por sí solo, sin sobre, o como un lote contenido en un sobre.

Requisitos previos

Para este ejemplo, debe estar familiarizado con la creación de proyectos de BizTalk, la firma de un ensamblado y el uso de la consola de administración de BizTalk Server para ver las aplicaciones y los puertos. También debe estar cómodo con las ideas presentadas en Tutorial: Implementación de una aplicación básica de BizTalk.

Qué se hace en este ejemplo

En el ejemplo se procesan los mensajes de entrada que contienen un solo mensaje de error o un lote de éstos. Para ello, se define un esquema de sobres y se usa la canalización XmlDisassembler.

Ejemplo

Para crear el ejemplo, siga los pasos que se especifican en las secciones que se presentan a continuación.

Crear un nuevo proyecto de BizTalk

Antes de generar una solución, es preciso crear un proyecto de BizTalk, asegurarse de que se le ha asignado un nombre seguro y un nombre de aplicación. La asignación de un nombre de aplicación evita que BizTalk Server implemente la solución en la aplicación de BizTalk predeterminada.

Para crear y configurar un nuevo proyecto de BizTalk

1. Use Visual Studio para crear un nuevo proyecto de BizTalk. Llame al proyecto BasicXMLEnvelope.

2. Genere un archivo de clave y asígnelo al proyecto. Para obtener más información sobre esta tarea, vea How to Configure a Strong Name Assembly Key File.

3. En las propiedades de configuración de implementación del proyecto, asigne un nombre de aplicación y establezca Reiniciar instancias de host en True. Al definir esta marca, se ordena al host que borre todas las instancias del ensamblado almacenadas en caché.

Crear el esquema de error

En este paso, se creará el esquema de error. Define el mensaje clave para el sistema.

Para crear el esquema de error

1. Agregue un nuevo esquema denominado "Error" al proyecto.

2. Cambie el espacio de nombres de destino del esquema a http://BasicXMLEnvelope.

3. Cambie la propiedad schema Element FormDefault (Elemento FormDefault ) de la categoría Advanced (Avanzadas) a Qualified (Calificado). Con ello, se indica que el espacio de nombres de destino debe calificar los elementos declarados localmente en un documento de instancia.

4. Cambie el nombre del nodo raíz "Error" y cree cinco elementos secundarios con los tipos que se indican:

   • ID, xs:int

   • Type, xs:int

   • Priority, xs:string

   • Description, xs:string

   • ErrorDateTime, xs:string

     El esquema tendrá el siguiente aspecto:

     

5. Cree un mensaje de ejemplo para este esquema Este mensaje se usa para comprobar que los mensajes sencillos, no contenidos en un sobre, se procesan correctamente. Un mensaje de ejemplo es:

   <Error xmlns="http://BasicXMLEnvelope">  
     <ID>1</ID>  
     <Type>5</Type>  
     <Priority>Low</Priority>  
     <Description>Sprocket widget prints reports slowly.</Description>  
     <ErrorDateTime>1999-05-31T13:20:00.000-05:00</ErrorDateTime>  
   </Error>  
   

   Guarde este mensaje en un archivo en el directorio del proyecto.

Crear el esquema de sobres

El sobre contiene uno o más mensajes de error. En este ejemplo básico, el sobre no tiene propiedades ni elementos propios.

Para crear el esquema de sobres

1. Agregue un nuevo esquema denominado "Envelope" al proyecto BasicXMLEnvelope.

2. Cambie el espacio de nombres de destino a http://BasicXMLEnvelope.

3. Cambie el nombre del nodo raíz de "Root" a "Envelope".

4. Ahora, marque el esquema como esquema de sobres. Haga clic en el <nodo Esquema> . En el panel Propiedades, establezca la propiedad de referencia de esquema EnvelopeOKen .

5. Establezca la propiedad Body XPath . Para ello, haga clic en el nodo Sobre . En el ventana Propiedades, haga clic en el botón de puntos suspensivos (...) de la propiedad Body XPath, seleccione Envelope y, a continuación, haga clic en Aceptar.

6. Agregue un elemento secundario Cualquier elemento al nodo Envelope. El mensaje de error estará contenido en este elemento. El esquema tendrá el siguiente aspecto:

   

7. Cree un mensaje de ejemplo que contenga un sobre y uno o varios ejemplos de mensajes. Un mensaje de ejemplo es:

   <Envelope xmlns="http://BasicXMLEnvelope">  
     <Error>  
       <ID>102</ID>  
       <Type>0</Type>  
       <Priority>High</Priority>  
       <Description>Sprocket query fails.</Description>  
       <ErrorDateTime>1999-05-31T13:20:00.000-05:00</ErrorDateTime>  
     </Error>  
     <Error>  
       <ID>16502</ID>  
       <Type>2</Type>  
       <Priority>Low</Priority>  
       <Description>Time threshold exceeded.</Description>  
       <ErrorDateTime>1999-05-31T13:20:00.000-05:00</ErrorDateTime>  
     </Error>  
   </Envelope>  
   

   Guarde este mensaje en un archivo en el directorio del proyecto.

Implementar y configurar los puertos de envío y recepción

Con los esquemas creados, será necesario compilar el proyecto e implementarlo. Una vez implementado, se podrá utilizar la consola de administración de BizTalk Server para configurar los puertos de envío y recepción.

Para implementar BasicXMLEnvelope

1. En Visual Studio, elija Implementar BasicXMLEnvelope en el menú Compilar. Se generará e implementará en BizTalk Server como la aplicación "BasicXMLEnvelope".

2. En la consola de administración de BizTalk Server, expanda el grupo Aplicaciones para comprobar que BasicXMLEnvelope está presente como una aplicación personalizada.

Para configurar el puerto de recepción

1. Use el Explorador de Windows para crear un directorio denominado "Receive" en el directorio del proyecto BasicXMLEnvelope .

2. En la consola de administración de BizTalk Server, expanda la aplicación BasicXMLEnvelope, haga clic con el botón derecho en Puertos de recepción, seleccione Nuevoy, a continuación, haga clic en Puerto de recepción unidireccional.

3. En el cuadro de diálogo Propiedades del puerto de recepción , establezca el nombre del puerto en "Receive".

4. Haga clic con el botón derecho en Ubicaciones de recepción y, a continuación, haga clic en Nuevo para agregar un puerto de recepción. Defina "ReceiveError" como nombre del nuevo puerto. Establezca la canalización de recepción en XMLReceive. En Tipo de transporte, seleccione ARCHIVO y, a continuación, haga clic en Configurar.

5. Seleccione el directorio de recepción creado anteriormente y haga clic en Aceptar. Con ello, el puerto de recepción debería estar configurado. Haga clic en Aceptar para cerrar.

Para configurar el puerto de envío

1. Use el Explorador de Windows para crear un directorio denominado "Send" en el directorio del proyecto BasicXMLEnvelope .

2. En la consola de administración de BizTalk Server, expanda la aplicación BasicXMLEnvelope, haga clic con el botón derecho en Puertos de envío, seleccione Nuevoy, a continuación, haga clic en Estática unidireccional.

3. En el cuadro de diálogo Propiedades del puerto de envío, establezca el nombre del puerto en "Enviar".

4. En Tipo de transporte, seleccione ARCHIVO y, a continuación, haga clic en Configurar. Establezca la carpeta de destino en el directorio de envío que creó anteriormente y haga clic en Aceptar.

5. Haga clic en Filtros y agregue un único filtro:

   • BTS. MessageType == http://BasicXMLEnvelope#Error

6. Haga clic en Aceptar para completar la configuración del puerto de envío. Con ello, el puerto de envío debería estar configurado.

Ejecutar el ejemplo

Ha llegado el momento de ejecutar el ejemplo. Tras utilizar la consola de administración de BizTalk Server para iniciar la aplicación BasicXMLEnvelope, se copiarán los archivos de prueba en la ubicación de recepción y se observará lo que se produce en la ubicación de envío.

Para ejecutar el ejemplo BasicXMLEnvelope

1. En la consola de administración de BizTalk Server, haga clic con el botón derecho en la aplicación BasicXMLEnvelope y, a continuación, haga clic en Iniciar. Con ello, se darán de alta los puertos de recepción y envío y se iniciarán.

2. Coloque cada uno de archivos de ejemplo en el directorio de recepción. Si usa los ejemplos facilitados anteriormente, encontrará tres mensajes de error individuales en la ubicación de envío cuando se complete el procesamiento.

Extensión del ejemplo

Puede ampliar el ejemplo para adaptarlo a otros requisitos. En esta sección se tratan dos escenarios comunes.

• Si se envía un lote de errores dentro de un sobre, los errores en mensajes individuales del desensamblado no deberían prohibir el procesamiento ulterior de los demás mensajes sin errores.

• Los errores deberán enviarse a distintas ubicaciones según la prioridad del error. Los mensajes de alta prioridad se envían antes, mientras que los demás niveles de prioridad se administran por los canales normales.

  En las siguientes secciones se amplía el ejemplo de modo que incluya estos requisitos.

Procesamiento de intercambio recuperable

BizTalk Server admite el procesamiento de intercambio recuperable. Esta característica permite garantizar que los lotes de mensajes con errores se traten individualmente en el desensamblado, y no como un lote.

Para configurar el ejemplo para el procesamiento de intercambio recuperable

1. En la consola de administración de BizTalk Server, expanda la aplicación BasicXMLEnvelope, haga clic en Puertos de recepción y, a continuación, haga doble clic en el puerto de recepción. Éste es el puerto creado anteriormente.

2. En el cuadro de diálogo Propiedades del puerto de recepción, haga clic en Ubicaciones de recepción. Haga clic en Propiedades para abrir el cuadro de diálogo Propiedades de ubicación de recepción receiveError . Haga clic en el botón de puntos suspensivos (...) de la canalización de recepción.

3. En el cuadro de diálogo Configurar canalización - XMLReceive, establezca la propiedad TrueProcesamiento de intercambio recuperable en y, a continuación, haga clic en Aceptar.

4. Haga clic en Aceptar para cerrar el cuadro de diálogo Propiedades de ubicación de recepción y, a continuación, haga clic en Aceptar para cerrar el cuadro de diálogo Propiedades del puerto de recepción.

Para crear un archivo de ejemplo y ejecutar el ejemplo

1. Para crear un archivo de ejemplo, realice una copia del archivo de ejemplo de sobre creado en el ejemplo, agregue un espacio de nombres inexistente a una de las instancias de error y guarde el archivo:

   <Envelope xmlns="http://BasicXMLEnvelope">  
     <Error>  
       <ID>102</ID>  
       <Type>0</Type>  
       <Priority>High</Priority>  
       <Description>Sprocket query fails to return any sprockets even though some exist</Description>  
       <ErrorDateTime>1999-05-31T13:20:00.000-05:00</ErrorDateTime>  
     </Error>  
     <Error xmlns="http://ThisIsAnError">  
       <ID>16502</ID>  
       <Type>2</Type>  
       <Priority>Low</Priority>  
       <Description>Time threshold exceeded.</Description>  
       <ErrorDateTime>1999-05-31T13:20:00.000-05:00</ErrorDateTime>  
     </Error>  
   </Envelope>  
   

2. En la consola de administración de BizTalk Server, haga clic en Aplicaciones y compruebe que la aplicación BasicXMLEnvelope se está ejecutando.

3. Coloque el mensaje en la ubicación de recepción. Después del procesamiento, deberá encontrar el primer mensaje en la ubicación de envío y el segundo, de baja prioridad, en la cola de suspensión.

Enrutamiento por contenidos (CBR)

También puede utilizar el enrutamiento por contenidos para enrutar mensajes según su contenido. En este escenario, en enrutamiento se basa en la prioridad. Los mensajes con prioridad alta van a una ubicación de envío y los mensajes con prioridad media o baja van a otra.

Para ampliar el ejemplo, debe completar las tareas siguientes:

1. Promueva el campo Prioridad en el esquema error del proyecto BasicXMLEnvelope. El enrutamiento por contenidos se basa en propiedades promocionadas para enrutar los mensajes. Para obtener más información, vea Promoción de propiedades.

2. Cree y configure dos puertos adicionales. Los puertos usan un filtro para garantizar que reciben los mensajes apropiados.

Para promocionar el campo Priority del esquema de error

1. Con el proyecto BasicXMLEnvelope abierto en Visual Studio, abra el esquema Error y expanda el nodo Error .

2. Haga clic con el botón derecho en el elemento Priority , seleccione Promover y, a continuación, haga clic en Promoción rápida.

3. Haga clic en Aceptar para confirmar la adición de un nuevo esquema de propiedades para las propiedades promocionadas.

4. En Visual Studio, en Explorador de soluciones, abra el nuevo esquema de propiedades PropertySchema.xsd. Quite "Field1" del esquema.

5. Vuelva a compilar e implementar la solución. En el menú Generar, elija Implementar BasicXMLEnvelope.

6. El proyecto se configuró para restablecer la instancia de host cuando se vuelve a implementar la solución. Si lo ha modificado, deberá detener e iniciar el host.

Para configurar el puerto de envío de prioridad media y baja

1. Use el Explorador de Windows para crear un directorio denominado "SendLowMediumPriority" en el directorio del proyecto BasicXMLEnvelope .

2. En la consola de administración de BizTalk Server, expanda la aplicación BasicXMLEnvelope, haga clic con el botón derecho en Puertos de envío, seleccione Nuevo y, a continuación, haga clic en Estática unidireccional.

3. En el cuadro de diálogo Propiedades del puerto de envío, establezca el nombre del puerto en "SendLowMediumPriority".

4. En Tipo de transporte, seleccione ARCHIVO y, a continuación, haga clic en Configurar. Defina el directorio creado anteriormente como la carpeta de destino. Haga clic en Aceptar para cerrar.

5. Haga clic en Filtros y agregue tres expresiones de filtro:

   • BTS. MessageType == http://BasicXMLEnvelope#Error y

   • BasicXMLEnvelope.PropertySchema.Priority == Low Or

   • BasicXMLEnvelope.PropertySchema.Priority == Medium

6. Haga clic en Aceptar para completar la configuración del puerto de envío de prioridad baja y media.

Para configurar el puerto de envío de prioridad alta

1. Use el Explorador de Windows para crear un directorio denominado "SendHighPriority" en el directorio del proyecto BasicXMLEnvelope .

2. En la consola de administración de BizTalk Server, expanda la aplicación BasicXMLEnvelope, haga clic con el botón derecho en Puertos de envío, seleccione Nuevo y, a continuación, haga clic en Estática unidireccional.

3. En el cuadro de diálogo Propiedades del puerto de envío , establezca el nombre del puerto en "SendHighPriority".

4. En Tipo de transporte, seleccione ARCHIVO y, a continuación, haga clic en Configurar. Defina el directorio creado anteriormente como la carpeta de destino. Haga clic en Aceptar para cerrar.

5. Haga clic en Filtros y agregue dos expresiones de filtro:

   • BTS. MessageType == http://BasicXMLEnvelope#Error y

   • BasicXMLEnvelope.PropertySchema.Priority == High

6. Haga clic en Aceptar para completar la configuración del puerto de envío de alta prioridad.

Para probar la solución de enrutamiento

1. En la consola de administración de BizTalk Server, expanda el grupo Aplicaciones, haga clic con el botón derecho en la aplicación BasicXMLEnvelope y, a continuación, haga clic en Iniciar. Cuando se le pida que confirme, haga clic en Iniciar. Se darán de alta los nuevos puertos de envío.

2. Coloque el mensaje de prueba en la ubicación de recepción. Observe cómo se enrutan los mensajes de error a las distintas ubicaciones de envío:

   • Los mensajes de error con prioridad baja, media o alta que no tengan errores al procesarse se enrutan a la ubicación de envío original (configurada en el ejemplo principal) y a las ubicaciones de envío por prioridad. Para los mensajes con prioridad media o baja, aparece una copia en la ubicación de envío original y en la ubicación de envío de prioridad media o baja.

   • Si el procesamiento de intercambio recuperable está habilitado, los mensajes de error con errores no se enrutan, y los mensajes sin errores se enrutan correctamente según lo esperado. Los mensajes con errores no se enrutan porque este tipo de mensaje no coincide con el tipo usado en los filtros configurados.

Consulte también

Procesamiento de intercambio recuperable
Promoción de propiedades
CBRSample (ejemplo de BizTalk Server)