In addition to the easy to use drag-and-drop interface, wyBuild offers a commandline interface to automate your update creation. With this commandline interface you can build your updates, add new versions using an XML file, build wyUpdate, and upload your updates.
The wyBuild Commandline Builder is the "wybuild.cmd.exe" in the wyBuild installation folder. Here are the available commandline switches:
| Commandline switch | Description |
|---|---|
/bu |
Build the updates & server files for your project. |
/bwu |
Build wyUpdate for the latest version of your app. |
/upload |
Upload the most recently built updates. |
-vs="<start version>" |
The start version - the version of your product that you're building from. If this switch is not present then the update is built from the oldest available version. |
-ve="<end version>" |
The end version - the version of your product that you're building to. If this switch is not present then the update is built to the newest available version. |
-add="<xml filename>" |
Add additional versions to your product using the XML specification below. |
-catchall="<true or false>" |
If this "catchall" commandline argument is present you can override the setting for the "Create catch-all update for corrupt installations" option in your project's properties. Otherwise the value you have in your project is used. |
The wyBuild Commandline Builder returns 0 on success and 1 on error.
Building updates from commandline is simply a matter of supplying the version ranges of the update you want to build:
wybuild.cmd.exe "C:\YourProject.wyp" /bu
Or you can specify the version ranges you want to cover with the update:
wybuild.cmd.exe "C:\YourProject.wyp" /bu -vs="1.0" -ve="1.1"
You can add new versions to your wyBuild project by using either the "/bu" or "/bwu" commandline switch along with the "-add" switch. For example:
wybuild.cmd.exe "C:\YourProject.wyp" /bu -vs="1.0" -ve="1.2" -add="newversions.xml"
This adds the new version using the xml specification (see below) while also building the updates for your product in the range from v1.0 to v1.2.
The format of the XML file required to add new versions by commandline is rather simple. Below is an example:
<?xml version="1.0" encoding="utf-8"?>
<Versions>
<AddVersion>
<Version>1.2</Version>
<Changes>Some very very cool stuff</Changes>
<InheritPrevRegistry />
<InheritPrevActions />
<Files dir="basedir">
<File source="C:\YourProduct\1.2\YourProduct.exe" />
<File source="C:\YourProduct\1.2\Awesome.dll">NewName.dll</File>
<Folder source="C:\YourProduct\1.2\Lots of files" insideonly="true" />
<Files dir="Sub folder">
<File source="C:\YourProduct\1.2\Sub folder\File.dat" />
</Files>
</Files>
<Files dir="sys32\YourProduct">
<File source="C:\YourProduct\1.2\AnotherFile.dll" />
</Files>
</AddVersion>
</Versions>
To add files and folders there are 2 elements that you need to use: <Files> and <File>. The <Files> element defines the destination folder and contains all <File> and <Folder> elements:
<AddVersion>
...
<Files dir="basedir">
<File source="C:\YourProduct\1.2\YourProduct.exe" />
<Folder source="C:\Folder to add" />
...
</Files>
...
</AddVersion>
You can also specify destination subfolder by nesting <Files> elements:
<Files dir="basedir">
<File source="C:\YourProduct\1.2\YourProduct.exe" />
<Folder source="C:\Folder to add" />
...
<Files dir="A subfolder\another">
<File source="C:\a file.exe" />
...
</Files>
</Files>
If you want to add a file to wyBuild, but want to use a filename different from the source filename, then use the following <File> element format:
<File source="C:\YourProduct\1.2\Old filename.exe">New filename.exe</File>
The <Files> blocks (<Files dir="basedir">...</Files>) have a dir attribute which corresponds to destination directory:
| Directory Abbreviation | Destination |
|---|---|
| basedir | The directory where your program is installed (e.g. C:\Program Files\YourProgram) |
| commdesktop | The common desktop. |
| cudesktop | The current user's desktop. |
| commstartmenu | The common start menu. |
| custartmenu | The current user's start menu. |
| commappdata | The common application data directory. |
| currappdata | The current user's roaming application data directory (e.g. C:\Users\User Name\AppData\Roaming) |
| currlocalappdata | The current user's local application data directory (e.g. C:\Users\User Name\AppData\Local) |
| commonfilesx86 | The Common Files directory for 32-bit
|
| commonfilesx64 | The Common Files directory for 64-bit
|
| sys32 | The system32 directory for 32-bit
|
| sys32x64 | The system32 directory for 64-bit
|
| root | The root Windows drive (e.g. C:\) |
| temp | The temporary directory. |
To recursively add a folder along with all files and folders within it simply use the <Folder> element. For instance, to add the folder "C:\Folder to add" along with all of its contents add the following Folder element:
...
<Files dir="basedir">
<Folder source="C:\Folder to add" />
...
</Files>
...
Let's say you want to add all the files and folders within a particular folder, but not the folder itself. You can do this by adding the insideonly="true" attribute:
...
<Files dir="basedir">
<Folder source="C:\Folder to add" insideonly="true" />
...
</Files>
...
To add a shortcut simply use the <Shortcut> element. Here's an example shortcut named "Your Awesome App.lnk" that will be added to the desktop that references the "Your App.exe" file in the "Your program's folder" directory:
...
<Files dir="commdesktop">
<Shortcut source="%basedir%\Your App.exe">Your Awesome App.lnk</Shortcut>
...
</Files>
...
| Shortcut Attribute | Description |
|---|---|
| source | The location the file you're making the shortcut to. Use the %basedir% variable to reference files in the "Your program's folder" in wyBuild. That is, wherever wyUpdate.exe is sitting on your user's computer. |
| startin | The start path (or current directory) of the shortcut. If this attribute is absent the default value is the path of the "source" attribute. |
| run | The "run" attribute lets you set how the executable is started. It can have one of 3 possible values:
normal. |
| comment | The comment string of the shortcut. This is the tooltip text the user sees when they hover their mouse over the shortcut. |
You can also remove and overwrite existing versions in your wyBuild project file. To overwrite an existing version (if it exists), add the overwrite="true" attribute to the <AddVersion> element:
<?xml version="1.0" encoding="utf-8"?>
<Versions>
<AddVersion overwrite="true">
<Version>1.2</Version>
...
</AddVersion>
</Versions>
You can also explicitly remove versions:
<?xml version="1.0" encoding="utf-8"?>
<Versions>
<RemoveVersion ver="1.1" />
<AddVersion>
<Version>1.2</Version>
...
</AddVersion>
</Versions>
If you would like wyBuild to show an error if you try to remove a version that doesn't exist then use the hardfail="true" attribute:
<RemoveVersion ver="1.1" hardfail="true" />
As shown in the "Executing files in your update" article you can execute *.exe, *.bat, *.cmd, and *.msi files either before or after you've installed your update.
| File Attribute | Description |
|---|---|
| elevation | The "elevation" attribute lets you set the elevation level of the executable to be started. It can have one of 3 possible values:
same. |
| execute | The "execute" attribute is required if you want to execute files. It can have one of 2 possible values:
|
| waitforexit | Set this attribute to true if you want wyUpdate to wait for the program to finish before continuing with the update. Set it to false otherwise.If this attribute is absent the default value is true. |
| startstyle | The "startstyle" attribute lets you set how the executable is started. It can have one of 4 possible values:
normal. |
| commandline | Any additional commandline options you want to pass to your executable. |
| retrollback | Set this attribute to true if you want wyUpdate to rollback the update if the exit code of the file was non-zero. Set it to false otherwise.If this attribute is absent the default value is true. Also, the waitforexit attribute must be set to true for the update to rollback on non-zero return code. |
| retexcept | A comma separated list of non-zero return codes that won't cause wyUpdate to rollback the update. |
Here's a simple example showing a program being executed before the update takes place:
...
<Files dir="temp">
<File source="C:\YourProduct\1.2\SpecialFunctions.bat" execute="before" startstyle="hidden" commandline="--folder="%basedir%\Important Stuff"" />
</Files>
...
As shown in How to register / unregister COM dlls you can register COM *.dll and *.ocx files. Simply add the comreg="true" attribute to a file. For example:
...
<Files dir="basedir">
<File source="C:\YourProduct\1.2\yourcom.dll" comreg="true" />
</Files>
...
As shown in Starting and Stopping Windows Services you can stop services before an update and start services after an update.
| Action Attribute | Description |
|---|---|
| type | The "type" attribute is required. There are currently 2 available update action types:
|
| service | The service to start or stop. |
The following update actions will stop the service "Your Service Name" before the update, and start it again after the update:
...
<Actions>
<Action type="stopservice" service="Your Service Name" />
<Action type="startservice" service="Your Service Name" />
</Actions>
...
You can also specify arguments that will be passed to your service when it's started. Each argument is on a separate line:
...
<Actions>
<Action type="startservice" service="Your Service Name">First argument
Second argument
Third argument
etc...</Action>
</Actions>
...
If you would just like to copy all of the update actions used in the previous version, then in leiu of a new Actions block, add the following element:
<InheritPrevActions />
You can also add registry changes (create & remove values and create & remove keys).
...
<Registry>
<Create base="HKEY_LOCAL_MACHINE" subkey="SOFTWARE\%product%" valname="a value" valtype="REG_SZ" valdata="the data" wow64="true" />
<Remove base="HKEY_LOCAL_MACHINE" subkey="SOFTWARE\%product%" valname="old value to remove" />
</Registry>
...
Below are the possible atributes to the <Create> and <Remove> elements:
| Create/Remove Attribute | Description |
|---|---|
| base | This is the base key you'll be accessing. It can have one of 5 possible values:
|
| subkey | The subkey you'll be working with (e.g. "SOFTWARE\%product%"). |
| wow64 | Set this attribute to true if you're modifying the 32-bit registry (e.g. regular registry on x86 Windows, the WoW64 node on x64 Windows) and set this to false if you're modifying the regular registry on both platforms. Set it to otherwise.If this attribute is absent the default value is false. |
| valname | The name of the value to create or remove. If this attribute is missing, and the registry change will either be creating or removing the subkey (rather than a value). |
| valtype | This attribute lets you specify the type of the value data. It can have one of 6 possible values:
|
| valdata | The value of the data. If the valtype attribute is REG_BINARY then this should be a filename (the contents of which will be inserted into the registry). |
If you would just like to copy all of the registry modifications used in the previous version, then in leiu of a new Registry block, add the following element:
<InheritPrevRegistry />
To build wyUpdate.exe and client.wyc for the latest version of your software simply use the "/bwu" commandline argument:
wybuild.cmd.exe "C:\YourProject.wyp" /bwu
Or you can specify the version you want to create wyUpdate for:
wybuild.cmd.exe "C:\YourProject.wyp" /bwu -ve="1.1"
You can also do everything in one step:
wybuild.cmd.exe "C:\YourProject.wyp" /bwu /bu /upload -vs="1.0" -ve="1.2" -add="newversions.xml"
In this example we add a new version, create wyUpdate, and build the updates from 1.0 through 1.2 and then upload them to the sites you added to the "upload page" in wyBuild (FTP, SFTP servers, Amazon S3, etc.).