This nuget package adds a convention to Visual Studio projects to allow building .config files depending on environment. For example, if developers has different databases configured in web.config, this package can support each developer with a unique web.config.
The config builder aims to make it easy to maintain multiple development environments for a project. The config builder can perform two different methods of build, merge and replace.
You maintain a base configuration (like web.config) and several others (one for each development environment, build configuration etc.) and the ConfigBuilder will merge the base with the selected merge files produce the actual configuration before building the project itself. It's much like the normal publish handling with the difference that it occurs when you build the project instead.
To create a merge file, you create an xdt file for the file you would like to modify according to the following syntax.
filename.extension.merge.keyword.value.xdt
where
- filename.extension - same filename and extension as the file to modify
- keyword - optional keyword that triggers when and if a merge is performed
- value - is an argument used to control the keyword
The following keywords are supported and are executed in this order.
-
pre - will trigger a merge before any other merges are performed.
-
step - will always trigger a merge in the alphabetical order of the vaule.
-
host - This keyword will trigger a merge if the hostname of the computer that the project is compiled on matches the value argument.
Example:
web.config.merge.host.mycomputer.xdtwill trigger a merge if the hostname of the compiling machine ismycomputer. -
configuration - will trigger a merge if the current build configuration matches the value argument.
Example:
web.config.merge.configuration.debug.xdtwill trigger a merge if the project is building thedebugconfiguration. -
post - will trigger a merge after all other merges have been performed.
A folder contains the following files
- web.config
- web.config.merge.configuration.debug.xdt
- web.config.merge.configuration.release.xdt
- web.config.merge.host.devmachine1.xdt
- web.config.merge.host.devmachine2.xdt
- web.config.merge.post.xdt
- web.config.merge.pre.xdt
- web.config.merge.xdt
When project is compiled on the devmachine1 computer, using the debug configuration, merge files will be applied in the following order:
- web.config
- web.config.merge.pre.xdt
- web.config.merge.xdt
- web.config.merge.host.devmachine1.xdt
- web.config.merge.configuration.debug.xdt
- web.config.merge.post.xdt
Merging is performed using XmlTransform using xdt merge files https://msdn.microsoft.com/en-us/library/dd465326(v=vs.110).aspx
Before merging a xdt file, the merge file is scanned for variables and these are expanded inline. A variable is defined by the following syntax
$(name)
The following variables are supported
- ProjectDir - The path to the project directory
- SolutionDir - The path to the solution directory
- Configuration - The current configuration of the project
- ConfigBuilderHost - The current hostname (can be overridden, see below)
If you have an app.config file in your project (located at c:\proj\myProject\myproject.cproj) with the following contents
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<appSettings>
<add key="path" value="c:\temp\some.file"/>
</appSettings>
</configuration>
and add a merge file named app.config.merge.xdt with the following contents
<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
<appSettings>
<add key="path" value="$(ProjectDir)MyFolder\some.file" xdt:Locator="Match(key)" xdt:Transform="SetAttributes" />
</appSettings>
</configuration>
The resulting app.content after compilation will look like below
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<appSettings>
<add key="path" value="c:\proj\myProject\MyFolder\some.file"/>
</appSettings>
</configuration>
The replace mode looks for files matching the filename.replace.keyword.value.extension pattern where
- filename.extension - same filename and extension as the file to modify
- keyword - keyword that triggers if a replace is performed
- value - is an optional argument (see keywords below) used to control the keyword
It will replace the filename.extension file with the replace one that matches the keyword.
-
host - This keyword will trigger a replace if the hostname of the computer that the project is compiled on matches the value argument.
Example:
web.replace.host.mycomputer.configwill trigger a replace if the hostname of the compiling machine ismycomputer. -
default - will indicate the default replacement file that will be used if no other matching keyword is active. Note: This file must exists to trigger the replace function
Example: You would like to check in different license.config files, one for each host. You set up the following files
-
license.replace.default.config- an default license file that will be used if no other file deems suitable. -
license.replace.host.productionServer.config- a license file for the productionServer -
license.replace.host.dev1.config- a license file for the dev1 host.
When building, the script will look for the current hostname (can be overridden, see below)), and if it exists, copy the matching hostfile to the license.config file.
If no matching hostfile is found, the default file is copied to the target location.
If you would like to change the build to simulate another host, you can set the msbuild property ConfigBuilderHost either by supplying it as a parameter to the msbuild.exe
/p:ConfigBuilderHost=test
or setting it in the .csproj file
<PropertyGroup>
<ConfigBuilderHost>test</ConfigBuilderHost>
</PropertyGroup>
Meriworks.PowerShell.ConfigBuilder had a previous convention including a .base. notation in the filename. This is still supported, and documentation regarding that can be found at github.
There is a video tutorial available on youtube.
Project is licensed using the MIT License.
Package is developed by Dan Händevik, Meriworks.
- Fixed paths to PowerShell to work better in vscode/mac
- Removed dll from nuget package
- Moved to azure pipelines
- Fixed issue where file is written to even if no changes where detected on merge/replace
- Fixed issue where merge didn't trigger if .merge.xdt is the only mergefile
- Fixed support for Visual Studio 2017 #1
- Removed unused dll from nupkg file
- Fixed error with nuget install script
- Removed scripts and readme from project
- Added a new default convention that modifies the original file. Just add xdt files for automatic merge on build. The old convention is still supported.
- Minor changes in nuspec, license and documentation
- Initial release