Generar, implementar y depurar objetos personalizados

Artículo
05/23/2023

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

Después de haber escrito el código para un objeto personalizado de Integration Services, debe generar, implementar e integrar el ensamblado en el Diseñador SSIS para que esté disponible para su uso en paquetes, y probarlo y depurarlo.

Pasos para generar, implementar y depurar un objeto personalizado para Integration Services

Ya ha escrito la funcionalidad personalizada para el objeto. Ahora tiene que probarlo y hacer que esté disponible para los usuarios. Los pasos son muy similares para todos los tipos de objetos personalizados que puede crear para Integration Services.

Estos son los pasos para generarlo, implementarlo y probarlo.

Firme el ensamblado que se va a generar con un nombre seguro.
Genere el ensamblado.
Implemente el ensamblado; para ello, muévalo o cópielo en la carpeta de Integration Services adecuada.
Instale el ensamblado en la caché global de ensamblados (GAC).

El objeto se agregará automáticamente al cuadro de herramientas.
Solucione los problemas de la implementación, si es necesario.
Pruebe y depure el código.

Ahora puede usar el Diseñador SSIS en SQL Server Data Tools (SSDT) para crear, mantener y ejecutar paquetes que se destinen a distintas versiones de SQL Server. Para obtener más información sobre el impacto de esta mejora en sus extensiones personalizadas, vea Getting your SSIS custom extensions to be supported by the multi-version support of SSDT 2015 for SQL Server 2016 (Conseguir que la compatibilidad con varias versiones de SSDT 2015 para SQL Server 2016 admita extensiones personalizadas de SSIS).

Firmar el ensamblado

Cuando se tiene pensado compartir un ensamblado, se debe instalar en la memoria caché de ensamblados global. Una vez agregado el ensamblado a la memoria caché de ensamblados global, aplicaciones como SQL Server Data Tools (SSDT) pueden utilizarlo. Un requisito de la memoria caché de ensamblados global es que el ensamblado se debe firmar con un nombre seguro, que garantiza que el ensamblado es único de forma global. Un ensamblado con nombre seguro especifica un nombre completo que incluye el nombre del ensamblado, la referencia cultural, la clave pública y el número de versión. El motor en tiempo de ejecución utiliza esta información para localizar el ensamblado y distinguirlo entre otros ensamblados con el mismo nombre.

Para firmar un ensamblado con un nombre seguro, es necesario crear o tener antes un par de claves publica y privada. Este par de claves criptográficas pública y privada se usa al realizar la compilación para crear un ensamblado con nombre seguro.

Para obtener más información sobre los nombres seguros y los pasos que debe seguir para firmar un ensamblado, consulte los temas siguientes en la documentación del SDK de .NET Framework:

Ensamblados con nombre seguro
Crear un par de claves
Firmar un ensamblado con un nombre seguro

Puede firmar con facilidad el ensamblado con un nombre seguro en Visual Studio durante la generación. En el cuadro de diálogo Propiedades del proyecto, seleccione la pestaña Firma. Seleccione la opción para Firmar el ensamblado y, a continuación, proporcione la ruta de acceso del archivo de claves (.snk).

Generar el ensamblado

Después de firmar el proyecto, debe generar o volver a generar el proyecto o la solución utilizando los comandos disponibles en el menú Generar de SQL Server Data Tools. La solución puede contener un proyecto independiente para una interfaz de usuario personalizada, que también se debe firmar con un nombre seguro y se puede generar al mismo tiempo.

El método más sencillo para realizar los dos pasos siguientes (implementar el ensamblado e instalarlo en la memoria caché de ensamblados global) es crear un script con estos pasos como un evento posterior a la compilación en Visual Studio. Los eventos de compilación están disponibles en la página Compilar de Propiedades del proyecto para un proyecto de Visual Basic y en la página Eventos de compilación para un proyecto de C#. Es necesaria la ruta de acceso completa para las utilidades de símbolo del sistema como gacutil.exe. Son necesarias comillas alrededor de las rutas de acceso que contienen espacios en blanco y alrededor de macros como $(TargetPath) que se expanden a rutas de acceso que contienen espacios en blanco.

A continuación figura un ejemplo de una línea de comandos del evento posterior a la generación para un proveedor de registro personalizado:

"C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\bin\NETFX 4.0 Tools\gacutil.exe" -u $(TargetName)  
"C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\bin\NETFX 4.0 Tools\gacutil.exe" -i $(TargetFileName)  
copy $(TargetFileName) "C:\Program Files\Microsoft SQL Server\130\DTS\LogProviders "

Implementar el ensamblado

El Diseñador SSIS busca los objetos personalizados disponibles para su uso en paquetes enumerando los archivos buscados en una serie de carpetas que se crean cuando se instala SQL Server Integration Services. Cuando se utilizan los valores de instalación predeterminados de SQL Server, este conjunto de carpetas se encuentra en C:\Archivos de programa\Microsoft SQL Server\130\DTS. Sin embargo, si crea un programa de instalación para el objeto personalizado, debe comprobar el valor de la clave del Registro HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\130\SSIS\Setup\DtsPath para comprobar la ubicación de esta carpeta.

Nota

Para obtener información sobre cómo implementar componentes personalizados para que funcionen bien con la compatibilidad con varias versiones de SQL Server Data Tools, consulte Getting your SSIS custom extensions to be supported by the multi-version support of SSDT 2015 for SQL Server 2016 (Conseguir que la compatibilidad con varias versiones de SSDT 2015 para SQL Server 2016 admita extensiones personalizadas de SSIS).

Puede colocar el ensamblado en la carpeta de dos maneras:

Copiar o mover el ensamblado compilado a la carpeta adecuada después de generarlo. (Para su comodidad, puede incluir el comando de copia en un evento posterior a la generación).
Generar el ensamblado directamente en la carpeta adecuada.

Las carpetas de implementación de C:\Archivos de programa\Microsoft SQL Server\130\DTS se usan para los distintos tipos de objetos personalizados:

Objeto personalizado	Carpeta de implementación
Tarea	Tareas
Administrador de conexiones	Conexiones
Proveedor de registro	LogProviders
Componente de flujo de datos	PipelineComponents

Nota

Los ensamblados se copian en estas carpetas para admitir la enumeración de tareas disponibles, administradores de conexión, etc. Por consiguiente no tiene que implementar los ensamblados que contienen solo la interfaz de usuario personalizada para los objetos personalizados en estas carpetas.

Instalar el ensamblado en la memoria caché de ensamblados global

Para instalar el ensamblado de tarea en la caché global de ensamblados (GAC), use la herramienta de línea de comandos gacutil.exe o arrastre los ensamblados al directorio %system%\assembly. Para su comodidad, puede incluir también la llamada a gacutil.exe en un evento posterior a la compilación.

El comando siguiente instala un componente denominado MyTask.dll en la GAC mediante gacutil.exe.

gacutil /iF MyTask.dll

Se debe cerrar y volver a abrir el Diseñador SSIS después de instalar una nueva versión del objeto personalizado. Si ha instalado versiones anteriores del objeto personalizado en la caché global de ensamblados, debe quitarlos antes de instalar la nueva versión. Para desinstalar un ensamblado, ejecute gacutil.exe y especifique el nombre del ensamblado con la opción /u.

Para obtener más información sobre la caché global de ensamblados, vea Herramienta Caché global de ensamblados (Gactutil.exe) en .NET Framework Tools.

Solucionar problemas relacionados con la implementación

Si el objeto personalizado aparece en el cuadro de herramientas o en la lista de objetos disponibles, pero no puede agregarlo a un paquete, pruebe lo siguiente:

Busque en la memoria caché de ensamblados global varias versiones del componente. Si hay varias versiones del componente en la memoria caché de ensamblados global, el diseñador quizá no pueda cargar el componente. Elimine todas las instancias del ensamblado de la memoria caché de ensamblados global y vuelva a agregar el ensamblado.
Asegúrese de que solo existe una instancia única del ensamblado en la carpeta de implementación.
Actualice el cuadro de herramientas.
Adjunte Visual Studio a devenv.exe y establezca un punto de interrupción para reproducir paso a paso el código de inicialización con el fin de asegurarse de que no se produce ninguna excepción.

Probar y depurar el código

El enfoque más sencillo para depurar los métodos en tiempo de ejecución de un objeto personalizado consiste en iniciar dtexec.exe desde Visual Studio después de compilar el objeto personalizado y ejecutar un paquete que use el componente.

Si desea depurar los métodos en tiempo de diseño del componente, como el método Validate, abra un paquete que use el componente en una segunda instancia de Visual Studio y adjúntelo a su proceso devenv.exe.

Si también quiere depurar los métodos en tiempo de ejecución del componente cuando un paquete está abierto y ejecutándose en el Diseñador SSIS, debe forzar una pausa en la ejecución del paquete para poder adjuntarlo también al proceso DtsDebugHost.exe.

Para depurar los métodos en tiempo de ejecución de un objeto adjuntándolos a dtexec.exe

Firme e integre el proyecto en la configuración de depuración, impleméntelo e instálelo en la memoria caché de ensamblados global tal y como se describe en este tema.
En la pestaña Depurar de Propiedades del proyecto, seleccione Programa externo de inicio como la Acción de inicio y busque dtexec.exe, que se instala de forma predeterminada en C:\Archivos de programa\Microsoft SQL Server\130\DTS\Binn.
En el cuadro de texto Opciones de la línea de comandos, en Opciones de inicio, escriba los argumentos de la línea de comandos necesarios para ejecutar un paquete que usa el componente. A menudo el argumento de la línea de comandos estará compuesto del modificador /F[ILE] seguido de la ruta de acceso y nombre de archivo del archivo .dtsx. Para obtener más información, consulte utilidad dtexec.
Establezca los puntos de interrupción en el código fuente donde sea adecuado en los métodos en tiempo de ejecución del componente.
Ejecute el proyecto.

Para depurar los métodos en tiempo de diseño de un objeto personalizado adjuntándolos a las herramientas de datos de SQL Server

Firme e integre el proyecto en la configuración de depuración, impleméntelo e instálelo en la memoria caché de ensamblados global tal y como se describe en este tema.
Establezca puntos de interrupción en el código fuente donde se adecuado en los métodos en tiempo de diseño del objeto personalizado.
Abra una segunda instancia de Visual Studio y cargue un proyecto de Integration Services que contiene un paquete que utiliza el objeto personalizado.
En la primera instancia de Visual Studio, adjúntelo a la segunda instancia de devenv.exe en la que se carga el paquete seleccionando Adjuntar al proceso en el menú Depurar de la primera instancia.
Ejecute el paquete desde la segunda instancia de Visual Studio.

Para depurar los métodos en tiempo de ejecución de un objeto personalizado adjuntándolos a las herramientas de datos de SQL Server

Una vez completados los pasos enumerados en el procedimiento anterior, fuerce una pausa en la ejecución del paquete para que se pueda adjuntar a DtsDebugHost.exe. Para forzar esta pausa, agregue un punto de interrupción al evento OnPreExecute o agregue una tarea Script al proyecto y escriba el script que muestra un cuadro de mensaje modal.
Ejecute el paquete. Cuando se produzca la pausa, cambie a la instancia de Visual Studio en la que está abierto el código del proyecto y seleccione Adjuntar al proceso en el menú Depurar. Asegúrese de adjuntarlo a la instancia de DtsDebugHost.exe que se muestra como Administrado, x86 en la columna Tipo, no a la instancia mostrada solo como x86.
Vuelva al paquete en pausa y continúe más allá del punto de interrupción o haga clic en Aceptar para descartar el cuadro de mensaje generado por la tarea Script, y continuar con la ejecución y depuración del paquete.

Consulte también

Desarrollar objetos personalizados para Integration Services
Conservar objetos personalizados
Herramientas para solucionar problemas con el desarrollo de paquetes