master..xp_cmdshell

xp_cmdshell (Transact-SQL)

生成 Windows 命令 shell 并以字符串的形式传递以便执行。任何输出都作为文本的行返回。

语法

xp_cmdshell { \'command_string\' } [ , no_output ]

参数

\'command_string\': 包含要传递到操作系统的命令的字符串。command_string 的数据类型为 varchar(8000) 或 nvarchar(4000)，无默认值。command_string 不能包含一对以上的双引号。如果 command_string 中引用的文件路径或程序名中存在空格，则需要使用一对引号。如果不方便使用内含的空格，则可考虑使用 FAT 8.3 文件名作为解决方法。

no_output: 可选参数，指定不应向客户端返回任何输出。

返回代码值

0（成功）或 1（失败）

结果集

执行以下 xp_cmdshell 语句将返回当前目录的目录列表。

复制代码

EXEC xp_cmdshell \'dir *.exe\';
GO

行以 nvarchar(255) 列的形式返回。如果使用 no_output 选项，则仅返回以下内容：

复制代码

The command(s) completed successfully.

备注

xp_cmdshell 生成的 Windows 进程与 SQL Server 服务帐户具有相同的安全权限。

xp_cmdshell 以同步方式操作。在命令 shell 命令执行完毕之前，不会将控制权返回给调用方。

可以使用外围应用配置器工具以及通过执行 sp_configure 来启用和禁用 xp_cmdshell。有关详细信息，请参阅外围应用配置和 xp_cmdshell 选项。

重要提示：
如果 xp_cmdshell 在批处理中执行并返回错误，则该批处理将失败。这是行为的更改。在 Microsoft SQL Server 的早期版本中，批处理将会继续执行。

xp_cmdshell 代理帐户

当不属于 sysadmin 固定服务器角色成员的用户调用 xp_cmdshell 时，xp_cmdshell 会使用名为 ##xp_cmdshell_proxy_account## 的凭据中存储的帐户名和密码连接到 Windows。如果该代理凭据不存在，则 xp_cmdshell 将失败。

代理帐户凭据可以通过执行 sp_xp_cmdshell_proxy_account 来创建。此存储过程将 Windows 用户名和密码作为参数使用。例如，以下命令为具有 Windows 密码 sdfh%dkc93vcMt0 的 Windows 域用户 SHIPPING\KobeR 创建代理凭据。

复制代码

EXEC sp_xp_cmdshell_proxy_account \'SHIPPING\KobeR\',\'sdfh%dkc93vcMt0\'

有关详细信息，请参阅 sp_xp_cmdshell_proxy_account (Transact-SQL)。

权限

需要 CONTROL SERVER 权限。

示例

A. 返回可执行文件列表

以下示例显示执行目录命令的 xp_cmdshell 扩展存储过程。

复制代码

EXEC master..xp_cmdshell \'dir *.exe\'

B. 使用 Windows net 命令

以下示例显示 xp_cmdshell 在存储过程中的使用。本例使用 net send 通知用户将要关闭 SQL Server 实例，使用 net pause 暂停服务器，然后使用 net stop 关闭服务器。

复制代码

CREATE PROC shutdown10
AS
EXEC xp_cmdshell \'net send /domain:SQL_USERS \'\'SQL Server
shutting down in 10 minutes. No more connections
allowed.\', no_output
EXEC xp_cmdshell \'net pause sqlserver\'
WAITFOR DELAY \'00:05:00\'
EXEC xp_cmdshell \'net send /domain: SQL_USERS \'\'SQL Server
shutting down in 5 minutes.\', no_output
WAITFOR DELAY \'00:04:00\'
EXEC xp_cmdshell \'net send /domain:SQL_USERS \'\'SQL Server
shutting down in 1 minute. Log off now.\', no_output
WAITFOR DELAY \'00:01:00\'
EXEC xp_cmdshell \'net stop sqlserver\', no_output

C. 不返回任何输出

以下示例使用 xp_cmdshell 执行命令字符串，且不向客户端返回输出。

复制代码

USE master;
EXEC xp_cmdshell \'copy c:\SQLbcks\AdvWorks.bck
\\server2\backups\SQLbcks, NO_OUTPUT\';
GO

D. 使用返回状态

在以下示例中，xp_cmdshell 扩展存储过程也给出了返回状态。返回代码值存储在变量 @result 中。

复制代码

DECLARE @result int
EXEC @result = xp_cmdshell \'dir *.exe\'
IF (@result = 0)
PRINT \'Success\'
ELSE
PRINT \'Failure\'

E. 将变量内容写入文件中

以下示例将 @var 变量的内容写入当前服务器目录下名为 var_out.txt 的文件中。

复制代码

DECLARE @cmd sysname, @var sysname
SET @var = \'Hello world\'
SET @cmd = \'echo \' + @var + \' > var_out.txt\'
EXEC master..xp_cmdshell @cmd

F. 将命令的结果捕获到文件中

以下示例将当前目录的内容写入当前服务器目录下名为 dir_out.txt 的文件中。

复制代码

DECLARE @cmd sysname, @var sysname
SET @var = \'dir/p\'
SET @cmd = @var + \' > dir_out.txt\'
EXEC master..xp_cmdshell @cmd