Crear una transformación sincrónica con el componente de script

Artículo
05/23/2023

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

Un componente de transformación se utiliza en el flujo de datos de un paquete de Integration Services para modificar y analizar los datos cuando pasan del origen al destino. Una transformación con salidas sincrónicas procesa cada fila de entrada a medida que pasa por el componente. Una transformación con salidas asincrónicas espera hasta que haya recibido todas las filas de entrada para completar su procesamiento. En este tema se describe una transformación sincrónica. Para obtener información sobre transformaciones asincrónicas, vea Crear una transformación asincrónica con el componente de script. Para obtener más información acerca de la diferencia entre los componentes sincrónicos y asincrónicos, vea Descripción de las transformaciones sincrónicas y asincrónicas.

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 que debe seguir para desarrollar un componente de flujo de datos personalizado en la sección Developing a Custom Data Flow Component (Desarrollo de un componente Flujo de datos personalizado) y, en especial, Developing a Custom Transformation Component with Synchronous Outputs (Desarrollo de un componente de transformación personalizado con salidas sincrónicas).

Introducción a un componente de transformación sincrónica

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 que seleccione un tipo de componente como Origen, Transformación o Destino. En este cuadro de diálogo, seleccione Transformación.

Configurar un componente de transformación sincrónica en modo de diseño de metadatos

Después de seleccionar la opción para crear un componente de transformación, 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).

Para establecer el lenguaje de script para el componente de script, puede establecer la propiedad ScriptLanguage en la página Script del Editor de transformación Script.

Nota:

Para establecer el lenguaje de scripting predeterminado para el componente 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 (Página General).

Un componente de transformación de flujo de datos tiene una entrada y admite una o varias salidas. La configuración de la entrada y 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.

Configurar las columnas de entrada

Un componente de transformación tiene una entrada.

En la página Columnas de entrada del Editor de transformación Script, la lista de columnas muestra las columnas disponibles de la salida del componente de nivel superior en el flujo de datos. Seleccione las columnas que desee transformar o las columnas a través de las que desee pasar. Marque todas las columnas que desee transformar en contexto como de columnas de lectura/escritura.

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

Configurar entradas, salidas y columnas de salidas

Un componente de transformación admite una o más salidas.

En la página Entradas y salidas del Editor de transformación Script puede ver que se ha creado una salida única, pero la salida no tiene ninguna columna. En esta página del editor, quizá necesite o desee configurar los elementos siguientes.

Cree 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 transformación sincrónica. Todas las filas de entrada se dirigen a todas las salidas disponibles a menos que indique que desea redirigir cada fila a una salida u otra. Para indicar que desea redirigir las filas, debe especificar un valor entero distinto de cero para la propiedad ExclusionGroup en las salidas. El valor entero concreto escrito en ExclusionGroup para identificar las salidas no es significativo, pero debe utilizar el mismo entero de forma coherente para el grupo de salidas especificado.

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.
Asigne un nombre más descriptivo a la entrada y las salidas. El componente de script utiliza estos nombres para generar las propiedades de descriptor de acceso con tipo que se usarán para hacer referencia a la entrada y las salidas en el script.
Deje las columnas tal como están para las transformaciones sincrónicas. Normalmente una transformación sincrónica no agrega columnas al flujo de datos. Se modifican los datos in situ en el búfer y se pasa el contenido del búfer al componente siguiente del flujo de datos. Si éste es el caso, no tiene que agregar y configurar explícitamente las columnas de resultados en las salidas de la transformación. Las salidas aparecen en el editor sin las columnas definidas explícitamente.
Agregue las nuevas columnas a las salidas de error simuladas para los errores de fila. Normalmente, varias salidas del mismo ExclusionGroup tienen el mismo conjunto de columnas de resultados. Sin embargo, si crea una salida de error simulada, quizá desee agregar más columnas que contengan 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). Observe que en el componente de script 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 quiere utilizar variables existentes en el script, puede agregarlas en los campos de propiedades ReadOnlyVariables y ReadWriteVariables de la página Script del Editor de transformación Script.

Cuando agregue varias variables a los campos de propiedades, separe sus nombres con comas. Para seleccionar 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 las 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).

Scripting de un componente de transformación sincrónica en el modo de diseño de código

Después de haber configurado los metadatos para el componente, puede escribir un script personalizado. En la página Script del Editor de transformación Script, haga clic en Editar script para abrir el IDE de Microsoft Visual Studio Tools for Applications (VSTA), donde puede agregar el script personalizado. El lenguaje de scripting que utilice dependerá de si ha seleccionado Microsoft Visual Basic o Microsoft Visual C# como lenguaje de script para la propiedad ScriptLanguage en la página Script.

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 transformación, la clase ScriptMain modificable aparece en el editor de código con un código auxiliar para el método ProcessInputRow. En la clase ScriptMain escribirá el código personalizado; ProcessInputRow es el método más importante de un componente de transformación.

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 se hereda de la clase UserComponent en el elemento de proyecto ComponentWrapper.

En tiempo de ejecución, el motor de flujo de datos invoca el método ProcessInput de la clase UserComponent, lo que invalida el método ProcessInput de la clase primaria ScriptComponent. A su vez, el método ProcessInput recorre las filas del búfer de entrada y llama al método ProcessInputRow una vez por cada fila.

Escribir código personalizado

Un componente de transformación con salidas sincrónicas es el más sencillo de escribir de todos los componentes de flujo de datos. Por ejemplo, el ejemplo de salida única mostrado más adelante en este tema consta del código personalizado siguiente:

Row.City = UCase(Row.City)

Row.City = (Row.City).ToUpper();

Para terminar de crear un componente de transformación sincrónica personalizado, debe utilizar el método ProcessInputRow invalidado para transformar los datos de cada fila del búfer de entrada. El motor de flujo de datos pasa este búfer, cuando está lleno, al componente siguiente del flujo de datos.

En función de sus requisitos, puede que también quiera escribir script en los métodos PreExecute y PostExecute, disponibles en la clase ScriptMain, para realizar un procesamiento preliminar o final.

Trabajar con varias salidas

Dirigir las filas de entrada a una de dos o más posibles salidas no requiere mucho más código personalizado que el caso de ejemplo de salida única descrito anteriormente. Por ejemplo, el ejemplo de dos salidas mostrado más adelante en este tema consta del código personalizado siguiente:

Row.City = UCase(Row.City)  
If Row.City = "REDMOND" Then  
    Row.DirectRowToMyRedmondAddresses()  
Else  
    Row.DirectRowToMyOtherAddresses()  
End If

Row.City = (Row.City).ToUpper();  
  
if (Row.City=="REDMOND")  
{  
    Row.DirectRowToMyRedmondAddresses();  
}  
else  
{  
    Row.DirectRowToMyOtherAddresses();  
}

En este ejemplo, el componente de script genera los métodos DirectRowTo<OutputBufferX> automáticamente, basándose en los nombres de las salidas configuradas. Puede utilizar un código similar para dirigir las filas de errores a una salida de error simulada.

Ejemplos

En los ejemplos que figuran aquí se muestra el código personalizado requerido en la clase ScriptMain para crear un componente de transformación sincrónica.

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 transformación sincrónica de salida única

En este ejemplo se muestra un componente de transformación sincrónica con una salida única. Esta transformación pasa por la columna AddressID y convierte la columna City a mayúsculas.

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

Agregue un nuevo componente de script a la superficie del diseñador de flujo de datos y configúrelo como una transformación.
Conecte la salida de un origen o de otra transformación al nuevo componente de transformación en el diseñador de SSIS. Esta salida debe proporcionar datos de la tabla Person.Address de la base de datos de ejemplo AdventureWorks que contiene las columnas AddressID y City.
Abra el Editor de transformación Script. En la página Columnas de entrada, seleccione las columnas AddressID y City. Marque la columna City como de lectura y escritura.
En la página Entradas y salidas, cambie el nombre de la entrada y la salida por nombres más descriptivos, como MyAddressInput y MyAddressOutput. Observe que el valor de SynchronousInputID de la salida se corresponde con el valor de ID de la entrada. Por consiguiente no tiene que agregar y configurar las columnas de resultados.
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 que espere las columnas AddressID y City, 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. A continuación, conecte la salida de transformación al componente de destino. 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.

Public Class ScriptMain  
    Inherits UserComponent  
  
    Public Overrides Sub MyAddressInput_ProcessInputRow(ByVal Row As MyAddressInputBuffer)  
  
        Row.City = UCase(Row.City)  
  
    End Sub  
  
End Class

public class ScriptMain:  
    UserComponent  
  
{  
    public override void MyAddressInput_ProcessInputRow(MyAddressInputBuffer Row)  
    {  
  
        Row.City = (Row.City).ToUpper();  
  
    }  
  
}

Ejemplo de transformación sincrónica de dos salidas

En este ejemplo se muestra un componente de transformación sincrónica con dos salidas. Esta transformación pasa por la columna AddressID y convierte la columna City a mayúsculas. Si el nombre de la ciudad es Redmond, dirige la fila a una salida; dirige todas las demás filas a otra salida.