Построение, развертывание и отладка пользовательских объектов

Статья
05/23/2023

Применимо к: SQL Server Integration Runtime служб SSIS в Фабрика данных Azure

После написания кода пользовательского объекта для служб Службы Integration Services необходимо построить сборку, развернуть ее и интегрировать в конструктор служб Integration Services, чтобы сделать ее доступной для использования в пакетах, а затем протестировать и выполнить ее отладку.

Шаги построения, развертывания и отладки пользовательского объекта для служб Integration Services

Пользовательская функциональность для объекта уже написана. Теперь необходимо протестировать ее и сделать доступной для пользователей. Эти шаги похожи для всех типов пользовательских объектов, которые могут быть созданы для служб Службы Integration Services.

Ниже описывается порядок построения, развертывания и тестирования.

Подпишите сборку для формирования со строгим именем.
Постройте сборку.
Разверните сборку, переместив или скопировав ее в соответствующую папку служб Службы Integration Services.
Установите сборку в глобальный кэш сборок (GAC).

Объект автоматически добавляется в область элементов.
Устраните неполадки в работе развернутой сборки, если необходимо.
Протестируйте и выполните отладку кода.

Теперь можно использовать конструктор SSIS в SQL Server Data Tools (SSDT), чтобы создавать, обслуживать и выполнять пакеты, ориентированные на различные версии SQL Server. Дополнительные сведения о влиянии этого улучшения на пользовательские расширения см. в разделе Получение пользовательских расширений служб SSIS, поддерживаемых несколькими версиями SSDT 2015 для SQL Server 2016

Подписывание сборки

Если сборка предназначена для общего доступа, ее необходимо установить в глобальный кэш сборок. После добавления сборки в глобальный кэш сборок, ее можно использовать в приложениях, например, в среде SQL Server Data Tools (SSDT). Глобальный кэш сборок предъявляет к добавляемой сборке особое требование: она должна быть подписана строгим именем, что гарантирует глобальную уникальность сборки. Сборка со строгим именем имеет полное имя, включающее имя, культуру, открытый ключ и номер версии сборки. Среда выполнения использует эти сведения, чтобы найти сборку и отличить ее от других сборок с тем же именем.

Чтобы подписать сборку строгим именем, необходимо иметь или создать пару открытого и закрытого ключей. Такая пара открытого и закрытого криптографических ключей используется во время построения для создания сборки со строгим именем.

Дополнительные сведения о строгих именах и шагах подписывания сборки см. в следующих разделах документации к пакету SDK платформы .NET Framework:

Сборки со строгими именами
Создание пары ключей
Подписывание сборки строгим именем

Можно легко подписать сборку строгим именем в среде Visual Studio во время построения. В диалоговом окне Свойства проекта перейдите на вкладку Подписывание. Выберите параметр Подписать сборку и укажите путь к файлу ключа (SNK).

Построение сборки

После подписывания проекта необходимо построить или перестроить проект или решение с использованием команд, доступных в меню Построение среды SQL Server Data Tools. Решение может содержать отдельный проект для пользовательского интерфейса, который также должен быть подписан строгим именем и может строиться одновременно со сборкой.

Наиболее удобным способом выполнения следующих двух шагов — развертывания сборки и установки ее в глобальный кэш сборок — является создание скрипта для этих шагов, запускаемого после построения в Visual Studio. События построения доступны на странице Компиляция свойств проекта для проекта Visual Basic и на странице События построения для проекта C#. В программах командной строки, например gacutil.exe, необходимо указывать полный путь. Пути, содержащие пробелы, и макросы, например, $(TargetPath), которые разворачиваются в пути, содержащие пробелы, необходимо заключать в кавычки.

Ниже приведен образец командной строки события после построения для пользовательского регистратора.

"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 "

Развертывание сборки

Конструктор служб Integration Services определяет местоположение пользовательских объектов, доступных для использования в пакетах, путем перечисления файлов, обнаруженных в наборах папок, которые были созданы при установке служб SQL Server Службы Integration Services. При использовании настроек установки SQL Server по умолчанию этот набор папок расположен по адресу C:\Program Files\Microsoft SQL Server\130\DTS. Однако если для пользовательского объекта была создана программа установки, следует проверить значение в разделе реестра HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\130\SSIS\Setup\DtsPath, чтобы убедиться в правильности указанного местоположения этой папки.

Примечание

Дополнительные сведения о развертывании пользовательских компонентов с поддержкой нескольких версий в SQL Server Data Tools см. в разделе Получение пользовательских расширений служб SSIS, поддерживаемых несколькими версиями SSDT 2015 для SQL Server 2016.

Можно поместить сборку в папку двумя способами.

Переместить или скопировать скомпилированную сборку в соответствующую папку после ее построения. (Для удобства можно включить команду копирования в событие после построения.)
Построить сборку непосредственно в нужной папке.

Следующие папки развертывания, расположенные в каталоге C:\Program Files\Microsoft SQL Server\130\DTS, используются для различных типов пользовательских объектов:

Пользовательский объект	Папка развертывания
Задача	Задания
Диспетчер соединений	Соединения
Регистратор	LogProviders
Компонент потока данных	PipelineComponents

Примечание

Сборки копируются в эти папки для поддержки перечисления доступных задач, диспетчеров соединений и т. д. Поэтому нет необходимости развертывать сборки, содержащие только пользовательский интерфейс для пользовательских объектов, в этих папках.

Установка сборки в глобальный кэш сборок

Чтобы установить сборку задачи в глобальный кэш сборок (GAC), используйте программу командной строки gacutil.exe или перетащите сборки в каталог %system%\assembly. Для удобства можно включить вызов программы gacutil.exe в событие после построения.

Следующая команда устанавливает компонент с именем MyTask.dll в глобальный кэш сборок (GAC) с помощью программы gacutil.exe.

gacutil /iF MyTask.dll

После установки новой версии пользовательского объекта необходимо закрыть и заново открыть конструктор служб Integration Services. Если устаревшие версии пользовательского объекта были ранее установлены в глобальный кэш сборок, необходимо удалить их перед установкой новой версии. Чтобы удалить сборку, запустите программу gacutil.exe и укажите имя сборки с параметром /u.

Дополнительные сведения о глобальном кэше сборок см. в разделе «Программа глобального кэша сборок (Gactutil.exe)» в документации по средствам платформы .NET Framework.

Устранение неполадок в развертывании

Если пользовательский объект отображается на панели элементов или в списке доступных объектов, но его не удается добавить в пакет, попробуйте выполнить следующие действия:

Выполните поиск в глобальном кэше сборок на предмет наличия в нем нескольких версий компонента. При наличии нескольких версий компонента в глобальном кэше сборок конструктор не может загрузить компонент. Удалите все экземпляры сборки из глобального кэша сборок и добавьте сборку заново.
Убедитесь в том, что только один экземпляр сборки существует в папке развертывания.
Обновите панель элементов.
Подключитесь в среде Visual Studio к файлу devenv.exe и установите точку останова, чтобы выполнить в пошаговом режиме код инициализации и убедиться в отсутствии исключений.

Тестирование и отладка кода

Самым простым подходом к отладке методов времени выполнения пользовательского объекта является запуск dtexec.exe из среды Visual Studio после построения пользовательского объекта и выполнение пакета, использующего этот компонент.

Если необходимо выполнить отладку методов времени разработки компонента, например метода Validate, откройте пакет, в котором используется компонент, во втором экземпляре среды Visual Studio и подключитесь к процессу devenv.exe.

Если также требуется выполнить отладку методов времени выполнения компонента, когда пакет открыт и выполняется в конструкторе Integration Services, необходимо принудительно приостановить выполнение пакета с тем, чтобы можно было также присоединиться к процессу DtsDebugHost.exe.

Отладка методов времени выполнения объекта путем подключения к dtexec.exe

Подпишите и постройте проект в конфигурации отладки, выполните развертывание и установку в глобальный кэш сборок, как описано в этом разделе.
На вкладке Отладка диалогового окна Свойства проекта выберите Запуск внешней программы в качестве значения для параметра Начальное действие и найдите файл dtexec.exe, который по умолчанию установлен в каталог C:\Program Files\Microsoft SQL Server\130\DTS\Binn.
В текстовом поле Параметры командной строки в разделе Параметры запуска введите аргументы командной строки, необходимые для выполнения пакета, который использует пользовательский компонент. Часто аргумент командной строки содержит параметр /F[ILE], за которым следуют путь и имя DTSX-файла. Дополнительные сведения см. в статье dtexec Utility.
В исходном коде, где это необходимо, задайте точки останова в методах времени выполнения компонента.
Выполните проект.

Отладка методов времени разработки пользовательского объекта путем присоединения к SQL Server Data Tools

Подпишите и постройте проект в конфигурации отладки, выполните развертывание и установку в глобальный кэш сборок, как описано в этом разделе.
В исходном коде, где это необходимо, задайте точки останова в методах времени разработки пользовательского объекта.
Откройте второй экземпляр среды Visual Studio и загрузите проект служб Службы Integration Services, содержащий пакет, в котором используется пользовательский объект.
В первом экземпляре среды Visual Studio подключитесь ко второму экземпляру devenv.exe, в котором загружен пакет, выбрав команду Присоединиться к процессу в меню Отладка первого экземпляра.
Выполните пакет из второго экземпляра среды Visual Studio.

Отладка методов времени выполнения пользовательского объекта путем присоединения к SQL Server Data Tools

После выполнения шагов, описанных в предыдущей процедуре, принудительно приостановите выполнение пакета, чтобы его можно было присоединить к DtsDebugHost.exe. Принудительно приостановить выполнение можно путем добавления точки останова в событие OnPreExecute либо добавления задачи "Скрипт" в проект и ввода скрипта, отображающего модальное окно сообщения.
Запустите пакет. Во время паузы переключитесь в экземпляр среды Visual Studio, где открыт проект кода, и выберите команду Присоединить для обработки в меню Отладка. Подсоединяться следует к экземпляру DtsDebugHost.exe, содержащемуся в списке Управляемые, x86 в столбце Тип, а не к экземпляру из списка x86.
Вернитесь к приостановленному пакету и продолжите выполнение после точки останова либо нажмите кнопку ОК, чтобы закрыть окно сообщения, выданного задачей "Скрипт", и продолжить выполнение и отладку пакета.

См. также:

Разработка пользовательских объектов для служб Integration Services
Сохранение пользовательских объектов
Инструменты устранения неполадок при разработке пакета