MainBoss Advanced, Version 4.1.1:
Updating an Existing ClickOnce Installation

ClickOnce is simple to use but complicated to set up.
It requires an IT department with a high degree of technical sophistication.

Microsoft provides a good deal of information about ClickOnce at http://msdn.microsoft.com/library/wh45kb66.aspx.

The web page you are reading now is for people who have installed an earlier version of ClickOnce MainBoss. If you are installing ClickOnce MainBoss for the first time, click here for instructions.

Introductory Notes

ClickOnce users go to a web page to access ClickOnce. Typically, you will have a customized web page for this purpose. You may be able to re-use your existing web page with this new version of ClickOnce.

If you don't remember where your ClickOnce directory is: Start your IIS manager (by running inetmgr using "Run" in the Windows Start Menu). In the left hand panel, keep expanding entries until you find the one for the web site that your ClickOnce uses. Right-click on the entry for that site and click either "Explore" or "Properties" (different versions of IIS manager have different menu entries). The resulting information will tell you where your current ClickOnce directory is.

Installing the new ClickOnce software:

  1. Move the contents of your existing ClickOnce directory to some (temporary) holding directory.
  2. to obtain a ZIP file named Install.MainBoss.ClickOnce.4.1.1.3.zip containing the files you need for ClickOnce deployment.
  3. Extract the contents of the ZIP file into your existing MainBoss ClickOnce directory.
  4. Copy your old web page file (typically an HTML file) from the holding directory back to the ClickOnce directory.
  5. The new ClickOnce directory will have a file named setup.exe. This file attempts to install the prerequisite software needed by MainBoss, including .NET 4.6, Report Viewer 2015, and the "CLR Types" add-on to SQL Server. We recommend that you execute the file to make sure that your system has all the needed software. When the prerequisites are installed, setup.exe then installs a ClickOnce version of MainBoss (if necessary). Thus, executing setup.exe will let you see if ClickOnce is installed correctly.

Once you are satisfied that ClickOnce is working, you can delete the holding directory that contains your old ClickOnce files.

Online vs. Offline Builds

There are two builds of MainBoss for ClickOnce:

  1. The Online build is designed for people who always intend to launch MainBoss from the ClickOnce web page. It does not create an entry for MainBoss in the Windows "Start" menu. (You can still start the program without a web connection by using the Windows "Search" box or by creating your own shortcut to the file containing the program.)
  2. The Offline build is designed for people who may frequently work without an active Internet connection. When you first install the software, it creates an entry in the Windows "Start" menu which you can then use to start the program instead of going through a web page. (You should still go through the web page occasionally, because the web interface is designed to update your software automatically whenever a new version is released.)

For a more detailed explanation of the two types of builds, see Microsoft's web page here, particularly the discussion of the Install attribute.

When you have installed ClickOnce (as described in the preceding section), you will notice that the folder contains the executable files:

mainbossOnline.application
The Online build
mainbossOffline.application
The Offline build
mainboss.application
A file that can contain whichever build you think ought to be standard for your users; by default, this is the Online build

A user can't switch easily from one build to another. Therefore, each user should choose one build (or IT administrators should dictate one build) and stick with that one. If someone really needs to switch builds, see Switching Builds below.

Before MainBoss 3.4 Update 1, the only build of MainBoss was the Offline build. For this reason, you may wish to arrange that most users continue using the Offline build. Users who want to switch to the Online build must use the Windows Control Panel to uninstall the old version; they can then start using the Online build (which will install itself the first time you launch the application).

Prerequisite Software

In order to run MainBoss Advanced using ClickOnce, the following software must be installed on the user's system:

If a user attempts to run MainBoss through the ClickOnce web page without having the appropriate prerequisites, MainBoss will display the message "System update required".

There are two ways to ensure that user systems have the prerequisite software. You could simply install the software by hand on any system where someone will be running MainBoss. However, this can only be done by someone with Windows Administrator privileges. Alternatively, you could use Windows Server Manager to activage Windows Server Update Services. To do so, start Windows Server Manager on your Windows Server system and use "Add Role" to add the role "Windows Server Update Services".

Once you add this role, you can update other Windows systems on the network using the normal Windows Update software (provided you have Windows Administrator privileges on the network server computer). In particular, you can add the prerequisite packages (listed above) to any computer you choose.

Browser: In order to use ClickOnce, users must connect to your ClickOnce web page using Internet Explorer, or else they must download an appropriate plug-in (e.g. for Firefox or for Google Chrome).

Caveats about ClickOnce

If several people use ClickOnce to run MainBoss on the same computer, the MainBoss software will be installed once for each such user. For example, if three people use the same computer at different times and all of them run MainBoss, the MainBoss software will be installed separately for each person.

People who invoke MainBoss through ClickOnce will not be able to specify command line arguments to the MainBoss software. They will also not be able to run the MBUtility program.

Changing the ClickOnce Location

When installing a new version of ClickOnce, you may decide that it's a good time to change the software's location. If so, make sure you tell your users to start ClickOnce at least once through the web page rather than just using the entries in their Start menus.

Why? Because if users start ClickOnce through their Start menus, Windows looks for the software in the known location. If the software can't be found (because it's been moved), Windows just uses the local version of MainBoss without issuing a message. This local version will be the old version of MainBoss, and will continue to be the old one until the user, at least once, executes the software through the web page and obtains the new software.

Note that this is only a problem if you move the software location. If you install a new version of MainBoss in the same location as the old one, Windows will look at that location, see that there's a new version, and install it on the user's computer.

Switching Builds

As noted previously, there are two builds of MainBoss for ClickOnce: an Online build and an Offline build. Once a user has run one for the first time, switching to the other requires some work:

Switching from Offline to Online:
You must use the standard Windows Control Panel to uninstall the Offline build (in the usual way you uninstall any software package). You can then run the Online version; it will install itself and you will use the Online version from then on.

If you try to run the Online version when you have the Offline installed, you will receive an error message that says Application cannot be started. Contact the application vendor. The Details button will say something like

System.Deployment.Application.DeploymentException (SubscriptionState)
Cannot make this application an online application because the previous version is installed.
To install this application uninstall the previous version, or mark this application as installed.

Switching from Online to Offline:
To do this, you must clear the ClickOnce installed cache. If you have the mage command (which is part of the Windows SDK), you can run it from a command window with the -cc (clear cache) option. Once you have run the command, you can use the Offline build.

If you do not have the mage command on your computer, open a command window and run the following command.

   rundll32 dfshim CleanOnlineAppCache

Once you have run this command, you can use the Offline build.

If you have the Online build installed and try to run the Offline build without clearing the cache, you get the message: You cannot start application MainBoss Advanced from this location because it is already installed from a different location.

Launching ClickOnce MainBoss without a Browser

You can launch a ClickOnce version of MainBoss without using a browser by using the following command line: 

C:\Windows\System32\rundll32.exe dfshim ShOpenVerbApplication URL

where URL is the URL of the file that contains the application you want to run. For example, you might have something like this: 

C:\Windows\System32\rundll32.exe dfshim ShOpenVerbApplication http://ourcompany.com/mainboss/mainboss.application

You can use this command line in a command prompt window or in the command line associated with a shortcut icon.