NuGetUpdate script language

The installation process itself is scripted using the NguScript.xml file part of the NuGet package. Below is an example of a simple installation script:

<?xml version="1.0" encoding="utf-8" ?>
<Script xmlns="https://github.com/pvginkel/NuGetUpdate/Script/v1">
  <Setup>
    <Assign Variable="TargetPath">ExpandPath("%LOCAL_APPDATA%\\Convert All to MP3")</Assign>
    <Assign Variable="StartMenuPath">Config.SetupTitle</Assign>
    
    <Function Name="PrepareVariables">
      <Assign Variable="PrimaryPath">TargetPath + "\\Bin\\ConvertAllToMp3.exe"</Assign>
      <Assign Variable="ShortCutName">Config.SetupTitle + ".lnk"</Assign>
    </Function>

    <Function Name="StartConvertAllToMP3">
      <ExecShell
        FileName="PrimaryPath"
        Arguments="Config.RestartArguments"/>
    </Function>
  </Setup>

  <Install>
    <Page.Install.DestinationFolder />
    <Page.Install.StartMenu CreateOnDesktopVisible="true" IsLast="true" />
    <Page.Install.Progress>
      <InstallPackage />

      <Call Name="PrepareVariables" />

      <If Condition="CreateShortcuts">
        <Then>
          <CreateShortcut
            ShortcutFileName="ExpandPath(&quot;%STARTMENU%\\&quot; + StartMenuPath + &quot;\\&quot; + ShortCutName)"
            TargetFileName="PrimaryPath" />
        </Then>
      </If>
      <If Condition="CreateDesktopShortcuts">
        <Then>
          <CreateShortcut
            ShortcutFileName="ExpandPath(&quot;%DESKTOP%\\&quot; + ShortCutName)"
            TargetFileName="PrimaryPath" />
        </Then>
      </If>
    </Page.Install.Progress>

    <Page.Install.Finish>
      <Control.CheckBox Text="Run {{Config.SetupTitle}}">
        <Call Name="StartConvertAllToMP3" />
      </Control.CheckBox>
    </Page.Install.Finish>
  </Install>

  <Update>
    <Page.Update.Progress>
      <Call Name="PrepareVariables" />

      <InstallPackage />
    </Page.Update.Progress>

    <Page.Update.Finish>
      <Control.CheckBox Text="Run {{Config.SetupTitle}}">
        <Call Name="StartConvertAllToMP3" />
      </Control.CheckBox>
    </Page.Update.Finish>
  </Update>

  <Uninstall>
    <Page.Uninstall.Progress>
      <UninstallPackage />
    </Page.Uninstall.Progress>

    <Page.Uninstall.Finish />
  </Uninstall>
</Script>

The script file contains the following elements:

At the root is the Script element;
The Script element contains four sections:
- The Setup section is run before any of the other sections run. This section can be used to declare functions and variables;
- The Install section is run on the first installation;
- The Update section is run when an already installed application is updated;
- The Uninstall section is run when the application is uninstalled;

With in the different sections, XML elements can be added to perform certain actions. Some of these only make sense in certain sections (e.g. the Page.Install.Welcome only makes sense in the Install section). The purpose of these are described below.

Most values can be expressed as expressions. NuGetUpdate uses C# as a scripting language for such expressions using the Expressions library. See the Expressions section below for more information.

Generic elements

`Assign`

Assign a value to a variable. The name of the variable is assigned to the Variable attribute and the contents of the element specifies the expression to assign to the variable.

`Call`

Call a previously declared function with the name assigned to the Name attribute.

`CreateDirectory`

Create a new directory with the name assigned to the Path attribute.

`CreateShortcut`

Create a new shortcut. This element takes the following attributes:

ShortcutFileName: The filename of the shortcut;
TargetFileName: The target of the shortcut;
IconFileName: The path to the icon or executable containing an icon;
IconIndex: The icon index. This is useful when the IconFileName refers to an executable. Assigning 0 to this attribute takes the main icon of the executable;
StartOptions: The arguments passed to the TargetFileName when starting the application;
Description: A description added to the shortcut.

`ExecShell`

Execute a process without waiting for it to complete. This element takes the following attributes:

Verb: The verb used to start the application. See ProcessStartInfo.Verb for more information;
FileName: The file to execute;
Arguments: Arguments passed to the application to execute;
WindowStyle: The window style of the file to execute. See ProcessWindowStyle for more information.

`ExecWait`

Execute a process, waiting for it to complete. This element takes the following attributes:

FileName: The file to execute;
Arguments: Arguments passed to the application to execute;
WindowStyle: The window style of the file to execute. See ProcessWindowStyle for more information.

`Function`

Declares a new function with the name of the Name attribute.

The contents of a Function element can contain any element. However, only certain elements make sense.

Note that functions cannot take parameters. If it is necessary to pass parameters to a function, do this by assigning a variable before the function is called.

`If`

Conditionally execute some elements. The condition is specified in the Condition attribute. The If element requires at least the Then child element and can optionally contain an Else element.

`MessageBox`

Shows a message box. This element takes the following attributes:

Text: The text to show;
Buttons: One of the following values:
- OK: Show the OK button;
- OKCancel: Show an OK and Cancel button;
- AbortRetryIgnore: Show an Abort, Retry and Ignore button;
- YesNoCancel: Show a Yes, No and Cancel button;
- YesNo: Show a Yes and No button;
- RetryCancel: Show a Retry and Cancel button;
Icon: The icon to show in the message box:
- None: No icon;
- Hand: Show a hand icon;
- Question: Show a question mark icon;
- Exclamation: Show an exclamation icon;
- Asterisk: Show an asterisk icon;
- Stop: Show a stop icon;
- Error: Show an error icon;
- Warning: Show a warning icon;
- Information: Show an information icon;
Result: Optionally the name of a variable to assign the result to. This can be used to find out whether the user e.g. clicked a Yes or No button.

Installation

The following elements can be used to control installation. These are useful in the Page.Install.Progress, Page.Update.Progress and Page.Uninstall.Progress pages.

`Message`

Show the expression contents of the element as progress.

`InstallPackage`

Install or update the NuGet package.

`UninstallPackage`

Uninstall the NuGet package.

Controls

The following elements can be used to present controls on the completion pages. These are useful in the Page.Install.Finish, Page.Update.Finish and Page.Uninstall.Finish pages.

`Control.CheckBox`

Show a checkbox with the contents of the Text attribute as its label. If the user checks the checkbox, the child elements of the Control.CheckBox element are executed when the user finishes the installer.

`Control.Label`

Show a label with the contents of the element as its label.

`Control.Link`

Show a link with the contents of the Text attribute as its label. If the user clicks the link, the child elements of the Control.Link element are executed.

Setup pages

Setups are build out of a number of pages. What pages can be shown depend on the mode in which the setup is run.

There are three modes in which the setup can run:

When the application is first installed, elements in the Install element are executed and pages starting with Page.Install. can be shown;
When an already installed application is updated, elements in the Update element are executed and pages starting with Page.Update. can be shown;
When the application is uninstalled, elements in the Uninstall element are executed and pages starting with Page.Uninstall. can be shown.

Note that all pages are optional. However, if no .Progress page is added, nothing will be installed.

`Page.Install.Welcome`

Show a generic welcome page.

This element takes the following attributes:

IsLast: Whether to show a Next or Install button.

`Page.Install.License`

Show a license. The contents of the element is displayed as the license and the user needs to click an I Agree button before he can continue with the installation.

`Page.Install.DestinationFolder`

Ask for a destination folder. The destination folder is taken from the TargetFolder script variable and needs to be set before this page is shown.

This element takes the following attributes:

Enabled: Whether the user can change the destination folder;
IsLast: Whether to show a Next or Install button.

`Page.Install.StartMenu`

Ask for start menu items to be created.

This element takes the following attributes:

Enabled: Whether the user can change the settings;
CreateStartMenuVisible: Whether the option to create start menu items is visible. The result of this option is set to the CreateShortcuts script variable;
CreateOnDesktopVisible: Whether the option to create a desktop shortcut is visible. The result of this option is set to the CreateDesktopShortcuts script variable;
IsLast: Whether to show a Next or Install button.

The name of the start menu path is taken from the StartMenuPath script variable which needs to be set before this page is shown.

`Page.Install.Progress`

Show progress to perform the actual installation. The contents of this element is executed to perform the installation. Note that this element should at least contain exactly one InstallPackage element.

This element takes a ProgressVisible attribute to indicate whether or not progress should be displayed to the user.

`Page.Install.Finish`

Show a completion page. This page can contain controls. See the section on controls above.

`Page.Update.Welcome`

Show a generic welcome page.

`Page.Update.Progress`

Show progress to perform the actual installation. The contents of this element is executed to perform the installation. Note that this element should at least contain exactly one InstallPackage element.

This element takes a ProgressVisible attribute to indicate whether or not progress should be displayed to the user.

`Page.Update.Finish`

Show a completion page. This page can contain controls. See the section on controls above.

`Page.Uninstall.Welcome`

Show a generic welcome page.

`Page.Uninstall.Progress`

Show progress to perform the actual installation. The contents of this element is executed to perform the installation. Note that this element should at least contain exactly one UninstallPackage element.

This element takes a ProgressVisible attribute to indicate whether or not progress should be displayed to the user.

`Page.Uninstall.Finish`

Show a completion page. This page can contain controls. See the section on controls above.

Expressions

Most values can be expressed as expressions. NuGetUpdate uses C# as a scripting language for such expressions using the Expressions library.

As an example, a variable can be assigned as follows:

<Assign Variable="MyVariable">2 * 5</Assign>

This will execute 2 * 5 as a C# expression and assign 10 to the variable named MyVariable.

Functions

The following functions are available to be used in expressions.

`ExpandPath`

The ExpandPath function can be used to parse replacement variables and expand them into full directories.

The names of the replacement variables are taken from the CSIDL enumeration, with the CSIDL_ prefix removed.

The following example is used to assign a target path as part of the setup:

<Assign Variable="TargetPath">ExpandPath("%LOCAL_APPDATA%\\Convert All to MP3")</Assign>

This example contains the LOCAL_APPDATA replacement variable, which refers to the CSIDL_LOCAL_APPDATA CSIDL value.

.NET framework methods

All static methods from the following classes are also available:

Math;
Convert;
Path;
[File][https://msdn.microsoft.com/en-us/library/system.io.file(v=vs.110).aspx];
DateTime.

This means that e.g. the following example takes the filename of the TargetPath and assigns it to a FileName attribute:

<Assign Variable="FileName">GetFileName(TargetPath)</Assign>

Note that the Path. prefix is missing as all static methods are imported into the global namespace.

Variables

A number of script variables have a special meaning:

TargetPath: The installation destination and needs to be set before the package can be installed;
StartMenuPath: The path to the start menu items and needs to be set before the start menu items can be created;
CreateShortcuts: Whether the user choose to create start menu items;
CreateDesktopShortcuts: Whether the user choose to create a desktop shortcut.

Constants

The following constants are available from the script:

Config.PackageFolder: The folder where the NuGet package was extracted to;
Config.PackageCode: The NuGet package ID;
Config.SetupTitle: The setup title passed when the automatic installer was created;
Config.PackageVersion: The version of the NuGet package being installed;
Config.InstalledVersion: The currently installed version of the application;
Config.RestartArguments: If the package is being automatically updated, restart arguments can be passed to the installer. These can then be used to restart the application after the automatic update completes.

NuGetUpdate script language

Generic elements

Assign

Call

CreateDirectory

CreateShortcut

ExecShell

ExecWait

Function

If

MessageBox

Installation

Message

InstallPackage

UninstallPackage

Controls

Control.CheckBox

Control.Label

Control.Link

Setup pages

Page.Install.Welcome

Page.Install.License

Page.Install.DestinationFolder

Page.Install.StartMenu

Page.Install.Progress

Page.Install.Finish

Page.Update.Welcome

Page.Update.Progress

Page.Update.Finish

Page.Uninstall.Welcome

Page.Uninstall.Progress

Page.Uninstall.Finish

Functions

ExpandPath

.NET framework methods

Variables

Constants

Clone this wiki locally

`Assign`

`Call`

`CreateDirectory`

`CreateShortcut`

`ExecShell`

`ExecWait`

`Function`

`If`

`MessageBox`

`Message`

`InstallPackage`

`UninstallPackage`

`Control.CheckBox`

`Control.Label`

`Control.Link`

`Page.Install.Welcome`

`Page.Install.License`

`Page.Install.DestinationFolder`

`Page.Install.StartMenu`

`Page.Install.Progress`

`Page.Install.Finish`

`Page.Update.Welcome`

`Page.Update.Progress`

`Page.Update.Finish`

`Page.Uninstall.Welcome`

`Page.Uninstall.Progress`

`Page.Uninstall.Finish`

`ExpandPath`