dtexec 实用工具

  • 项目

更新日期： 2008 年 11 月 17 日

dtexec 命令提示实用工具用于配置和执行 SQL Server 2005 Integration Services (SSIS) 包。使用 dtexec 实用工具，可以访问所有包配置和执行功能，如连接、属性、变量、日志和进度指示器等。使用 dtexec 实用工具，可以加载来自以下三个源的包：Microsoft SQL Server 数据库、SSIS 服务和文件系统。

ms162810.note(zh-cn,SQL.90).gif注意：
在 64 位计算机上，Integration Services 将同时安装 32 位和 64 位版本的 dtexec 实用工具 (dtexec.exe)。

该实用工具的执行过程经历四个阶段。这些阶段如下所列：

  1. 命令选项确定阶段：命令提示符读取选项列表和已指定的参数。如果遇到 /? 或 /HELP 选项，则会跳过所有后续阶段。
  2. 包加载阶段：加载 /SQL、/FILE 或 /DTS 选项指定的包。
  3. 配置阶段：按以下顺序处理各个选项：
    • 设置包标志、变量和属性的选项。
    • 验证包版本和内部版本的选项。
    • 配置实用工具运行时行为（如报告）的选项。
  4. 验证和执行阶段：运行包。如果指定了 /VALIDATE 选项，则验证但不运行包。

dtexec 实用工具返回的退出代码

运行包时，dtexec 可能会返回退出代码。使用该退出代码填充 ERRORLEVEL 变量，然后可以在批处理文件的条件语句或分支逻辑中测试该变量的值。下表列出了 dtexec 实用工具退出时可以设置的值。

值 说明

0

已成功执行包。

1

包失败。

3

用户取消了包。

4

实用工具找不到请求的包。无法找到包。

5

实用工具无法加载请求的包。无法加载包。

6

实用工具的命令行中有内部语法错误或语义错误。

实用工具语法规则

所有选项必须以斜杠 (/) 或减号 (-) 开头。此处显示的选项以斜杠 (/) 开始，但可用减号 (-) 替换。

如果参数包含空格，则必须用引号将该参数引起来。如果没有使用引号将参数引起来，则该参数不能包含空格。

用引号引起来的字符串中的双引号表示转义单引号。

除密码外，其他选项和参数都不区分大小写。

从 xp_cmdshell 中使用 dtexec

可以从 xp_cmdshell 提示符下运行 dtexec。以下示例显示如何运行名为 UpsertData.dtsx 的包并忽略返回代码：

EXEC xp_cmdshell 'dtexec /f "C:\UpsertData.dtsx"'

以下示例显示如何运行相同的包并捕获返回代码：

DECLARE @returncode int
EXEC @returncode = xp_cmdshell 'dtexec /f "C:\UpsertData.dtsx"'
ms162810.note(zh-cn,SQL.90).gif重要提示：
在 Microsoft SQL Server 2005 中，默认情况下，新安装中将禁用 xp_cmdshell 选项。可以通过使用外围应用配置器工具或通过运行 sp_configure 系统存储过程来启用该选项。有关详细信息，请参阅 xp_cmdshell 选项。

语法

dtexec /option [value] [/option [value]]...

参数

若要了解用于 SQL Server 2000 dtsrun 实用工具的命令提示符选项如何映射到用于 SQL Server 2005 dtexec 实用工具的命令提示符选项，请参阅 dtsrun 到 dtexec 的命令选项映射。有关如何升级这些实用工具的建议，请参阅升级 dtsrun 命令行。

选项

说明

/? [option_name]

（可选）。显示命令提示符选项，或显示指定的 option_name 的帮助，然后关闭实用工具。

如果指定 option_name 参数，则 dtexec 将启动 SQL Server 联机丛书并显示 dtexec 实用工具 主题。

**/CheckF[ile]**filespec

（可选）。将包中的 CheckpointFileName 属性设置为 filespec 中指定的路径和文件。重新启动包时将使用此文件。如果指定了该选项并且未提供文件名值，则包的 CheckpointFileName 将被设置为空字符串。如果不指定该选项，则保留包中的值。

/CheckP[ointing]{on\off}

（可选）。设置一个值，用于确定包执行期间包是否使用检查点。值 on 指定要重新运行失败的包。重新运行失败的包时，运行时引擎将使用检查点文件，以便从失败点重新启动包。

如果声明该选项时未提供值，则默认值为“on”。如果值设置为“on”，但找不到检查点文件，则包执行将失败。如果不指定该选项，则保留包中设置的值。有关详细信息，请参阅在包中使用检查点。

dtexec 的 /CheckPointing on 选项等效于将包的 SaveCheckpoints 属性设置为 True，并将 CheckpointUsage 属性设置为 Always。

**/Com[mandFile]**filespec

（可选）。指定在实用工具的命令选项确定阶段，打开 filespec 中指定的文件，并读取该文件中的选项，直到在文件中找到 EOF。filespec 是一个文本文件，它包含其他 dtexec 命令选项。filespec 参数指定与包执行关联的命令文件的文件名和路径。

**/Conf[igFile]**filespec

（可选）。指定要从中提取值的配置文件。使用该选项，可以设置一个与设计包时指定的配置不同的运行时配置。可以将不同的配置设置存储在 XML 配置文件中，然后在执行包之前使用 /ConfigFile 选项加载这些设置。

ms162810.note(zh-cn,SQL.90).gif注意：

如果 /ConfigFile 选项为配置文件指定的位置不同于包指定的位置，则 dtexec 实用工具会引发警告。您可以忽略此警告。只要 /ConfigFile 选项指定一个有效的文件路径，则 dtexec 实用工具会找到并使用 /ConfigFile 选项指定的配置文件。

**/Conn[ection]**id_or_name;connection_string [[;id_or_name;connection_string]…]

（可选）。指定带有指定名称或 GUID 的连接管理器位于包中，并指定了连接字符串。

该选项要求同时指定两个参数：必须在 id_or_name 参数中提供连接管理器名称或 GUID，并且在 connection_string 参数中指定有效的连接字符串。有关详细信息，请参阅连接管理器。

/Cons[oleLog] [[displayoptions];[list_options;src_name_or_guid]...]

（可选）。在包执行过程中，在控制台显示指定日志项。如果省略该选项，则不会在控制台中显示日志项。如果指定该选项时不带限制显示的参数，则会显示所有日志项。若要限制控制台显示的日志项，可以使用 displayoptions 参数指定要显示的列，并使用 list_options 参数限制日志项类型。

displayoptions 值包括：

  • N（名称）
  • C（计算机）
  • O（操作员）
  • S（源名称）
  • G（源 GUID）
  • X（执行 GUID）
  • M（消息）
  • T（开始和结束时间）

list_options 值包括：

  • I - 指定包含列表。仅记录指定的源名称或 GUID。
  • E - 指定排除列表。不记录指定的源名称或 GUID。
  • 为包含或排除指定的 src_name_or_guid 参数是事件名称、源名称或源 GUID。

如果在同一个命令提示符中使用了多个 /ConsoleLog 选项，它们的相互影响如下：

  • 它们的出现顺序没有影响。
  • 如果命令行中不存在包含列表，将对所有类型日志项应用排除列表。
  • 如果命令行中存在包含列表，将对所有包含列表统一应用排除列表。

有关 /ConsoleLog 选项的若干示例，请参阅备注部分。

**/D[ts]**package_path

（可选）。从 SSIS 包存储区加载包。package_path 参数指定 SSIS 包的相对路径，从 SSIS 包存储区的根目录开始，包括 SSIS 包的名称。如果 package_path 参数中指定的路径或文件名包含空格，则必须在 package_path 参数两侧加上引号。

/DTS 选项不能与 /File 或 /SQL 选项一起使用。如果指定多个选项，dtexec 将失败。

/De[crypt] password

（可选）。设置加载使用密码加密的包时所用的解密密码。

**/F[ile]**filespec

（可选）。加载保存在文件系统中的包。filespec 参数指定包的路径和文件名。可以将路径指定为通用命名约定 (UNC) 路径或本地路径。如果 filespec 参数中指定的路径或文件名包含空格，则必须在 filespec 参数两侧加上引号。

/File 选项不能与 /DTS 或 /SQL 选项一起使用。如果指定多个选项，dtexec 将失败。

/H[elp] [option_name]

（可选）。显示选项的帮助，或显示指定的 option_name 的帮助，同时关闭实用工具。

如果指定 option_name 参数，则 dtexec 将启动 SQL Server 联机丛书并显示 dtexec 实用工具 主题。

**/L[ogger]**classid_orprogid;configstring

（可选）。将一个或多个日志提供程序与 SSIS 包的执行关联。classid_orprogid 参数指定日志提供程序，可以指定为类 GUID。configstring 是用于配置日志提供程序的字符串。

以下列表显示了可用的日志提供程序：

  • 文本文件：
    • ProgID：DTS.LogProviderTextFile.1
    • ClassID：{59B2C6A5-663F-4C20-8863-C83F9B72E2EB}
  • SQL Server Profiler:
    • ProgID：DTS.LogProviderSQLProfiler.1
    • ClassID：{5C0B8D21-E9AA-462E-BA34-30FF5F7A42A1}
  • SQL Server:
    • ProgID：DTS.LogProviderSQLServer.1
    • ClassID：{6AA833A1-E4B2-4431-831B-DE695049DC61}
  • Windows 事件日志：
    • ProgID：DTS.LogProviderEventLog.1
    • ClassID：{97634F75-1DC7-4F1F-8A4C-DAF0E13AAA22}
  • XML 文件：
    • ProgID：DTS.LogProviderXMLFile.1
    • ClassID：{AFED6884-619C-484F-9A09-F42D56E1A7EA}

**/M[axConcurrent]**concurrent_executables

（可选）。指定包可以同时执行的可执行文件数。指定的值必须是非负整数或 -1。如果值为 -1，则表示 SSIS 允许并发运行的最大可执行文件数，该数目等于执行包的计算机的处理器总数加二。

**/P[assword]**password

（可选）。允许检索受 SQL Server 身份验证保护的包。该选项与 /User 选项一起使用。如果省略 /Password 选项并使用 /User 选项，则使用空白密码。password 值可以用引号引起来。

ms162810.security(zh-cn,SQL.90).gif安全说明：

请尽可能使用 Windows 身份验证。

/Remcomment

（可选）。在命令提示符或命令文件中包含注释。该参数可选。comment 的值是字符串，必须用引号引起来或不含空格。如果未指定参数，将插入一个空行。在命令选项确定阶段，将放弃 comment 值。

**/Rep[orting]**level [;event_guid_or_name[;event_guid_or_name[...]]

（可选）。指定要报告的消息类型。level 可用的报告选项如下：

N 无报告。

E 报告错误。

W 报告警告。

I 报告信息性消息。

C 报告自定义事件。

D 报告数据流任务事件。

P 报告进度。

V 详细报告。

V 和 N 参数与所有其他参数互相排斥，必须单独指定。如果不指定 /Reporting 选项，则默认级别为 E（错误）、W（警告）和 P（进度）。

所有事件前都有一个格式为“YY/MM/DD HH:MM:SS”的时间戳以及一个 GUID 或友好名称（如果可用）。

可选参数 event_guid_or_name 是日志提供程序的异常列表。该异常指定本应记录但却未记录的事件。

如果默认情况下通常不记录某个事件，则不必排除该事件。

/Res[tart] {deny | force | ifPossible}

（可选）。为包的 CheckpointUsage 属性指定新值。各参数的含义如下：

Deny 将 CheckpointUsage 属性设置为 DTSCU_NEVER。

Force 将 CheckpointUsage 属性设置为 DTSCU_ALWAYS。

ifPossible 将 CheckpointUsage 属性设置为 DTSCU_IFEXISTS。

如果不指定值，则使用默认值 force。

/SetpropertyPath;value

（可选）。覆盖包中变量、属性、容器、日志提供程序、Foreach 枚举器或连接的配置。使用该选项时，/SET 可将 propertyPath 参数更改为指定的值。可以指定多个 /SET 选项。

可以通过运行包配置向导确定 propertyPath 的值。选定项的路径会显示在最后一个**“完成向导”**页中，可以进行复制和粘贴。如果仅以此目的使用该向导，则可以在复制路径后取消它。

下面是执行包并为变量提供新值的示例：

dtexec /f mypackage.dtsx /set \package.variables[myvariable].Value;myvalue

**/Ser[ver]**server

（可选）。指定了 /SQL 或 /DTS 选项时，此选项可以指定从中检索包的服务器的名称。如果省略 /Server 选项并指定 /SQL 或 /DTS 选项，则尝试对本地服务器执行包。server_instance 值可以用引号引起来。

**/SQ[L]**package_path

加载一个存储在 SQL Server 中的包。package_path 参数指定要检索的包的名称。如果文件夹包含在路径中，则文件夹将以反斜杠（\）结束。package_path 值可以用引号引起来。如果 package_path 参数中指定的路径或文件名包含空格，则必须在 package_path 参数两侧加上引号。

可以将 /User、/Password 和 /Server 选项与 /SQL 选项一起使用。

如果省略 /User 选项，则使用 Windows 身份验证来访问包。如果使用 /User 选项，指定的 /User 登录名将与 SQL Server 身份验证相关联。

/Password 选项仅与 /User 选项一起使用。如果使用 /Password 选项，则使用提供的用户名和密码信息访问包。如果省略 /Password 选项，则使用空密码。

安全说明请尽可能使用 Windows 身份验证。

如果省略 /Server 选项，则假定使用 SQL Server 的默认本地实例。

/SQL 选项不能与 /DTS 或 /File 选项一起使用。如果指定多个选项，dtexec 将失败。

/Su[m]

（可选）。显示一个递增计数器，其中包含下一个组件将接收的行数。

**/U[ser]**user_name

（可选）。允许检索受 SQL Server 身份验证保护的包。仅当指定了 /SQL 选项时才使用此选项。user_name 值可以用引号引起来。

安全说明请尽可能使用 Windows 身份验证。

/Va[lidate]

（可选）。在验证阶段之后停止执行包，而不实际运行包。如果在验证期间使用 /WarnAsError 选项，则会导致 dtexec 将警告视为错误，因此使得包在验证期间出现警告时失败。

**/VerifyB[uild]**major[;minor[;build]]

（可选）。根据验证阶段在 major、minor 和 build 参数中指定的内部版本号，验证包的内部版本号。如果出现不匹配，则将不执行包。

这些值是长整数。此参数可以使用以下三种格式之一，其中必须要有 major 的值：

  • major
  • major;minor
  • major; minor; build

**/VerifyP[ackageID]**packageID

（可选）。通过将要执行的包的 GUID 与 package_id 参数中指定的值进行比较，来验证该 GUID。

/VerifyS[igned]

（可选）。如果指定该选项但未对其签名，则包将失败。

**/VerifyV[ersionID]**versionID

（可选）。通过将要执行的包的版本 GUID 与包验证阶段 version_id 参数中指定的值进行比较，来验证该 GUID。

/W[arnAsError]

（可选）。导致包将警告视为错误，使得包在验证期间出现警告时失败。如果验证期间无警告并且未指定 /Validate 选项，则执行包。

备注

命令选项的指定顺序可以影响包的执行方式：

  • 选项的处理顺序与其在命令行中出现的顺序一致。命令文件的读取顺序与其在命令行中出现的顺序一致。命令文件中的命令的处理顺序也与其出现的顺序一致。
  • 如果在同一个命令行语句中多次出现相同的选项、参数或变量，则优先执行该选项的最后一个实例。
  • /Set 和 /ConfigFile 选项将按其出现的顺序进行处理。

示例

正在运行的包

若要使用 Windows 身份验证执行保存到 SQL Server 的 SSIS 包，可使用以下代码：

dtexec /sq pkgOne /ser productionServer

若要执行保存到 SSIS 包存储区的“文件系统”文件夹中的 SSIS 包，请使用以下代码：

dtexec /dts "\File System\MyPackage"

若要验证使用 Windows 身份验证并保存在 SQL Server 中的包但不执行该包，可使用以下代码：

dtexec /sq pkgOne /ser productionServer /va

若要执行保存在文件系统中的 SSIS 包，可使用以下代码：

dtexec /f "c:\pkgOne.dtsx"

若要执行保存在文件系统中的 SSIS 包并指定日志选项，可使用以下代码：

dtexec /f "c:\pkgOne.dtsx" /l "DTS.LogProviderTextFile;c:\log.txt"

若要执行使用 Windows 身份验证并保存至 SQL Server 的默认本地实例的包，并在执行前查看其版本，可使用以下代码：

dtexec /sq pkgOne /verifyv {c200e360-38c5-11c5-11ce-ae62-08002b2b79ef}

若要执行保存在文件系统中并在外部配置的 SSIS 包，可使用以下代码：

dtexec /f "c:\pkgOne.dtsx" /conf "c:\pkgOneConfig.cfg"
ms162810.note(zh-cn,SQL.90).gif注意：
如果路径或文件名包含空格，则 /SQL、/DTS 或 /FILE 选项的 package_path 或 filespec 参数必须用引号引起来。如果没有使用引号将参数引起来，则该参数不能包含空格。

日志记录选项

如果有三种日志项类型 A、B 和 C，以下不带参数的 ConsoleLog 选项可以显示所有三种日志类型和所有字段：

/CONSOLELOG

以下选项显示所有日志类型，但只显示 Name 和 Message 列：

/CONSOLELOG NM

以下选项仅显示日志项类型 A 的所有列：

/CONSOLELOG I;LogEntryTypeA

以下选项仅显示日志项类型 A 的 Name 和 Message 列：

/CONSOLELOG NM;I;LogEntryTypeA

以下选项显示日志项类型 A 和 B 的日志项：

/CONSOLELOG I;LogEntryTypeA;LogEntryTypeB

可以使用多个 ConsoleLog 选项来获得相同的结果：

/CONSOLELOG I;LogEntryTypeA /CONSOLELOG I;LogEntryTypeB

如果使用不带参数的 ConsoleLog 选项，将显示所有字段。包含 list_options 参数会导致以下示例仅显示日志项类型 A 和所有字段：

/CONSOLELOG NM;I;LogEntryTypeA /CONSOLELOG

以下示例可以显示除日志项类型 A 以外的所有日志项，即显示日志项类型 B 和 C：

/CONSOLELOG E;LogEntryTypeA

以下示例通过使用多个 ConsoleLog 选项和一个排除条件可获得相同的结果：

/CONSOLELOG E;LogEntryTypeA /CONSOLELOG
/CONSOLELOG E;LogEntryTypeA /CONSOLELOG E;LogEntryTypeA
/CONSOLELOG E;LogEntryTypeA;LogEntryTypeA

以下示例不显示日志消息，因为一个日志文件类型同时出现在包含列表和排除列表中时，该类型将被排除。

/CONSOLELOG E;LogEntryTypeA /CONSOLELOG I;LogEntryTypeA

SET 选项

以下示例显示如何使用 /SET 选项。从命令行启动包时，使用该选项可以更改任何包属性或变量的值。

/SET \package\DataFlowTask.Variables[User::MyVariable].Value;newValue

请参阅

概念

dtsrun 到 dtexec 的命令选项映射

其他资源

如何在 Business Intelligence Development Studio 中运行包
64 位计算机上的 Integration Services 注意事项

帮助和信息

获取 SQL Server 2005 帮助

更改历史记录

版本 历史记录

2008 年 11 月 17 日
更改的内容：
  • 添加了有关如果 /ConfigFile 选项为配置文件指定的位置不同于包指定的位置，则 dtexec 实用工具会引发警告的说明。

2006 年 7 月 17 日
更改的内容：
  • 对错误代码进行了更详细的说明。
  • 添加了显示错误代码捕获的语法示例。
  • 说明了 CheckPointing on 选项与 UI 属性 CheckpointUsage 的等效性。

2006 年 4 月 14 日
更改的内容：
  • 说明了包含空格的参数必须用引号引起来。
  • 添加了有关如何执行保存到文件系统的 SSIS 包的示例。

2005 年 12 月 5 日
更改的内容：
  • 添加了默认情况下将禁用 xp_cmdshell 的重要通知。