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>] [/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*.
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)
   

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)
   

Miscellaneous
/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


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

*FixFalse

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)