Home What's New Properties Command Line Managing Properties MSI Integration Samples Roadmap


Command Line

Usage: XmlPreprocess.exe [@argfile] [/input|i:<value>] [/output|o:<value>]
       [/settings|s:<value>] [/define|d:<value>] [/clean|c] [/quiet|q] [/validate|v]
       [/validateSettingsExist|vs] [/validateXmlWellFormed|vx] [/fixFalse|f]
       [/environment|e:<value>] [/spreadsheet|x:<value>] [/database|db:<value>]
       [/custom|cx:<value>] [/list|l] [/property|p:<value>] [/delimiters|t:<value>]
       [/environmentRow|er:<value>] [/firstValueRow|vr:<value>]
       [/settingNameCol|nc:<value>] [/defaultValueCol|dc:<value>]
       [/environmentFile|ef:<value>] [/noDirectives|n] [/tokenStart|ts:<value>]
       [/tokenEnd|te:<value>] [/countReportFile|cr:] [/noLogo] [/help|?|h] [/version|v]

Argument   Description

Inputs / Outputs

/input:<value> /i Location of input file. You can specify multiple /i parameters (ex: /i:f1 /i:f2), or pass multiple files with semicolon delimiter (/i:f1;f2). You can pass wildcards such as /i:*.config to preprocess all *.config files in a single directory. (Wildcards introduced in 2.0.15)
/output:<value> /o Location of output file. If omitted, input file will be overwritten. You can specify multiple /o parameters(ex: /o:f1 /o:f2), or pass multiple files with semicolon delimiter (/o:f1;f2). If multiple files are passed, they must correspond to the /i parameters, this should not be used in conjunction with wildcards.

Defining Properties

/settings:<value> /s Location of XML settings file with the format: <settings><property name="a">1</property></settings>. You can specify multiple /s parameters (ex: /s:f1/s:f2), or pass multiple files with semicolon delimiter (/s:f1;f2).
/define:<value> /d Properties to define, these will override properties read from the file with the same name. (example: /d:a=1 /d:b=2 /d:c=3)
/environment:<value> /e Name of environment column to use if one of the spreadsheet formats was passed (/x, /db/ cx). If not passed, and /quiet was not passed, the user will be prompted for which environment to use.
/spreadsheet:<value> /x Location of spreadsheet file, must also specify environment. Valid formats are XML Spreadsheet 2003 (*.xml), or Excel 2003 or older (*.xls). You can specify multiple /x parameters (ex: /x:f1 /x:f2), or pass multiple files with semicolon delimiter (/x:f1;f2).
/database:<value> /db Connection string to database, must also specify environment. You can specify multiple /db parameters (ex: /db:f1 /db:f2) (introduced in 2.0.15)
/custom:<value> /cx Command line for custom data source, must also specify environment. You can specify multiple /cx parameters (ex: /cx:f1 /cx:f2) (introduced in 2.0.15)

Controlling the Output

/fixFalse /f Do not use the value of "False" to undefine settings. (instead use "#undef") SEE BELOW*.
Starting with version 2.0.18, it is no longer necessary to pass this switch, the preprocessor will act as if you passed it unless you use the legacy executable (xmlpreprocess-nofixfalse.exe) which maintains the old behavior.
Note: To avoid legacy behavior that can be difficult to track down when dealing with “false” values you should always pass /f just to be safe. This behavior was not corrected in order to maintain backward compatibility with the original version.
/clean /c Clean output file of all preprocessor markup comments. Keeping these comments in allows the file to be preprocessed multiple times.
/quiet /q Quiet mode, do not prompt for missing settings files or environments, just exit with an error if anything is missing.
/list /l List all environment names (or property values when used with /p) from a spreadsheet file to the console. Must be combined with a single /x parameter.
/property:<value> /p Name of property to output to the console.
/environmentFile:<value> /ef File in which to save the name of the chosen environment. Passing a value indicates you wish to only prompt for environment and immediately exit, Must be combined with /x (introduced in Beta 8)
/countReportFile:<value> /cr File in which to write property usage counts, will be written in CSV format. (introduced n 2.0.16)

Validating the Output

/validate /v Validate all, turns on /validateSettingsExist, and /validateXmlWellFormed
/validateSettingsExist /vs Validate settings exist, return an error if any substitution settings are undefined. (introduced in 2.0.11)
/validateXmlWellFormed /vs Validate resulting XML is well-formed, return an error if the result document is not well-formed. (introduced in 2.0.11)

Adjusting for different Inputs

/noDirectives /n No preprocessor directives needed. Just globally replace all macros. (introduced in RC2)
/delimiters:<value> /t Delimiter characters to use to split a compound property value into multiple lines, used in conjunction with /p.
/environmentRow:<value> /er Row number (1 based) of environment name in input spreadsheet. (Default is "2")
/firstValueRow:<value> /vr Row number (1 based) of first value in input spreadsheet. (Default is "7")
/settingNameCol:<value> /nc Column index (1 based) of setting names in input spreadsheet. (Default is "1")
/defaultValueCol:<value> /dc Column index of default values in input spreadsheet. (Default is "2")
/tokenStart:<value> /ts The starting token (default is "${") (introduced in 2.0.15)
/tokenEnd:<value> /te The ending token (default is "}") (introduced in 2.0.15)


/noLogo   Do not output logo.
@argfile   Read arguments from a file.
/help   Show usage.
/version   Show version.

Command Line Examples:

Here are some examples of how to invoke the XmlPreprocess utility from the command line.

XmlPreprocess.exe /f /i web.config /s dt_settings.xml /d:installer /d:debug /d:trace=4

This will process a file named web.config, and write it out to the same place, using dt_settings.xml for it's settings. It also defines three additional properties: installer="TRUE", debug="TRUE" and trace="4" which will override any properties of the same name found in the settings file.

XmlPreprocess.exe /f /i in\web.config /o out\out-web-prod.config /d PRODUCTION=TRUE /d DEPLOYDIR=%~dp0 /d METADATADB=productionserver /d SERVERPREFIX=FOO

This will process a file named in\web.config, and write it out to out\out-web-prod.config with no settings file. It defines four additional properties: production="TRUE", DEPLOYDIR="<current directory when run from batch file>" etc. Note that the colon on all parameters is optional.

Here is an example using the spreadsheet import feature:

XmlPreprocess.exe /nologo /f /i FileToProcess.config /x MySpreadsheet.xml /e Production

  • /i = input file to process
  • /x = name of settings file saved in SpreadsheetML
  • /e = environment column to use

This eliminates the need for the individual settings files from ever having to be written out to disk. XmlPreprocess will just consume it directly.


This table shows the resulting value for the various combinations of property value and the /FixFalse switch

Property Value-> true false "false" #undef
pass /f true false false (undefined)
no /f true (undefined) false (undefined)

Last edited Jul 30, 2013 at 6:38 PM by lorenh, version 23


No comments yet.