How to: Use AppCmd.exe to Configure IIS at Startup
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 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 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 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. 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. 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:
<Startup> <Task commandLine="Startup.cmd" executionContext="elevated" taskType="simple" /> </Startup>
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 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. IF %ERRORLEVEL% EQU 183 DO VERIFY > NUL REM If the ERRORLEVEL is not zero at this point, some other error occurred. IF %ERRORLEVEL% NEQ 0 ( ECHO Error adding a compression section to the Web.config file. >> "%TEMP%\StartupErrorLog.txt" 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 IF %ERRORLEVEL% EQU 183 VERIFY > NUL IF %ERRORLEVEL% NEQ 0 ( ECHO Error adding the JSON compression type to the Web.config file. >> "%TEMP%\StartupErrorLog.txt" GOTO ErrorExit ) REM *** Exit batch file. *** EXIT /b 0 REM *** Log error and exit *** :ErrorExit REM Report the date, time, and ERRORLEVEL of the error. DATE /T >> "%TEMP%\StartupErrorLog.txt" TIME /T >> "%TEMP%\StartupErrorLog.txt" ECHO An error occurred during startup. ERRORLEVEL = %ERRORLEVEL% >> "%TEMP%\StartupErrorLog.txt" EXIT %ERRORLEVEL%