xp_cmdshell (Transact-SQL)

Artículo
12/15/2008

Crea un shell de comandos de Windows y lo pasa a una cadena para ejecutarlo. Los resultados se devuelven como filas de texto.

Icono de vínculo a temas Convenciones de sintaxis de Transact-SQL

Sintaxis

xp_cmdshell { 'command_string' } [ , no_output ]

Argumentos

'command_string'
Es la cadena que contiene un comando que se pasa al sistema operativo. El parámetro command_string es de tipo varchar(8000) o nvarchar(4000) y no tiene valor predeterminado. El parámetro command_string no puede contener más de un conjunto de comillas dobles. Es necesario un único par de comillas dobles si hay espacios en las rutas de acceso a archivos o en los nombres de programa a los que hace referencia command_string. Si tiene problemas con espacios incrustados, considere el uso de nombres de archivo de tipo FAT 8.3 como solución.

no_output
Es un parámetro opcional que especifica que no se devuelven resultados al cliente.

Conjuntos de resultados

La ejecución de la instrucción xp_cmdshell devuelve una lista de directorios del directorio actual.

EXEC xp_cmdshell 'dir *.exe';
GO

Las filas se devuelven en una columna de tipo nvarchar(255). Si se utiliza la opción no_output, sólo se devolverá lo siguiente:

The command(s) completed successfully.

Notas

El proceso de Windows creado por xp_cmdshell dispone de los mismos derechos de seguridad que la cuenta de servicio de SQL Server.

xp_cmdshell opera de forma sincrónica. No se devolverá el control al llamador hasta que el comando del shell de comandos esté completo.

Es posible habilitar y deshabilitar xp_cmdshell con la herramienta de configuración de superficie y ejecutando sp_configure. Para obtener más información, vea Configuración de superficie y xp_cmdshell (opción).

Importante:
Si se ejecuta xp_cmdshell en un lote y devuelve un error, se producirán errores en el lote. Es un cambio de comportamiento. En versiones anteriores de Microsoft SQL Server, el lote continuaría su ejecución.

Cuenta de proxy xp_cmdshell

Cuando es llamada por un usuario que no pertenece a la función fija de servidor sysadmin, xp_cmdshell se conecta a Windows con el nombre de cuenta y la contraseña almacenados en la credencial con el nombre ##xp_cmdshell_proxy_account##. Si no existe esta credencial de proxy, xp_cmdshell registrará errores.

Para crear la credencial de cuenta de proxy, debe ejecutar sp_xp_cmdshell_proxy_account. Como argumentos, este procedimiento almacenado utiliza un nombre de usuario y una contraseña de Windows. Por ejemplo, el siguiente comando crea una credencial de proxy para el usuario de dominio de Windows SHIPPING\KobeR que tiene la contraseña de Windows sdfh%dkc93vcMt0.

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

Para obtener más información, vea sp_xp_cmdshell_proxy_account (Transact-SQL).

Permisos

Requiere el permiso CONTROL SERVER.

Valores de código de retorno

0 (correcto) o 1 (error)

Ejemplos

A. Devolver una lista de archivos ejecutables

En el siguiente ejemplo se muestra el procedimiento almacenado extendido xp_cmdshell ejecutando un comando de directorio.

EXEC master..xp_cmdshell 'dir *.exe'

B. Usar comandos de red de Windows

En el siguiente ejemplo se muestra el uso de xp_cmdshell en un procedimiento almacenado. En este ejemplo se notifica a los usuarios mediante net send que una instancia de SQL Server va a cerrarse, interrumpe el servidor mediante net pause y cierra el servidor utilizando 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. No devolver resultados

En el siguiente ejemplo se utiliza xp_cmdshell para ejecutar una cadena de comandos sin devolver los resultados al cliente.

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

D. Utilizar el estado de retorno

En el siguiente ejemplo, el procedimiento almacenado extendido xp_cmdshell también sugiere el estado de retorno. El valor del código de retorno se almacena en la variable @result.

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

E. Escribir el contenido de variables en un archivo

En el siguiente ejemplo se escribe el contenido de la variable @var en un archivo denominado var_out.txt en el directorio actual del servidor.

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

F. Capturar el resultado de un comando en un archivo

En el siguiente ejemplo se escribe el contenido del directorio actual en un archivo denominado dir_out.txt en el directorio actual del servidor.

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

Vea también

Compartir a través de