Web Deploy runCommand Provider

Article
06/18/2012

Applies To: Windows 7, Windows Server 2003, Windows Server 2003 R2, Windows Server 2008, Windows Server 2008 R2, Windows Vista, Windows XP

runCommand

The runCommand provider runs the specified command on the destination computer.

Example

msdeploy.exe -verb:sync -source:runCommand="net start MyService" -dest:auto

The runCommand provider provides a convenient way to run an executable (.exe), batch (.bat), or command (.cmd) file remotely as part of a Web Deploy operation. The provider accepts an argument that contains the path to a batch file, command file, or executable file. If you specify a batch file or a command file, the file will be streamed to the destination computer and run as a local command on the destination computer. The executable files that are referred to in the command or batch file will not be copied; they must be already present on the destination computer. If the specified command contains spaces, the entire command must be enclosed in quotation marks.

Using runCommand in a manifest file

If you use runCommand entries in a manifest file, and the argument for runCommand contains special characters such as the conditional combination symbol "&&", you must convert the special characters into character entities (for example, "&&") so that the XML of the manifest file will be valid. For example, the following command calls a manifest file that uses the runCommand provider to stop the Web Deployment Agent Service and then start it if the stop command is successful.

msdeploy -verb:sync -source:manifest=mymanifest.xml -dest:auto

Mymanifest.xml:

<myManifest>

<runcommand path="net stop msdepsvc && net start msdepsvc" waitInterval="5000"/>

</myManifest>

Custom Provider Settings

The runCommand provider has the following optional custom provider settings:

dontUseCommandExe
waitAttempts
waitInterval
dontUseJobObject
successReturnCodes

dontUseCommandExe

Usage: ,runCommand=<filepath>,dontUseCommandExe=<BOOL>

<BOOL> must be true or false. True if the argument to the runCommand provider is treated as a path to a separate executable (.exe) file; false if it is the path to a batch (.bat) file or command (.cmd) file. The default is false. By default, the runCommand provider treats its specified argument as batch or command file and calls the Windows shell command (cmd.exe /c <batchfilename>) on the destination. If you want to run a destination executable file directly, set the dontusecommandexe provider setting to true. This will cause the executable file that you specify to be called directly ("filename.exe" instead of "cmd.exe /c filename.exe").

waitAttempts

Usage: ,runCommand=<commandfilepath>,waitAttempts=<integer>

Specifies the number of times the runCommand provider will retry after a failure. <number> specifies the number of retries. The valid integer range is from 0 through 2147483647. The default number of retries is 5. By default, there is a delay of one second between each retry.

waitInterval

Usage: ,runCommand=<commandfilepath>,waitInterval=<integer>

Specifies, in milliseconds, the interval between runCommand provider retry attempts. The valid integer range is from 0 through 2147483647. The default is 1000 (one second).

Note

The waitAttempts and waitInterval provider settings are specific to the runCommand provider and can be set separately from the -retryAttempts and -retryInterval operation settings, although their default values are the same. The -retryAttempts and -retryInterval operation settings apply to an entire Web Deploy command. Since -retryAttempts and -retryInterval are not provider-specific, they can be used by any provider to handle retry logic. They are especially useful when files may be in use, such as with the contentPath, dirPath, and filePath providers. For more information about -retryAttempts and –retryInterval, see Web Deploy Operation Settings.

dontUseJobObject

Specifies whether Job Objects are used. true specifies that Job Objects are used, false specifies that they are not used.

successReturnCodes

A semicolon (;) separated list of return values that will be treated as a success for the command. If specified, all other return values will be treated as errors.

Using runCommand with the preSync and postSync Operations Settings

To include commands that run before and after a Web Deploy operation, you can use the runCommand provider with the -presync and -postSync operation settings. This lets you, for example, stop a service, synchronize two Web servers, and start the service all in one command. The following example stops the World Wide Web Publishing Service (W3SVC) on remote computer ServerA, synchronizes the local IIS 6.0 server to ServerA, then starts the W3SVC on ServerA after the synchronization completes.

msdeploy -verb:sync -preSync:runCommand="net stop w3svc" -source:webserver60 -dest:auto,computername=serverA -verbose -postSync:runCommand="net start w3svc"

Using the runCommand Provider with the Web Management Service (WMSvc)

The runCommand provider may not execute when WMSvc is running through an impersonated account. There are two possible solutions for this issue: one is to add necessary privileges to WMSvc; the other is to add the "Replace a process level token" privilege to the user account that will execute commands for the provider.

Warning

Allowing users to use runCommand through the WMSvc is a security risk and should be avoided if possible.

To add privileges to WMSvc

Warning

Avoid adding privileges to the WMSvc if you can. Adding privileges to WMSvc will give everyone who has rights to connect to the server the right to execute commands on the server.

The WMSvc uses a Local Service SID account that has fewer privileges than the Local Service account itself. To add the additional privileges to WMSvc, type the following command at an administrative command prompt.

sc privs wmsvc SeChangeNotifyPrivilege/SeImpersonatePrivilege/SeAssignPrimaryTokenPrivilege/SeIncreaseQuotaPrivilege

Important

You must restart the WMSvc for the change to take effect.

To add the "Replace a process level token" privilege

Open an administrative command prompt window. Click Start, point to All Programs, click Accessories, right-click Command Prompt, and then click Run as administrator.
Type secpol.msc and press ENTER.
In the Local Security Policy window, under Security Settings, expand Local Policies.
Select User Rights Assignment.
In the right pane, under Policy, double-click Replace a process level token. The Replace a process level token Properties dialog box appears.
Click Add User or Group. The Select Users, Computers, or Groups dialog box appears.
Enter the user name that you want to use, then click Check Names.
Click OK twice to exit.

Example usages

1) Run the batch file “Test.bat” on the remote computer Server1.

msdeploy -verb:sync -source:runcommand=d:\test.bat -dest:auto,computername=Server1

2) Run the “Commands.cmd” command file on the remote computer Server2. Wait 30 seconds for the command to complete before terminating the Cmd.exe process.

msdeploy -verb:sync -source:runcommand=c:\Commands.cmd,waitAttempts=30 -dest:auto,computername=Server2

3) Start the Web Management Service on the remote computer Server3. Specify a wait interval of 15 seconds.

msdeploy -verb:sync -source:runcommand -dest:runcommand="net start wmsvc",waitinterval=15000, computername=Server3

4) Run the Myscript.js script file on the remote computer Server4 by calling the Cscript.exe executable file. Show all messages.

msdeploy -verb:sync -source:runCommand="cscript.exe d:\scriptfiles\myscript.js" -dest:auto,computername=Server4 -verbose

5) Using the Web Deploy tempAgent feature, run the Myscript.js script file on the remote computer Server5 by calling the Cscript.exe executable file. Show all messages.

msdeploy -verb:sync -source:runCommand="cscript.exe d:\scriptfiles\myscript.js" -dest:auto,computername=Server5,tempAgent=true -verbose

6) Run the “ListAppPools.vbs” script file on the remote computer Server6 by calling the Cscript.exe executable file. A sample script follows.

msdeploy -verb:sync -source:runcommand="cscript.exe c:\scripts\ListAppPools.vbs" -dest:auto,computername=Server6

' =====================================================================
' ListAppPools.vbs – Lists the name and mode of each application pool.
' =====================================================================
' Connect to the WMI WebAdministration namespace.
Set oWebAdmin = GetObject("winmgmts:root\WebAdministration")

' Retrieve the application pools on the server. 
Set oAppPools = oWebAdmin.ExecQuery("SELECT * FROM ApplicationPool")

For Each oAppPool In oAppPools
    WScript.Echo "--------------------------------------"
    WScript.Echo "Application pool name:    " & oAppPool.Name

    If oAppPool.ManagedPipelineMode = 0 Then
        sAppPoolMode = "Integrated"
    ElseIf oAppPool.ManagedPipelineMode = 1 Then
        sAppPoolMode = "ISAPI"
    End if

    WScript.Echo "Application pool mode:    " & sAppPoolMode
Next

Share via