Crear un origen con el componente de script

Artículo
05/23/2023

Se aplica a: SQL Server SSIS Integration Runtime en Azure Data Factory

Los componentes de origen del flujo de datos de un paquete de Integration Services se usan para cargar datos de un origen de datos y pasarlos a transformaciones y destinos de nivel inferior. Normalmente la conexión al origen de datos se realiza a través de un administrador de conexiones existente.

Para obtener una introducción al componente de script, vea Extending the Data Flow with the Script Component (Extensión del Flujo de datos con el componente de script).

El componente de script y el código de infraestructura que genera simplifican considerablemente el proceso de desarrollo de un componente de flujo de datos personalizado. Sin embargo, para entender cómo funciona el componente de script, puede resultar útil leer los pasos necesarios para el desarrollo de un componente de flujo de datos personalizado. Vea la sección Developing a Custom Data Flow Component (Desarrollo de un componente de flujo de datos personalizado), especialmente el tema Developing a Custom Source Component (Desarrollo de un componente de origen personalizado).

Introducción al componente de origen

Al agregar un componente de script al panel Flujo de datos del Diseñador de SSIS, se abre el cuadro de diálogo Seleccionar el tipo de componente de script y se solicita la selección de un script de origen, destino o transformación. En este cuadro de diálogo, seleccione Origen.

Configurar un componente de origen en modo de diseño de metadatos

Después de seleccionar la opción para crear un componente de origen, configure el componente mediante el Editor de transformación Script. Para obtener más información, consulte Configuring the Script Component in the Script Component Editor (Configurar el componente de script en el editor de componentes de script).

Un componente de origen de flujo de datos no tiene ninguna entrada y admite una o más salidas. La configuración de las salidas del componente es uno de los pasos que debe completar en el modo de diseño de metadatos, mediante el Editor de transformación Script, antes de escribir un script personalizado.

También puede especificar el lenguaje de script mediante el establecimiento de la propiedad ScriptLanguage en la página Script del Editor de transformación Script.

Nota

Para establecer el lenguaje de script predeterminado para los componentes Script y las tareas de script, utilice la opción Lenguaje de scripting en la página General del cuadro de diálogo Opciones. Para obtener más información, vea General Page.

Agregar administradores de conexión

Normalmente, un componente de origen utiliza un administrador de conexiones existente para conectarse al origen de datos del que carga los datos en el flujo de datos. En la página Administradores de conexión del Editor de transformación Script, haga clic en Agregar para agregar el administrador de conexiones adecuado.

Sin embargo, un administrador de conexiones solo es una unidad práctica que encapsula y almacena la información necesaria para conectarse a un origen de datos de un tipo determinado. Debe escribir su propio código personalizado para cargar o guardar los datos y posiblemente también para abrir y cerrar la conexión al origen de datos.

Para obtener información general acerca de cómo se utilizan los administradores de conexión con el componente de script, vea Connecting to Data Sources in the Script Component (Conexión a orígenes de datos en el componente de script).

Para obtener más información acerca de la página Administradores de conexión del Editor de transformación Script, vea Editor de transformación Script (página Administradores de conexión).

Configurar salidas y columnas de salida

Un componente de origen no tiene ninguna entrada y admite una o más salidas. En la página Entradas y salidas del Editor de transformación Script, se ha creado una única salida de forma predeterminada, pero no se ha creado ninguna columna de salida. En esta página del editor, quizá necesite o desee configurar los elementos siguientes.

Debe agregar y configurar manualmente las columnas de salida para cada salida. Seleccione la carpeta Columnas de salida para cada salida y, a continuación, utilice los botones Agregar columna y Quitar columna para administrar las columnas de salida de cada salida del componente de origen. Después, hará referencia a las columnas de salida en el script por los nombres que asigna aquí, mediante las propiedades de descriptor de acceso con tipo creadas en el código generado automáticamente.
Puede crear una o varias salidas adicionales, como una salida de error simulada para las filas que contienen valores inesperados. Utilice los botones Agregar salida y Quitar salida para administrar las salidas del componente de origen. Todas las filas de entrada se dirigen a todas las salidas disponibles a menos que también especifique un valor distinto de cero idéntico para la propiedad ExclusionGroup de las salidas si desea dirigir cada fila a solo una de las salidas que comparten el mismo valor de ExclusionGroup. El valor entero determinado seleccionado para identificar el elemento ExclusionGroup no es significativo.

Nota

También puede utilizar un valor de la propiedad ExclusionGroup distinto de cero con una salida única si no desea generar la salida de todas las filas. Sin embargo, en este caso, debe llamar explícitamente al método DirectRowTo<outputbuffer> para cada fila que desee enviar a la salida.
Puede asignar un nombre descriptivo a las salidas. Después, hará referencia a las salidas en el script por sus nombres, mediante las propiedades de descriptor de acceso con tipo creadas en el código generado automáticamente.
Normalmente, varias salidas del mismo grupo ExclusionGroup tienen las mismas columnas de resultados. Sin embargo, si crea una salida de error simulada, quizá desee agregar más columnas que almacenen información de error. Para obtener información acerca de cómo el motor de flujo de datos procesa las filas de errores, vea Using Error Outputs in a Data Flow Component (Uso de las salidas de error en un componente de flujo de datos). En el componente de script, sin embargo, debe escribir su propio código para llenar las columnas adicionales con la información de error adecuada. Para obtener más información, vea Simulating an Error Output for the Script Component (Simular una salida de error para el componente de script).

Para obtener más información acerca de la página Entradas y salidas del Editor de transformación Script, vea Editor de transformación Script (página Entradas y salidas).

Agregar variables

Si hay variables existentes cuyos valores quiere usar en el script, puede agregarlas en los campos de propiedades ReadOnlyVariables y ReadWriteVariables de la página Script del Editor de transformación Script.

Al introducir diversas variables en los campos de propiedades, separe los nombres de éstas por comas. Para escribir varias variables, también puede hacer clic en el botón de puntos suspensivos ( … ) junto a los campos de propiedades ReadOnlyVariables y ReadWriteVariables y, después, seleccionar variables en el cuadro de diálogo Seleccionar variables.

Para obtener información general sobre la forma de usar variables con el componente de script, vea Using Variables in the Script Component (Uso de variables con el componente de script).

Para obtener más información acerca de la página Script del Editor de transformación Script, vea Editor de transformación Script (página Script).

Generar script en un componente de origen en modo de diseño de código

Después de configurar los metadatos para el componente, abra el IDE de Microsoft Visual Studio Tools for Applications (VSTA) para programar el script personalizado. Para abrir VSTA, haga clic en Editar script en la página Script del Editor de transformación Script. Puede escribir el script mediante Microsoft Visual Basic o Microsoft Visual C#, dependiendo del lenguaje de script seleccionado para la propiedad ScriptLanguage.

Para obtener información importante aplicable a todos los tipos de componentes creados mediante el componente de script, vea Coding and Debugging the Script Component (Programación y depuración del componente de script).

Descripción del código generado automáticamente

Al abrir el IDE de VSTA después de crear y configurar un componente de origen, la clase ScriptMain modificable aparece en el editor de código. El código personalizado se escribe en la clase ScriptMain.

La clase ScriptMain incluye un código auxiliar para el método CreateNewOutputRows. CreateNewOutputRows es el método más importante en un componente de origen.

Si abre la ventana Explorador de proyectos de VSTA, puede ver que el componente de script también ha generado elementos de proyecto BufferWrapper y ComponentWrapper de solo lectura. La clase ScriptMain hereda de la clase UserComponent en el elemento de proyecto ComponentWrapper.

En tiempo de ejecución, el motor de flujo de datos invoca al método PrimeOutput de la clase UserComponent, lo que invalida el método PrimeOutput de la clase primaria ScriptComponent. El método PrimeOutput a su vez llama a los métodos siguientes:

El método CreateNewOutputRows, que se invalida en ScriptMain para agregar filas del origen de datos a los búferes de salida, que al principio están vacíos.
El método FinishOutputs, que está vacío de forma predeterminada. Invalide este método en ScriptMain para realizar cualquier procesamiento que se requiera para completar la salida.
El método privado MarkOutputsAsFinished, que llama al método SetEndOfRowset de la clase primaria ScriptBuffer para indicar al motor de flujo de datos que la salida ha finalizado. No tiene que llamar explícitamente a SetEndOfRowset en su propio código.

Escribir código personalizado

Para terminar de crear un componente de origen personalizado, puede escribir el script en los siguientes métodos disponibles en la clase ScriptMain.

Invalide el método AcquireConnections para conectarse al origen de datos externo. Extraiga el objeto de conexión, o la información de conexión necesaria, del administrador de conexiones.
Invalide el método PreExecute para cargar datos, si puede cargar al mismo tiempo todos los datos de origen. Por ejemplo, puede ejecutar SqlCommand en una conexión ADO.NET a una base de datos SQL Server y cargar al mismo tiempo todos los datos de origen en SqlDataReader. Si debe cargar los datos de origen por filas individuales (por ejemplo, al leer un archivo de texto), puede cargar los datos mientras recorre las filas en bucle en CreateNewOutputRows.
Utilice el método CreateNewOutputRows invalidado para agregar nuevas filas a los búferes de salida vacíos y rellenar los valores de cada columna en las nuevas filas de salida. Utilice el método AddRow de cada búfer de salida para agregar una nueva fila vacía y, a continuación, establezca los valores de cada columna. Normalmente copia los valores de las columnas cargadas del origen externo.
Invalide el método PostExecute para finalizar el procesamiento de los datos. Por ejemplo, puede cerrar la clase SqlDataReader que utilizó para cargar datos.
Invalide el método ReleaseConnections para desconectarse del origen de datos externo, si se requiere.

Ejemplos

En los ejemplos siguientes se muestra el código personalizado que se necesita en la clase ScriptMain para crear un componente de origen.

Nota

En estos ejemplos se usa la tabla Person.Address de la base de datos de ejemplo AdventureWorks y se pasan la primera y la cuarta columna, las columnas intAddressID y nvarchar(30)City, a través del flujo de datos. Estos mismos datos se usan en los ejemplos de origen, transformación y destino de esta sección. Se documentan requisitos previos y suposiciones adicionales para cada ejemplo.

Ejemplo de origen de ADO.NET

En este ejemplo se muestra un componente de origen que utiliza un administrador de conexiones de ADO.NET existente para cargar datos de una tabla de SQL Server en el flujo de datos.

Si desea ejecutar este código de ejemplo, debe configurar el paquete y el componente de la siguiente forma:

Cree un administrador de conexiones de ADO.NET que utilice el proveedor SqlClient para conectarse a la base de datos AdventureWorks.
Agregue un nuevo componente de script a la superficie del diseñador de flujo de datos y configúrelo como origen.
Abra el Editor de transformación Script. En la página Entradas y salidas, cambie el nombre de la salida predeterminada por un nombre más descriptivo como MyAddressOutput, y agregue y configure las dos columnas de salida, AddressID y City.

Nota

Asegúrese de cambiar el tipo de datos de la columna de salida City a DT_WSTR.
En la página Administradores de conexión, agregue o cree el administrador de conexiones de ADO.NET y asígnele un nombre como MyADONETConnection.
En la página Script, haga clic en Editar script y escriba el script que se indica a continuación. A continuación, cierre el entorno de desarrollo de script y el Editor de transformación Script.
Cree y configure un componente de destino, como un destino de SQL Server o el componente de destino de ejemplo que se muestra en Crear un destino con el componente de script, que espere las columnas AddressID y City. A continuación, conecte el componente de origen al destino. (Puede conectar directamente un origen a un destino sin ninguna transformación). Puede crear una tabla de destino ejecutando el siguiente comando Transact-SQL en la base de datos AdventureWorks:
```
CREATE TABLE [Person].[Address2]([AddressID] [int] NOT NULL,  
    [City] [nvarchar](30) NOT NULL)  
```

Ejecute el ejemplo.

Imports System.Data.SqlClient  
...  
Public Class ScriptMain  
    Inherits UserComponent  

    Dim connMgr As IDTSConnectionManager100  
    Dim sqlConn As SqlConnection  
    Dim sqlReader As SqlDataReader  

    Public Overrides Sub AcquireConnections(ByVal Transaction As Object)  

        connMgr = Me.Connections.MyADONETConnection  
        sqlConn = CType(connMgr.AcquireConnection(Nothing), SqlConnection)  

    End Sub  

    Public Overrides Sub PreExecute()  

        Dim cmd As New SqlCommand("SELECT AddressID, City, StateProvinceID FROM Person.Address", sqlConn)  
        sqlReader = cmd.ExecuteReader  

    End Sub  

    Public Overrides Sub CreateNewOutputRows()  

        Do While sqlReader.Read  
            With MyAddressOutputBuffer  
                .AddRow()  
                .AddressID = sqlReader.GetInt32(0)  
                .City = sqlReader.GetString(1)  
            End With  
        Loop  

    End Sub  

    Public Overrides Sub PostExecute()  

        sqlReader.Close()  

    End Sub  

    Public Overrides Sub ReleaseConnections()  

        connMgr.ReleaseConnection(sqlConn)  

    End Sub  

End Class

using System.Data.SqlClient;  
public class ScriptMain:  
    UserComponent  

{  
    IDTSConnectionManager100 connMgr;  
    SqlConnection sqlConn;  
    SqlDataReader sqlReader;  

    public override void AcquireConnections(object Transaction)  
    {  
        connMgr = this.Connections.MyADONETConnection;  
        sqlConn = (SqlConnection)connMgr.AcquireConnection(null);  

    }  

    public override void PreExecute()  
    {  

        SqlCommand cmd = new SqlCommand("SELECT AddressID, City, StateProvinceID FROM Person.Address", sqlConn);  
        sqlReader = cmd.ExecuteReader();  

    }  

    public override void CreateNewOutputRows()  
    {  

        while (sqlReader.Read())  
        {  
            {  
                MyAddressOutputBuffer.AddRow();  
                MyAddressOutputBuffer.AddressID = sqlReader.GetInt32(0);  
                MyAddressOutputBuffer.City = sqlReader.GetString(1);  
            }  
        }  

    }  

    public override void PostExecute()  
    {  

        sqlReader.Close();  

    }  

    public override void ReleaseConnections()  
    {  

        connMgr.ReleaseConnection(sqlConn);  

    }  

}

Ejemplo de origen de archivo plano

En este ejemplo se muestra un componente de origen que utiliza un administrador de conexiones de archivos planos existente para cargar datos de un archivo plano en el flujo de datos. Los datos de origen del archivo plano se crean mediante su exportación desde SQL Server.