生成、部署和调试自定义对象Building, Deploying, and Debugging Custom Objects

适用于: SQL Server 是 Azure 数据工厂中的 SSIS Integration Runtime Azure Synapse Analytics (SQL DW)APPLIES TO: yesSQL Server yesSSIS Integration Runtime in Azure Data Factory yesAzure Synapse Analytics (SQL DW)

在为 Integration ServicesIntegration Services 的自定义对象编写代码后,必须生成和部署程序集,并将该程序集集成到 SSISSSIS 设计器中,使其可在包中使用,然后对其进行测试和调试。After you have written the code for a custom object for Integration ServicesIntegration Services, you must build the assembly, deploy it, and integrate it into SSISSSIS Designer to make it available for use in packages, and test and debug it.

生成、部署和调试 Integration Services 自定义对象的步骤Steps in Building, Deploying, and Debugging a Custom Object for Integration Services

您已编写了对象的自定义功能代码。You have already written the custom functionality for your object. 现在必须对所编写的代码进行测试,使其可供用户使用。Now you have to test it and to make it available to users. 对于可为 Integration ServicesIntegration Services 创建的所有类型的自定义对象,步骤都非常相似。The steps are very similar for all the types of custom objects that you can create for Integration ServicesIntegration Services.

下面是生成、部署和测试的步骤。Here are the steps to build, deploy, and test it.

  1. 使用强名称为要生成的程序集签名Sign the assembly to be generated with a strong name.

  2. 生成程序集。Build the assembly.

  3. 通过将程序集移动到或复制到适当的 Integration ServicesIntegration Services 文件夹来部署该程序集。Deploy the assembly by moving or copying it to the appropriate Integration ServicesIntegration Services folder.

  4. 在全局程序集缓存 (GAC) 中安装该程序集。Install the assembly in the global assembly cache (GAC).

    此对象自动添加到工具箱中。The object is automatically added to the Toolbox.

  5. 如有必要,对部署进行故障排除Troubleshoot the deployment, if necessary.

  6. 测试并调试代码。Test and debug your code.

现在可以在 SQL Server Data Tools (SSDT) 中使用 SSIS 设计器来创建、维护和运行面向不同版本的 SQL ServerSQL Server 的包。You can now use SSIS Designer in SQL Server Data Tools (SSDT) to create, maintain, and run packages that target different versions of SQL ServerSQL Server. 有关此改进对自定义扩展的影响的详细信息,请参阅使 SSIS 自定义扩展插件获得用于 SQL Server 2016 的 SSDT 2015 多版本的支持For more info about the impact of this improvement on your custom extensions, see Getting your SSIS custom extensions to be supported by the multi-version support of SSDT 2015 for SQL Server 2016

为程序集签名Signing the Assembly

若要共享程序集,必须将其安装在全局程序集缓存中。When an assembly is meant to be shared, it must be installed in the global assembly cache. 程序集被添加到全局程序集缓存之后,可以由 SQL Server Data Tools (SSDT)SQL Server Data Tools (SSDT) 这样的应用程序使用。After the assembly has been added to the global assembly cache, the assembly can be used by applications such as SQL Server Data Tools (SSDT)SQL Server Data Tools (SSDT). 全局程序集缓存要求必须使用强名称为程序集进行签名,这样可保证程序集是全局唯一的。A requirement of the global assembly cache is that the assembly must be signed with a strong name, which guarantees that an assembly is globally unique. 强名称程序集有一个完全限定的名称,由程序集的名称、区域性、公钥及版本号组成。A strong-named assembly has a fully qualified name that includes the name, culture, public key, and version number of the assembly. 运行库使用这些信息来定位程序集并将其与其他同名的程序集区分开。The runtime uses this information to locate the assembly and to differentiate it from other assemblies with the same name.

若要使用强名称为程序集签名,必须首先具有或创建公钥/私钥对。To sign an assembly with a strong name, you must first have or create a public/private key pair. 这一对加密公钥和加密私钥用于在生成时创建强名称程序集。This public and private cryptographic key pair is used at build time to create a strong-named assembly.

有关强名称的详细信息和为程序集签名所必须遵循的步骤,请参阅 .NET Framework.NET Framework SDK 文档中的下列主题:For more information about strong names and on the steps that you must followto sign an assembly, see the following topics in the .NET Framework.NET Framework SDK documentation:

  • 强名称程序集Strong-Named Assemblies

  • 创建密钥对Creating a Key Pair

  • 使用强名称为程序集签名Signing an Assembly with a Strong Name

在生成时,可以轻松在 Visual StudioVisual Studio 中使用强名称为程序集签名。You can easily sign your assembly with a strong name in Visual StudioVisual Studio at build time. 在“项目属性” 对话框中,选择“签名” 选项卡。选择“为程序集签名” 的选项,然后提供密钥文件 (.snk) 的路径。In the Project Properties dialog box, select the Signing tab. Select the option to Sign the assembly and then provide the path of the key (.snk) file.

生成程序集Building the Assembly

为项目签名后,必须使用 SQL Server Data ToolsSQL Server Data Tools 的“生成” 菜单上可用的命令来生成或重新生成项目或解决方案。After signing the project, you must build or rebuild the project or the solution by using the commands available on the Build menu of SQL Server Data ToolsSQL Server Data Tools. 您的解决方案可能包含单独的自定义用户界面项目,该项目也必须使用强名称签名,并且可以同时生成。Your solution may contain a separate project for a custom user interface, which must also be signed with a strong name, and can be built at the same time.

执行下两个步骤(部署程序集并将其安装在全局程序集缓存中)的最简便方法是将这些步骤编写为 Visual StudioVisual Studio 中的生成后事件。The most convenient method for performing the next two steps-deploying the assembly and installing it in the global assembly cache-is to script these steps as a post-build event in Visual StudioVisual Studio. Visual BasicVisual Basic 项目的项目属性的“编译” 页和 C# 项目的“生成事件” 页都提供可用的生成事件。Build events are available from the Compile page of Project Properties for a Visual BasicVisual Basic project, and from the Build Events page for a C# project. 命令提示实用工具(如 gacutil.exe )需要完整路径。The full path is required for command prompt utilities such as gacutil.exe. 包含空格的路径和展开为包含空格的路径的宏(如 $(TargetPath))的前后都需要引号。Quotation marks are required both around paths that contain spaces and around macros such as $(TargetPath) that expand to paths that contain spaces.

下面是自定义日志提供程序的生成后事件命令行的示例:Here is an example of a post-build event command line for a custom log provider:

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

部署程序集Deploying the Assembly

SSISSSIS 设计器对安装 SQL ServerSQL Server Integration ServicesIntegration Services 时创建的一系列文件夹中的文件进行枚举,从而查找可在包中使用的自定义对象。The SSISSSIS Designer locates the custom objects available for use in packages by enumerating the files found in a series of folders that are created when SQL ServerSQL Server Integration ServicesIntegration Services is installed. 使用默认的 SQL ServerSQL Server 安装设置时,这一组文件夹位于 C:\Program Files\Microsoft SQL Server\130\DTS 下。When the default SQL ServerSQL Server installation settings are used, this set of folders is located under C:\Program Files\Microsoft SQL Server\130\DTS. 但是,如果为自定义对象创建安装程序,应检查 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\130\SSIS\Setup\DtsPath 注册表项的值,以验证此文件夹的位置。However if you create a setup program for your custom object, you should check the value of the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\130\SSIS\Setup\DtsPath registry key to verify the location of this folder.


有关如何部署自定义组件以实现与 SQL Server Data Tools 中多版本支持之间的良好协作的详细信息,请参阅使 SSIS 自定义扩展插件获得 SQL Server 2016 的 SSDT 2015 多版本支持的支持For info about how to deploy custom components to work well with the multi-version support in SQL Server Data Tools, see Getting your SSIS custom extensions to be supported by the multi-version support of SSDT 2015 for SQL Server 2016.

可以通过下面两种方式将程序集放入文件夹中:You can put the assembly in the folder in two ways:

  • 在生成已编译的程序集后,将其移动或复制到相应的文件夹中。Move or copy the compiled assembly to the appropriate folder after building it. (为方便起见,可以在生成后事件中包含复制命令。)(For convenience, you can include the copy command in a Post-build Event.)

  • 直接在相应的文件夹中生成程序集。Build the assembly directly in the appropriate folder.

C:\Program Files\Microsoft SQL Server\130\DTS 下的下列部署文件夹用于不同类型的自定义对象:The following deployment folders under C:\Program Files\Microsoft SQL Server\130\DTS are used for the various types of custom objects:

自定义对象Custom object 部署文件夹Deployment folder
任务Task 任务Tasks
“ODBC 源编辑器”Connection manager 连接Connections
日志提供程序Log provider LogProvidersLogProviders
数据流组件Data flow component PipelineComponentsPipelineComponents


将程序集复制到这些文件夹中即可支持可用任务、连接管理器等的枚举。Assemblies are copied to these folders to support the enumeration of available tasks, connection managers, and so on. 因此,您不一定要将只包含用于自定义对象的自定义用户界面的程序集部署到这些文件夹中。Therefore you do not have to deploy assemblies that contain only the custom user interface for custom objects to these folders.

在全局程序集缓存中安装程序集Installing the Assembly in the Global Assembly Cache

若要将任务程序集安装到全局程序集缓存 (GAC) 中,请使用命令行工具 gacutil.exe ,或将程序集拖至 %system%\assembly 目录中。To install the task assembly into the global assembly cache (GAC), use the command line tool gacutil.exe, or drag the assemblies to the %system%\assembly directory. 为方便起见,还可以在生成事件后中调用 gacutil.exe 。For convenience, you can also include the call to gacutil.exe in a Post-build Event.

下面的命令使用 gacutil.exe 将名为 MyTask.dll 的组件安装到 GAC 中。The following command installs a component named MyTask.dll into the GAC by using gacutil.exe.

gacutil /iF MyTask.dll

在安装新版本的自定义对象后,必须先关闭再重新打开 SSISSSIS 设计器。You must close and reopen SSISSSIS Designer after you install a new version of your custom object. 如果已在全局程序集缓存中安装了早期版本的自定义对象,必须先删除这些对象再安装新版本。If you have installed earlier versions of your custom object in the global assembly cache, you must remove them before installing the new version. 若要卸载程序集,请运行 gacutil.exe 并在 /u 选项中指定程序集名称。To uninstall an assembly, run gacutil.exe and specify the assembly name with the /u option.

有关全局程序集缓存的详细信息,请参阅“.NET Framework.NET Framework 工具”中的“全局程序集缓存工具 (Gactutil.exe)”。For more information about the global assembly cache, see Global Assembly Cache Tool (Gactutil.exe) in the .NET Framework.NET Framework Tools.

对部署进行故障排除Troubleshooting the Deployment

如果自定义对象显示在“工具箱” 或可用对象列表中,但无法将其添加到包中,可以尝试以下操作:If your custom object appears in the Toolbox or the list of available objects, but you are not able to add it to a package, try the following:

  1. 在全局程序集缓存中查找该组件是否有多个版本。Look in the global assembly cache for multiple versions of your component. 如果全局程序集缓存中存在该组件的多个版本,则设计器可能无法加载该组件。If there are multiple versions of the component in the global assembly cache, the designer may not be able to load your component. 请删除全局程序集缓存中该程序集的所有实例,然后重新添加该程序集。Delete all instances of the assembly from the global assembly cache, and re-add the assembly.

  2. 请确保部署文件夹中只存在一个程序集实例。Make sure that only a single instance of the assembly exists in the deployment folder.

  3. 刷新工具箱。Refresh the Toolbox.

  4. Visual StudioVisual Studio 附加到 devenv.exe ,然后设置一个断点以单步执行初始化代码,确保不会发生异常。Attach Visual StudioVisual Studio to devenv.exe and set a breakpoint to step through your initialization code to ensure that no exceptions occur.

测试并调试代码Testing and Debugging Your Code

若要调试自定义对象的运行时方法,最简单的方法是在生成自定义对象后从 Visual StudioVisual Studio 启动 dtexec.exe ,然后运行使用该组件的包。The simplest approach to debugging the run-time methods of a custom object is to start dtexec.exe from Visual StudioVisual Studio after building your custom object and run a package that uses the component.

若要调试组件的设计时方法(如 Validate 方法),请在第二个 Visual StudioVisual Studio, 实例中打开使用该组件的包,并附加到该实例的 devenv.exe 进程。If you want to debug the component's design-time methods, such as the Validate method, open a package that uses the component in a second instance of Visual StudioVisual Studio, and attach to its devenv.exe process.

如果还希望在包已打开并在 SSISSSIS 设计器中运行时调试组件的运行时方法,必须在包的执行过程中强制暂停,以便还能够附加到 DtsDebugHost.exe 进程。If you also want to debug the component's run-time methods when a package is open and running in SSISSSIS designer, you must force a pause in the execution of the package so that you can also attach to the DtsDebugHost.exe process.

通过附加到 dtexec.exe 来调试对象的运行时方法To debug an object's run-time methods by attaching to dtexec.exe

  1. 在调试配置中,按照本主题中的说明签名和生成项目,进行部署,然后安装到全局程序集缓存中。Sign and build your project in the Debug configuration, deploy it, and install it in the global assembly cache as described in this topic.

  2. 在“项目属性” 的“调试” 选项卡中,为“启动操作” 选择“启动外部程序” ,然后查找 dtexec.exe ,默认情况下它安装在 C:\Program Files\Microsoft SQL Server\130\DTS\Binn 中。On the Debug tab of Project Properties, select Start external program as the Start Action, and locate dtexec.exe, which is installed by default in C:\Program Files\Microsoft SQL Server\130\DTS\Binn.

  3. 在“启动选项” 下的“命令行选项” 文本框中,输入运行使用了组件的包所需的命令行参数。In the Command line options text box, under Start Options, enter the command line arguments required to run a package that uses your component. 通常,命令行参数包含 /F[ILE] 开关,后跟 .dtsx 文件的路径和文件名。Often the command-line argument will consist of the /F[ILE] switch followed by the path and file name of the .dtsx file. 有关详细信息,请参阅 dtexec UtilityFor more information, see dtexec Utility.

  4. 在组件的运行时方法源代码中根据需要设置断点。Set breakpoints in the source code where appropriate in the run-time methods of your component.

  5. 运行您的项目。Run your project.

通过附加到 SQL Server Data Tools 来调试自定义对象的设计时方法To debug a custom object's design-time methods by attaching to SQL Server Data Tools

  1. 在调试配置中,按照本主题中的说明签名和生成项目,进行部署,然后安装到全局程序集缓存中。Sign and build your project in the Debug configuration, deploy it, and install it in the global assembly cache as described in this topic.

  2. 在自定义对象的设计时方法源代码中根据需要设置断点。Set breakpoints in the source code where appropriate in the design-time methods of your custom object.

  3. 打开第二个 Visual StudioVisual Studio 实例,并加载使用自定义对象的包所在的 Integration ServicesIntegration Services 项目。Open a second instance of Visual StudioVisual Studio and load an Integration ServicesIntegration Services project that contains a package that uses the custom object.

  4. Visual StudioVisual Studio 的第一个实例,附加到 devenv.exe 的第二个实例,其中包是通过从第一个实例的“调试” 菜单选择“附加到进程” 加载的。From the first instance of Visual StudioVisual Studio, attach to the second instance of devenv.exe in which the package is loaded by selecting Attach to Process from the Debug menu of the first instance.

  5. 从第二个 Visual StudioVisual Studio 实例运行包。Run the package from the second instance of Visual StudioVisual Studio.

通过附加到 SQL Server Data Tools 来调试自定义对象的运行时方法To debug a custom object's run-time methods by attaching to SQL Server Data Tools

  1. 完成上述过程中列出的步骤之后,在执行包时强制暂停,以便可附加到 DtsDebugHost.exe 中。After you have completed the steps listed in the previous procedure, force a pause in the execution of your package so that you can attach to DtsDebugHost.exe. 强制暂停的方法是:将断点添加到 OnPreExecute 事件,或将脚本任务添加到项目并输入用于显示模式消息框的脚本。You can force this pause by adding a breakpoint to the OnPreExecute event, or by adding a Script task to your project and entering script that displays a modal message box.

  2. 运行包。Run the package. 出现暂停时,切换到已在其中打开代码项目的 Visual StudioVisual Studio 实例,并从“调试” 菜单中选择“附加到进程” 。When the pause occurs, switch to the instance of Visual StudioVisual Studio in which your code project is open, and select Attach to Process from the Debug menu. 请确保附加到在“类型” 列中列为“托管,x86” 的 DtsDebugHost.exe 实例,而不是只列为 x86 的实例。Make sure to attach to the instance of DtsDebugHost.exe listed as Managed, x86 in the Type column, not to the instance listed as x86 only.

  3. 返回到暂停的包,并继续通过断点,或单击“确定” 来关闭脚本任务引发的消息框,并继续包的执行和调试。Return to the paused package and continue past the breakpoint, or click OK to dismiss the message box raised by the Script task, and continue package execution and debugging.

另请参阅See Also

开发 Integration Services 的自定义对象 Developing Custom Objects for Integration Services
使自定义对象持久化 Persisting Custom Objects
包开发的疑难解答工具Troubleshooting Tools for Package Development