Your official information source from the .NET Web Development and Tools group at Microsoft.
Hi everyone Sayed here. I recently had a customer, Johan, contact me to help with some challenges regarding deployment automation. He had some very specific requirements, but he was able to automate the entire process. He has been kind enough to agree to write up his experience to share with everyone. His story is below. If you have any comments please let us know. I will pass them to Johan.
I’d like to thank Johan for his willingness to write this up and share it. FYI if you’d like me to help you in your projects I will certainly do my best, but if you are willing to share your story like Johan it will motivate me more :) – Sayed
We have an Umbraco CMS web site where deployment is specific to certain folders only and not the complete website. Below is a snapshot of a typical Umbraco website.
I have omitted root files such as web.config as they never get deployed. Now as we develop new features, only those purple folders gets modified so there is no need to redeploy the bulky yellow folders which mostly contains the Umbraco CMS admin system. I will refer to these purple folders as release files.
The green media folder is a special case. Our ecommerce team modifies the content on a daily basis in a CMS environment. They may publish their changes to production at will. Content related files from this folder automatically synchronises to the production environment through a file watcher utility. Thus the CMS and PROD environments always contain the latest versions and we can never overwrite this.
This results in a special case for deployment. These are the steps we follow:
1. When preparing the QA environment, we first update the media folder from CMS
2. Then we transfer all the release files from DEV to QA
3. After QA sign off, we deploy those same the release files to PROD
4. Next we update the CMS release files
5. And then finally the media is transferred to DEV so
This flow is illustrated below:
Previously this was done by zipping folders up, transferring it to the different environments, expanding and then overriding the target destination. This was tedious and obviously quite risky. With assistance from Sayed Hashimi at Microsoft, I have managed to greatly simplify this task through MsDeploy.
MsDeploy can be downloaded here and the command line utility normally installs at:
c:\Program Files\IIS\Microsoft Web Deploy V3\msdeploy.exe
The syntax I will concentrate on is as follows (more details can be found here):
The ‘useCheckSum’ setting will ensure that only file changes are considered and ‘disableRule:BackupRule’ setting will stop warnings from being thrown. Automatic backups can be enabled with these instructions, but to keep things simple, we will create our own backups.
For the purposes of illustration, we’ll assume that our websites are all installed at the following location in each environment:
First we need to package up the media folder to a zip file, transfer it over to the QA environment and then deploy that package. We’ll create a .bat file and an .xml file that we can reuse in the future. On the CMS box at a location of your choice, create a Package.bat file with the following contents:
"c:\Program Files\IIS\Microsoft Web Deploy V3\msdeploy.exe" ^
-dest:package="Media @ %date:~6,4%-%date:~3,2%-%date:~0,2% %time:~0,2%-%time:~3,2%.zip" ^
Also create a Package.xml file at the same location with the following contents:
<?xml version="1.0" encoding="utf-8"?>
When you execute the Package.bat file, it will create a zip file (i.e. Media @ 2013-01-05 10-00.zip) containing the folder and subfolders you listed in Package.xml. Now we transfer the zip file to the QA box into a folder of our choice. In that same folder, create a Deploy.bat file with the following contents:
set /p package=Enter the package name (tab to cycle):
if '%package%' == '' goto error
set /p manifest=Enter the manifest name (tab to cycle):
if '%manifest%' == '' goto error
set /p deploy=Trial run complete - proceed to deployment (Y/N)?
if "%deploy%"=="Y" goto deploy
if "%deploy%"=="y" goto deploy
move %package% Archive
echo You did not enter a package name
Also create a Media.xml file at the same location with the same contents as Package.xml listed above. Update any paths if required.
When you now execute the batch file, supply the package filename when prompted (you can use the tab key to cycle through files in the same folder). Note that we used the ‘-dest:manifest=”Media.xml”’ parameter with MsDeploy. This does not modify Media.xml but rather uses it as reference for deployment instructions. Also note that MsDeploy executes twice, but the first time it uses the ‘-whatif’ parameter. This gives you the chance to test the deployment first without making any modifications. It will spew out the same output as always but only simulate the syncing of files. Then you will be prompted to commit the deployment and if you proceed, the QA website’s media folder should now be synced up with the CMS environment.
On the DEV box in a folder of your choice, create a Package.bat file with the following contents:
-dest:package="Release @ %date:~6,4%-%date:~3,2%-%date:~0,2% %time:~0,2%-%time:~3,2%.zip" ^
Also create a Package.xml file with the following contents:
Executing the batch file will give you a zip file such as Release @ 2013-01-05 10-00.zip containing the release folders. Transfer the zip file to the QA box into the same folder as before. Then create a Release.xml file with the same contents as Package.xml listed above and fix the path names. When you now execute the Deploy.bat batch file and supply the release package filename, the QA website’s release folders should now be synced up with the DEV environment.
This follows the same deployment as in step 2, but here we include in a backup step. So after choosing a suitable folder and transferring the release package file there, create a Deploy.bat file with the following contents:
-dest:package="Archive\Backup @ %date:~6,4%-%date:~3,2%-%date:~0,2% %time:~0,2%-%time:~3,2%.zip" ^
echo Backup complete
echo Deploy complete
Now create a Deploy.xml file with the same contents as Package.xml from step 2 and fix the paths. Once all is in place and the trail run succeeds, you can proceed and deploy your changes to the PROD website.
In addition to releasing your changes, it will first create a backup in the Archive folder such as Backup @ 2013-01-05 10-00.zip containing the original folders. If you need to do a restore, you can just execute Deploy.bat with this same backup file.
Now everything becomes a formality and you can just repeat the release part of “Step 2: Release to QA” to update the CMS box. After executing Deploy.bat, all environments are now running the same code.
For this final step just repeat “Step 1: Update the QA media folder”. Now all environments should have the same content.
I hope this will be helpful to someone with the same problem or something similar where only subsets of folders require updates. There is a lot of room for enhancement, i.e. becoming more creative with the zip file naming convention by including labels. MsDeploy is a great tool and can be used to deploy not just websites, but other kinds of projects which are as well. Please feel free to ask me questions. If I cannot help, I’m sure Sayed or someone at Microsoft will come to the rescue.
You can download the SampleFiles to help work through the process as well.
Johan van der Merwe
Very nice overview, helped me a lot :)