bright, fresh software
Downloads  |  Buy

Building from Commandline

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.

Return codes

The wyBuild Commandline Builder returns 0 on success and 1 on error.

Building updates

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"

Adding new versions

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.

New Versions XML Format

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>

Adding files

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>

Available destination directories

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
  • %ProgramFiles%\Common Files on 32-bit Windows
  • %ProgramFiles(x86)%\Common Files on 64-bit Windows
commonfilesx64 The Common Files directory for 64-bit
  • %ProgramFiles%\Common Files on 64-bit Windows
  • The update will fail to install on 32-bit Windows
sys32 The system32 directory for 32-bit
  • C:\Windows\System32 on 32-bit Windows
  • C:\Windows\SysWOW64 on 64-bit Windows
sys32x64 The system32 directory for 64-bit
  • C:\Windows\System32 on 64-bit Windows
  • The update will fail to install on 32-bit Windows
root The root Windows drive (e.g. C:\)
temp The temporary directory.

Adding a folder and its contents

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>
...

Adding shortcuts

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
  • minimized
  • maximized
If this attribute is absent the default value is normal.
comment The comment string of the shortcut. This is the tooltip text the user sees when they hover their mouse over the shortcut.

Removing & overwriting existing versions

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

Executing files

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: Start the executable the same elevation level as wyUpdate.
  • not: Start as a non-elevated process (the same elevation level as the Windows Shell).
  • elevated: Start as an elevated process.
If this attribute is absent the default value is same.
execute The "execute" attribute is required if you want to execute files. It can have one of 2 possible values:
  • before
  • after
Note: You can only execute a file before an update if the file to be executed is in the temporary directory.
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
  • minimized
  • maximized
  • hidden
If this attribute is absent the default value is 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=&quot;%basedir%\Important Stuff&quot;" />
</Files>
...

COM registration

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>
...

Update Actions: Starting and Stopping Services

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:
  • stopservice
  • startservice
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 />

Registry

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:
  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_CONFIG
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS
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:
  • REG_SZ
  • REG_EXPAND_SZ
  • REG_MULTI_SZ
  • REG_BINARY
  • REG_DWORD
  • REG_QWORD
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 />

Building wyUpdate

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"

Bringing it altogether

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.).