Compartir a través de

Adaptador transaccional (ejemplo de BizTalk Server)

  • Artículo

El ejemplo de adaptador transaccional demuestra cómo crear y utilizar una transacción explícita de Microsoft DTC (Coordinador de transacciones distribuidas) para una base de datos durante el procesamiento de un mensaje de BizTalk Server.

Descripción del ejemplo

Este ejemplo contiene un adaptador de recepción que ejecuta una instrucción SQL en un intervalo especificado por el usuario para obtener datos de una base de datos de SQL Server mediante una transacción de MSDTC. Los datos se envían posteriormente a la base de datos de cuadro de mensajes de BizTalk en forma de mensaje en el contexto de la misma transacción.

El adaptador de envío correspondiente ejecuta un procedimiento almacenado de SQL especificado por el usuario y para ello utiliza los datos de un mensaje de BizTalk en el contexto de una transacción. Usa datos específicos de ese mensaje para encontrar el mensaje correspondiente y eliminarlo de la base de datos de cuadro de mensajes de la misma transacción.

Cómo se ha diseñado este ejemplo y por qué

La solución de este ejemplo incluye dos proyectos. El primero es el proyecto administrativo (Admin) que se utiliza antes del tiempo de ejecución para permitir que un usuario configure las ubicaciones de recepción y los puertos de envío que usan el adaptador. El segundo es el proyecto de tiempo de ejecución (Runtime) que se ejecuta cuando los adaptadores de recepción y envío están en ejecución.

Ubicación del ejemplo

El ejemplo se encuentra en la siguiente ubicación del SDK:

<Ruta de acceso de> ejemplos\Samples\AdaptersDevelopment\TransactionalAdapter. El proyecto de configuración administrativa se encuentra en la carpeta \Admin, y el de tiempo de ejecución, en la carpeta \Runtime.

En la tabla siguiente se enumeran los archivos del ejemplo y se describe su propósito.

Nombre del archivo del proyecto Admin Descripción del archivo del proyecto Admin
TransactionalAdmin.csproj Archivo del proyecto administrativo del adaptador utilizado para la configuración anterior al tiempo de ejecución.
TransactionalReceiveHandler.xsd XSD de las propiedades del controlador de recepción.
TransactionalReceiveLocation.xsd XSD de las propiedades de la ubicación de recepción.
TransactionalTransmitLocation.xsd XSD de las propiedades de la ubicación de transmisión.
TransactionalTransmitHandler.xsd XSD de las propiedades del controlador de transmisión.
TransactionalAdapterManagement.cs Administración de la configuración del adaptador. Contiene GetConfigSchema, que invoca el marco de trabajo de adaptadores de BizTalk para devolver un esquema de configuración XSD para cada uno de los (cuatro) tipos posibles de configuración compatibles.
Nombre del archivo del proyecto de tiempo de ejecución Descripción del archivo del proyecto de tiempo de ejecución
Transactional.csproj Archivo del proyecto de tiempo de ejecución del adaptador.
TransactionalAsyncBatch.cs Realiza la implementación asíncrona de la parte de envío del adaptador.
TransactionalDeleteBatch.cs Elimina un lote de mensajes y votos para confirmar o anular una transacción.
TransactionalProperties.cs Extrae y establece las propiedades de configuración.
TransactionalReceiver.cs Crea y administra los extremos de recepción.
TransactionalReceiverEndpoint.cs Realiza la escucha o sondeo real de cada una de las ubicaciones de recepción.
TransactionalTransmitter.cs Acepta un lote de mensajes del motor de mensajería que se va a transmitir.

Uso del ejemplo

El propósito de este ejemplo es constituir un marco de trabajo que pueda utilizarse para la creación de adaptadores de recepción y envío personalizados mediante transacciones explícitas.

Crear e inicializar este ejemplo

Importante

Si la instalación de BizTalk es de 64 bits o se modifica la ubicación de la instalación, OutboundAssemblyPath, InboundAssemblyPath y AdapterMgmtAssemblyPath deben cambiarse según corresponda.

Creación de una clave de nombre seguro para el ejemplo del adaptador transaccional

  1. Inicie el símbolo del sistema de Visual Studio.

  2. En el símbolo del sistema, escriba el siguiente comando y, a continuación, presione ENTRAR:

    cd \Program Files\Microsoft BizTalk Server <version>\SDK\Samples\AdaptersDevelopment\TransactionalAdapter\Runtime

  3. En el símbolo del sistema, escriba el siguiente comando y, a continuación, presione ENTRAR:

    sn –k TransactionalAdapter.snk

  4. En el símbolo del sistema, escriba exit y presione Entrar para cerrar la ventana del símbolo del sistema.

Compilación de la solución del adaptador transaccional

  1. Haga clic en Inicio, seleccione Todos los programas, Accesorios y, a continuación, haga clic en Explorador de Windows.

  2. Vaya a \Archivos de programa (x86)\Microsoft BizTalk Server <VERSION>SDK\Samples\AdaptersDevelopment\TransactionalAdapter y haga doble clic en TransactionalAdapter.sln para abrir esta solución en Visual Studio.

  3. Para compilar los dos proyectos del adaptador transaccional (Administración y runtime) en Explorador de soluciones, haga clic con el botón derecho en TransactionalAdapter de solución y, a continuación, haga clic en Recompilar.

Ejecución del ejemplo

Registrar el adaptador transaccional

  1. En el Explorador de Windows, vaya a \Archivos de programa (x86)\Microsoft BizTalk Server <VERSION>SDK\Samples\AdaptersDevelopment\TransactionalAdapter\Administración.

  2. Para agregar los datos del adaptador transaccional al Registro, haga doble clic en TransactionalAdmin.reg.

    Nota

    TransactionalAdmin.reg incluye rutas de acceso codificadas de forma rígida a C:\Archivos de programa\Microsoft BizTalk Server\. Si no instaló BizTalk Server en la ubicación predeterminada o si actualizó la instalación de BizTalk Server desde una versión anterior, debe modificar el archivo TransactionalAdmin.reg con las rutas de acceso adecuadas. Actualice las rutas asociadas a los valores "InboundAssemblyPath", "OutboundAssemblyPath" y "AdapterMgmtAssemblyPath" para que señalen a la ubicación correcta de los archivos especificados.

    Importante

    Si instala BizTalk en una máquina de 64 bits, cambie todas las instancias de la entrada del Registro de HKEY_CLASSES_ROOT\CLSID\ a HKEY_CLASSES_ROOT\Wow6432Node\CLSID\ en el archivo del registro TransactionalAdmin.reg .

  3. En el cuadro de diálogo Editor del Registro , haga clic en Sí para agregar el adaptador de ejemplo al Registro y, a continuación, haga clic en Aceptar.

  4. Para cerrar el Explorador de Windows, haga clic en Archivo y, a continuación, haga clic en Cerrar.

Agregar el adaptador transaccional a BizTalk Server

  1. Haga clic en el menú Inicio, seleccione Todos los programas, Microsoft BizTalk Server 20xx y, a continuación, seleccione administración BizTalk Server.

  2. En la administración de BizTalk Server, expanda el árbol administración de BizTalk Server, expanda el árbol grupo de BizTalk y, a continuación, expanda el árbol Configuración de la plataforma.

  3. Haga clic con el botón derecho en Adaptadores, haga clic en Nuevoy, a continuación, haga clic en Adaptador.

  4. En el cuadro de diálogo Propiedades del adaptador , haga lo siguiente.

    Use Para hacer esto
    Nombre Escriba TransactionalAdapter.
    Adapter (Adaptador) Seleccione Txn en la lista desplegable. Esta entrada aparece como resultado de ejecutar el archivo TransactionalAdmin.reg anteriormente.
    Descripción Tipo Sample Transactional Adapter( Adaptador transaccional de ejemplo).

  5. Haga clic en Aceptar. El adaptador aparece ahora en la lista de adaptadores en la ventana derecha de la consola de administración de BizTalk.

Crear un puerto y una ubicación de recepción que utilicen el adaptador

  1. Expanda el nodo Grupo de BizTalk[nombre del servidor] en administración de BizTalk Server, expanda nodo Aplicaciones, expanda Nodo Aplicación de BizTalk 1.

  2. Haga clic con el botón derecho en Puertos de recepcióny, a continuación, haga clic en Nuevo, seleccione Puerto de recepción unidireccional.

  3. En Nombre, escriba TxnReceivePort1 y, a continuación, haga clic en Aceptar.

  4. Haga clic con el botón derecho en el nodo Ubicaciones de recepción , haga clic en Nuevoy, a continuación, seleccione Ubicación de recepción unidireccional.

  5. En el cuadro de diálogoSeleccionar un puerto de recepción , seleccione TxnReceivePort1 y, a continuación, haga clic en Aceptar.

  6. En el cuadro de diálogo Propiedades de ubicación de recepción , en la pestaña General , escriba TxnReceiveLocation1 como Nombre. Asegúrese de que la etiqueta Puerto de recepción muestra TxnReceivePort1.

  7. En el cuadro de lista desplegableTipo , en el marco Transporte , seleccione TransactionalAdapter.

  8. En el cuadro Canalización de recepción, asegúrese de que PassThruReceive está seleccionado. Deje el resto de las propiedades con los valores de configuración predeterminados.

  9. Haga clic en el botón Configurar situado junto al cuadro desplegable Tipo . Con ello, se muestra un cuadro de diálogo específico para este adaptador. Especifique lo siguiente como vea adecuado y, a continuación, haga clic en Aceptar.

    Propiedad Parámetro
    Cadena de conexión La cadena de conexión de base de datos de SQL utilizada para efectuar la conexión con la base de datos Northwind y la autenticación correspondiente. Posteriormente, se ejecutará un script de SQL que usará esta base de datos.
    Texto de comando Las instrucciones SQL que se ejecutan para la base de datos Northwind para obtener datos que se colocarán en el mensaje de BizTalk.
    Cookie Forma parte del URI, por lo que es preciso especificar un valor único, como el nombre de la ubicación de recepción; por ejemplo: TxnReceiveLocation1.
    Unidad de intervalo de sondeo El número de unidades de medida de tiempo para el sondeo de los datos. Establezca este valor como segundos.
    Intervalo de sondeo La unidad de medida de tiempo para el sondeo de los datos. Establezca este valor como 15 segundos.

  10. Haga clic en Aceptar para cerrar el cuadro de diálogo Configurar y, a continuación, vuelva a aceptar para cerrar el cuadro de diálogo Propiedades de ubicación de recepción para volver a la administración de BizTalk Server.

Crear un puerto y un controlador de envío que utilicen el adaptador

  1. Con el nodo Aplicación de BizTalk 1 todavía expandido, haga clic con el botón derecho en Puertos de envíoy, a continuación, haga clic en Nuevo y seleccione Estático One-Way Puerto de envío.

  2. En el campo Nombre , escriba TxnSendPort1.

  3. En el marco Transporte, en la lista desplegable Tipo, seleccioneTransactionalAdapter..

  4. En el cuadro Enviar canalización , asegúrese de que PassThruTransmit está seleccionado.

  5. Haga clic en el botón Configurar situado junto a la lista desplegable transporte . En el cuadro de diálogo que aparece, especifique lo siguiente como verá adecuado y, a continuación, haga clic en Aceptar.

    Propiedad Parámetro
    Cookie Consta de parte del URI: escriba un valor único aquí, como el nombre de la ubicación de recepción, por ejemplo: TxnSendPort1.
    Cadena de conexión La cadena de conexión de base de datos de SQL utilizada para efectuar la conexión con la base de datos Northwind y la autenticación correspondiente. Lo más probable es que sea el mismo que se usa para configurar la ubicación de recepción TxnReceiveLocation1 .
    Procedimiento almacenado Nombre del procedimiento almacenado que se ejecuta para sondear la base de datos: sp_txnProc. El cuerpo del mensaje de BizTalk se asigna a ese procedimiento almacenado como un parámetro de cadena denominado @Data. Por ejemplo, el usuario configurará posteriormente el procedimiento almacenado con el nombre sp_txnProc. El tiempo de ejecución del adaptador ejecutará el equivalente de esta llamada en la base de datos.

    exec sp_txnProc @Data = "el contenido del mensaje de BizTalk"

  6. En el panel de navegación izquierdo, haga clic en Filtrar.

  7. En el editor de expresiones de filtro, especifique la siguiente expresión con el fin de configurar una suscripción para este puerto de envío de modo que pueda recibir cualquier mensaje que reciba el puerto de recepción TxnReceivePort1.

    Escriba estos valores: BTS. ReceivePortName== TxnReceivePort1

    1. (property)BTS. ReceivePortName

    2. (operator) ==

    3. (value)TxnReceivePort1

  8. Use los valores predeterminados para el resto de las propiedades del adaptador y seleccione Aceptar.

Ejecución del ejemplo

  1. Haga clic en Inicio, seleccione Todos los programas, Microsoft SQL Server 2008 R2 y seleccione SQL Server Management Studio.

  2. En el cuadro de diálogo Conectar al servidor, asegúrese de que Tipo de servidor está establecido en Motor de base de datos y escriba las credenciales para autenticarse en el servidor de bases de datos y, a continuación, seleccione Conectar.

  3. Seleccione el botón de la barra de herramientas Nueva consulta y pegue lo siguiente en la nueva ventana de consulta para insertar una tabla de prueba, datos de prueba y un procedimiento almacenado de prueba en la base de datos Northwind. Seleccione el botón Ejecutar barra de herramientas.

    use [Northwind]  
GO  
if exists (select * from dbo.sysobjects where id = object_id(N'[dbo].[scratch]') and OBJECTPROPERTY(id, N'IsUserTable') = 1)  
drop table [dbo].[scratch]  
GO  
CREATE TABLE [dbo].[scratch] (  
     [id] [int] IDENTITY (1, 1) NOT NULL ,  
     [msg] [nvarchar] (4000) NOT NULL   
) ON [PRIMARY]  
GO  
GRANT SELECT , UPDATE , INSERT ON [dbo].[scratch] TO [public]  
GO  
if exists (select * from dbo.sysobjects where id = object_id(N'[dbo].[sp_txnProc]') and OBJECTPROPERTY(id, N'IsProcedure') = 1)  
drop procedure [dbo].[sp_txnProc]  
GO  
CREATE PROCEDURE [dbo].[sp_txnProc] @Data nvarchar (4000)  
AS   
INSERT scratch ( msg ) values ( @Data )  
GO  
GRANT EXECUTE ON [dbo].[sp_txnProc] TO [public]  
GO

  4. En BizTalk Server Administración, expanda el nodo Puertos de envío, seleccione el puerto de envío TxnSendPort1 y seleccione Iniciar.

  5. En BizTalk Server Administración, expanda el nodo ReceiveLocations, seleccione la ubicación de recepción TxnReceiveLocation1 y, a continuación, seleccione Habilitar.

  6. Una vez habilitada la ubicación de recepción, se efectuará automáticamente un sondeo de los datos de la base de datos en los intervalos designados.

Clases o métodos usados en el ejemplo

  • IBTTransmitterBatch (interfaz) (COM)

  • Interfaz IBTTransportProxy (COM)

Estos métodos se describen en la guía de interfaz de usuario y en la referencia del espacio de nombres de la API de desarrolladores.

Consulte también

Ejemplos de adaptador: desarrollo
Registro de un adaptador