Web Deploy recycleApp Provider
Applies To: Windows 7, Windows Server 2003, Windows Server 2003 R2, Windows Server 2008, Windows Server 2008 R2, Windows Vista, Windows XP
recycleApp
The recycleApp provider recycles an IIS 7 application pool.
Example
msdeploy.exe -verb:sync -source:recycleApp="Default Web Site/myapp" -dest:auto
The recycleApp provider recycles, starts, or stops an IIS 7 application pool, or unloads an application's application domains for a specified Web site or application. It takes as an argument the name of a Web site, or the name of an application in the form <Web site name>/<application name>. You cannot specify the name of an application pool directly as an argument. The recycleApp provider requires an administrative user account.
Warning
The recycleApp provider is not supported on IIS 6.0 or earlier versions of IIS.
Warning
If you do not have a single application pool for each Web site or application, use caution when creating a rule that uses the recycleApp provider. Such a rule could allow users to recycle, start or stop an application pool for Web sites or applications that they are not authorized to manage.
dump
You can use the dump operation to show the status of an application pool. If you do not specify the -xml operation setting, the application path that you specified as an argument to the provider is returned. If you specify the -xml operation setting, the results are returned in XML format. The returned attributes include the Web site or application path that you specified, the name of the application pool, the state of the application pool (for example, stopped or started) and the number of worker processes that are currently active.
sync
In a sync operation, specify recycleApp for both the source and dest arguments. In the dest argument, specify the application path and any provider settings. If the target server is remote, include the computername parameter in the dest argument. If you specify the –xml operation setting, traceEvent and syncResults information will appear in the attributes that are displayed.
Custom Provider Settings
The recycleApp provider has 2 optional custom provider settings: recycleMode and timeout.
recycleMode
The recycleMode custom provider setting takes one of four arguments that determine the action that is taken on the application pool.
Usage: ,recycleMode=[RecycleAppPool | StartAppPool | StopAppPool | UnloadAppDomain]
The following table describes each argument.
| Argument | Description |
|---|---|
RecycleAppPool |
Stops and starts the application pool for the specified Web site. The applications in the application pool may be temporarily unavailable until the recycle completes. This is the default. |
StartAppPool |
Starts the application pool for the specified Web site. All applications in the application pool will be available. |
StopAppPool |
Stops the application pool for the specified Web site. All applications in the application pool will be unavailable and will return 503 (Service Unavailable) error messages until the application pool is restarted. |
UnloadAppDomain |
Unloads the application domain for the specified Web site. |
Tip
If you are a Web hoster, a recommended best practice is that you maintain a single application pool for each Web site. Doing this lets you permit each user to use the recycleMode provider setting with the recycleApp provider to start or stop their his or her own application pool. For example, a customer who runs a hosted Web site could use Web Deploy to 1) call the recycleApp provider to take his Web site offline prior to deployment of new content; 2) deploy (synchronize) the new content; and 3) call the recycleApp provider again to start the application pool for the site. If each site has its own application pool, none of these steps should require intervention from the hoster.
timeout
The timeout custom provider setting specifies the amount of time, in milliseconds, that the recycleApp provider will wait for an application pool to recycle, start, or stop.
Usage: ,timeout=<milliseconds>
To return control from the provider immediately (without waiting for completion of the requested action), specify zero. To use the application pool's values of the startupTimeLimit and shutdownTimeLimit attributes (or the sum of their values in the case of a recycle), specify -1. The default is -1. For more information about the startupTimeLimit and shutdownTimeLimit attributes, see Process Model Settings for an Application Pool <processModel>.
Example usages
1) Stop the application pool for the "myapp" application under the default Web site by using the recycleMode=StopAppPool provider setting. All applications in the application pool will be unavailable and will return 503 (Service Unavailable) error messages until the application pool is restarted.
msdeploy.exe -verb:sync -source:recycleApp -dest:recycleApp="Default Web Site/myapp",recycleMode="StopAppPool"
2) Recycle the application pool for the "MyRemoteApp" application on the remote computer RemoteServer1.
msdeploy.exe -verb:sync -source:recycleApp -dest="RemoteSite1/MyRemoteApp",computername=RemoteServer1