17 easy steps for setting up xdt transformations in your web projects
So, what is xdt used for? Xdt is a way to generate the correct .config (or other xml-files) when you have different servers you need to deploy your web project to. This way you do no longer have to manually keep track of changes made to the different config files. (It is also used in Continous Integration, but I will not cover that here).
Xdt can of course be used for any project and xml file, but I will try to explain how you can use it in a web project.
This guide will show you how to transform not only web.config, but also appSettings.config, episerver.config and any other .config or .xml file you use. If you only use web.config, you do not need to take the steps explained in this guide and you can stop reading, if you do use other .config files, please continue:). Also, this guide will not teach you how to write the actual transforms, as it exists lots of nice guides on this already. Go to http://msdn.microsoft.com/en-us/library/dd465326.aspx to check out the xdt-language itself.
1. First of all you need a file called XmlDocumentTransform.Targets. This file is written by Vishal R Joshi, and you can get the file from Vishal here: https://skydrive.live.com/?cid=c4e57bdd18ff6eaa&id=C4E57BDD18FF6EAA%21322
2. You need to add this file to your web project, i.e undet the folder xdt.
3. On line 100, add the config/xml files you want to transform, i.e appSettings.config;EPiServer.config
4. In solution explorer: Right click your web project and choose "Unload Project".
5. In solution explorer: Right click your web project again (it should be gray by now), and choose Edit yourproject.csproj
6. Under the first <Project><PropertyGroup> node, add the following<AllXmlsToTransform>appSettings.config;EPiServer.config</AllXmlsToTransform><OnAfterTransformWebConfig>TransformXml;</OnAfterTransformWebConfig>
NB! The values in <AllXmlsToTransform> has to be the same values you added in pkt.3
7. At the very end in the file yourproject.csproj-file, just before the last </Project> node, add<Import Project="xdt\XmlDocumentTransform.Targets" Condition="Exists('xdt\XmlDocumentTransform.Targets')" />
NB! Here the values must match the path where you put your XmlDocumentTransform.Targets-file in pkt.2.
8. Given that you want to transform episerver.config and appSettings.config, change (We are still in the .csproj-file)
FROM:
<Content Include="EPiServer.config"><DependentUpon>Web.config</DependentUpon><SubType>Designer</SubType></Content>
TO:
<Content Include="EPiServer.config" />
You must also do the same for appSettings.config or any other file you want to transform.
9. Right click your project and choose "Reload Project".
10. Depending on how many servers you have with different settings, you have to create the same number of different build/publish-possibilities.Click the dropdown list where you usually can choose build method (Debug, Release), and choose Configuration Manager.
11. In the dropdown below "Active solution configuration", choose <New...>
12. Name your new build something that makes it easy to understand which server(s) it's for. I.e Test, Preprod or Prod. Make on of these build settings per server you need to deploy different settings to.
13. In your web project, you need to add one file per build setting that you just created. They MUST have the following naming standard based on the names of your build settings in pkt.11: appSettings.Test.config, appSettings.Preprod.config, appSettings.Prod.config.
NB! You do not need to add files manually for for web.config. You can instead right click (on web.config) and choose "Add Config Transforms".(You can delete Release, Debug etc if you dont need them)
14. Since appSettings.config etc can no longer be DependentUpon web.config (pkt.9), you need to do the following to get a nicer file structur: Right click your web project and choose Unload Project. Right click again and choose Edit yourproject.csproj
Find all (for Test, Preprod and Prod):
<Content Include="appSettings.Test.config" />
And change these to:
<Content Include="appSettings.Test.config"> <DependentUpon>appSettings.config</DependentUpon> <SubType>Designer</SubType></Content>
Do the same for episerver.config etc.
NB! Obviously the names have to reflect the names from pkt.11/12.
15. Right click your project and choose "Reload Project".
16. You are now ready to set up the transformations. If you are going to transform episerver.config you need to remove the namespace in the first <episerver>-node in the original episerver.config-file. That means that <episerver xmlns="http://EPiServer.Configuration.EPiServerSection"> becomes <episerver>
17. All transformation files need to have the following namespace in the first node:xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform"That means that i.e episerver.Test.config file will start with the node <episerver xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
One short example:
Your original (the one you use in the dev. environment) appSettings.config file looks like this:
<appSettings>
<add key="SomeKey1" value="SomeValue1"/>
<add key="SomeKey2" value="SomeValue2"/>
<add key="SomeKey3" value="SomeValue3"/>
<add key="SomeKey4" value="SomeValue4"/>
<add key="EmailAddressForErrorMessages" value="test@mycompany.com"/>
</appSettings>
Then your appSettings.Prod.config could look like this:
<?xml version="1.0">
<appSettings xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
<add key="EmailAddressForErrorMessages" value="error@mycompany.com" xdt:Locator="Match(key)" xdt:Transform="Replace"/>
</appSettings>
When you then choose to publish the project with the "Prod"-setting, the result i appSettings.config will be:
<appSettings>
<add key="SomeKey1" value="SomeValue1"/>
<add key="SomeKey2" value="SomeValue2"/>
<add key="SomeKey3" value="SomeValue3"/>
<add key="SomeKey4" value="SomeValue4"/>
<add key="EmailAddressForErrorMessages" value="error@mycompany.com"/>
</appSettings>
Thats it for setting up xdt in your web projects.