MainBoss Advanced, Version 3.4.1:
Installing ClickOnce Deployment for the First Time

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.

Note that this web page is for people who are installing ClickOnce for the first time. If you have an existing ClickOnce installation, click here for installation instructions.

Setting Up ClickOnce for the First Time

To set up ClickOnce deployment, follow these steps:

  1. Create a virtual directory on your organization's web site to contain all the files that MainBoss needs for ClickOnce deployment. We will call this the MainBoss ClickOnce directory. (If you have installed a previous version of ClickOnce, you can use the same directory after you've moved out all the old contents.)
  2. to obtain a ZIP file named Install.ClickOnce.3.4.1.20.zip containing the files you need for ClickOnce deployment.
  3. Extract the contents of the ZIP file into the MainBoss ClickOnce directory (i.e. the virtual directory created in Step 2 above).
  4. In the MainBoss ClickOnce directory, create a web page with a link to the file mainboss.application. Users should click on the mainboss.application link whenever they want to start MainBoss.

The files extracted in Step 4 above include a file named default.htm which you can modify to create the needed web page. Alternatively, you can write your own web page from scratch.

Online vs. Offline Builds

There are two builds of the ClickOnce version of MainBoss:

  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.

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.

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