SALES: 1-800-867-1380

Use AppCmd.exe to Configure IIS at Startup

Updated: October 24, 2014

The AppCmd.exe command line tool can be used to manage IIS settings at startup on Windows Azure.

AppCmd.exe provides convenient, command line access to configuration settings for use in startup tasks on Windows Azure. Using AppCmd.exe, Website settings can be added, modified, or removed for applications and sites. For more information on AppCmd.exe, see AppCmd.exe on Microsoft Technet.

To use AppCmd.exe at startup, add the appropriate AppCmd.exe commands to your startup task.

However, a few factors that can combine to complicate the use of AppCmd.exe in startup tasks:

  • Startup tasks can be run more than once between reboots. This can happen if the role recycles, for instance.

  • Some AppCmd.exe actions can generate errors if they are performed more than once. Attempting to add a section to Web.config twice could generate an error.

  • Startup tasks fail if they return a non-zero exit code or errorlevel. This can happen if AppCmd.exe generates an error.

For the reasons listed, it is often wise to check the errorlevel after AppCmd.exe executes to be sure that AppCmd.exe performed as expected. For example, after attempting to add a section to Web.config, the startup task could check if the errorlevel equals 183. An errorlevel 183 is the expected error when attempting to add a Web.config section that already exists. Because the Web.config section would have already been added by a previous execution of the startup task, the startup task should continue. Any other error, for example errorlevel 5 which is "access denied," should be logged and the startup task should exit with the errorlevel of the error. An errorlevel 5 could indicate that the executionContext attribute for the startup task may need to be elevated instead of limited. The errorlevels returned by AppCmd.exe are listed in the winerror.h file, and can also be seen at System Error Codes on MSDN.

This example adds a compression section and a compression entry for JSON to the Web.config file, with error handling and logging.

The relevant sections of the ServiceDefinition.csdef file are shown here, which include setting the executionContext attribute to elevated to give AppCmd.exe sufficient permissions to change the settings in the Web.config file:

      <Task commandLine="Startup.cmd" executionContext="elevated" taskType="simple" />

The Startup.cmd batch file uses AppCmd.exe to add a compression section and a compression entry for JSON to the Web.config file. The expected errorlevel of 183 is set to zero using the VERIFY.EXE command line program. Unexpected errorlevels are logged to StartupErrorLog.txt.

REM   *** Add a compression section to the Web.config file. ***
%windir%\system32\inetsrv\appcmd set config /section:urlCompression /doDynamicCompression:True /commit:apphost >> "%TEMP%\StartupLog.txt" 2>&1

REM   ERRORLEVEL 183 occurs when trying to add a section that already exists. This error is expected if this
REM   batch file were executed twice. This can occur and must be accounted for in a Windows Azure startup
REM   task. To handle this situation, set the ERRORLEVEL to zero by using the Verify command. The Verify
REM   command will safely set the ERRORLEVEL to zero.

REM   If the ERRORLEVEL is not zero at this point, some other error occurred.
   ECHO Error adding a compression section to the Web.config file. >> "%TEMP%\StartupLog.txt" 2>&1
   GOTO ErrorExit

REM   *** Add compression for json. ***
%windir%\system32\inetsrv\appcmd set config  -section:system.webServer/httpCompression /+"dynamicTypes.[mimeType='application/json; charset=utf-8',enabled='True']" /commit:apphost >> "%TEMP%\StartupLog.txt" 2>&1
   ECHO Error adding the JSON compression type to the Web.config file. >> "%TEMP%\StartupLog.txt" 2>&1
   GOTO ErrorExit

REM   *** Exit batch file. ***
EXIT /b 0

REM   *** Log error and exit ***
REM   Report the date, time, and ERRORLEVEL of the error.
DATE /T >> "%TEMP%\StartupLog.txt" 2>&1
TIME /T >> "%TEMP%\StartupLog.txt" 2>&1
ECHO An error occurred during startup. ERRORLEVEL = %ERRORLEVEL% >> "%TEMP%\StartupLog.txt" 2>&1

See Also

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
© 2015 Microsoft