An Upgrade Action is an action the upgrader runs during upgrading. This is a guide on how to create a custom upgrade action.

Getting Started

  1. First Create a new Visual Studio project. Add the following reference your project CartellaInstallerCommon.

  2. Create a new class and use CartellaInstallerCommon.

  3. Derive your class from the interface IInstallAction.

IInstallAction Reference

  • UpdateProgress: This is a callback to update the progress bar by the number of steps specfied. If the steps are negative it will move the progress bar back by that many steps.

  • InstallSteps: This specifies the number of "steps" that this action requires. This corresponds to how many times the progress bar should be progressed during this action.

    Important

    You must tell the installer to upgrade its progress yourself. You can do this by calling the UpdateProgress delegate in the Install method and also call it that number of times but with negative parameters for Rollback.

  • Weight: This specifies how many steps the prgress bar should updated for every call to UpdateProgress

    Important

    This is not yet implemented in the installer. It is highly recommended that you set Weight to 1 by adding the following code to your project.

    CopyC#
    public int Weight
    {
        get;
        set;
    }
    
    public <Your Class Name>()
    {
        this.Weight = 1;
    }
  • TaskName: This is the friendly name for this task that is displayed to the user.

  • RunThisAction: This returns whether this action can be ran during this upgrade.

  • Install: This does the install action. It returns true if succeded and false if it failed. If it failed it will start rolling back the installation. If it failed you need to specify an error message. This will be displayed to the user as the reason it failed.

  • RollBack: This does the rollback for this action. It should "undo" everything that the install action does. It returns true if succeded and false if it failed. If it failed it will cancel the rollback. If it failed you need to specify an error message. This will be displayed to the user as the reason it failed.

Code Example

Here is a fully functional example.

CopyC#
public class PreCustomTest : IInstallAction
{
    //Callback to update the progress bar
    public event UpdateProgressBar UpdateProgress;

    //THe number of steps that are in this installation action.
    public int InstallSteps(InstallerData data)
    {
        return 1;
    }

    public int Weight
    {
        get;
        set;
    }

    //Friendly name to be displayed to the user while the task is going on
    public string TaskName
    {
        get { return "Pre Custom Install Test"; }
    }

    //Whether we can run this action now
    public bool RunThisAction(InstallerData data)
    {
        return true;
    }

    public PreCustomTest()
    {
        this.Weight = 1;
    }

    //Logic for doing the installation.
    public bool Install(InstallerData data, InstallLogger log, out string error)
    {
        error = "";
        //update the progress bar
        if (UpdateProgress != null)
            UpdateProgress(this.Weight);
        System.Windows.Forms.MessageBox.Show("Pre Custom Test Install");

        //Is succesful
        return true;
    }

    //LOgic for doing a roll back of the install action
    public bool RollBack(InstallerData data, InstallLogger log, out string error)
    {
        error = "";

        if (UpdateProgress != null)
            UpdateProgress(-1 * this.Weight);

        System.Windows.Forms.MessageBox.Show("Pre Custom Test Install");

        return true;
    }
}