Deploying Separate User/Site Configurations with ClickOnce

Microsoft's ClickOnce framework is a powerful tool for deploying and updating Windows forms applications. Learn how to deploy separate application configurations via two methods: installing and updating from different locations, and using URL parameters.

ClickOnce in .NET is a technology that allows you to marry the rich user experience of Windows Forms applications with the deployment and update advantages of Web applications. What do you do, however, when you want to deploy different application configurations to different sets of users? For example, you might have a Power User version of the application to be distributed to a set of users who require advanced features and a normal version of the application to be distributed to a set of users who only require basic features. you will learn two different methods for distributing different application configurations to users.

Method 1: Installing and Updating from Different Locations

The first method for deploying different configurations via ClickOnce is to set up separate installations for each configuration of the application and pointing all versions of the application to one, common update location. This method can cause quite a bit of maintenance overhead because you have to maintain a different installation for each configuration that you have. However, once you set up the installations, you can streamline the process of deploying updates because all of the applications (regardless of the original installation location) will update from the same place while maintaining the initial configurations.

To follow the demonstration below, you will need to set up the following:

Create the folder "C:\Temp\ClickOncePublishFolder"

Create the folder "C:\ClickOnceInstallationPath"

Create the folder "C:\ClickOnceUpdatePath"

Configure "ClickOnceInstallationPath" to be a shared folder with the same name

Configure "ClickOnceUpdatePath" with IIS to be a virtual directory with the same name

Instructions for setting up a shared folder and a virtual directory for your operating system and version of IIS can be found via Web search and are beyond the scope of this article.

Once you have the directory structure in place, open Visual Studio (2005 or later) and create a new Windows Forms project with default settings. Change the default form in some way to distinguish it from the blank form. In the example below, the form is resized and the title changed to "MainForm".

Right-click on the project (*.csproj) in Solution Explorer and select Properties. Navigate to the Publish tab. Enter the location you created for the Publishing Folder, "C:\Temp\ClickOncePublishFolder". This is where the application files will be placed when you click the "Publish" button.

Next, enter the location from which the ClickOnce package will be installed. You will use the shared folder you created (mocking a shared directory on a server), "\\servername\ ClickOnceInstallationPath". You will need to replace "servername" with the name of your PC or the server where you are deploying.

The next step is to configure the location that the application will use for updates. By default, this will be the same location as the installation folder. To configure the update location, click on the "Updates..." button on the 'Publish' tab.

The dialog shown in Figure 3 will open. Enter the location of the virtual directory you set up for updates. In a real world situation, you would want to set the update path to a publicly available URL if users should be able to update over the Internet.

Figure 3: Set the Update location

Exit the 'Application Updates' dialog. You are now ready to publish the application.

From the 'Publish' tab, click the "Publish Now" button. The solution will build and create the ClickOnce package in the publishing folder's location. If you have the option enabled to 'Open deployment web page after publish' (located on the "Options " button dialog), a browser will launch and display the publish page. For now, minimize the window because the files have not yet been placed in the installation location, and you'll get an error if you try to install now.

Copy the files from the publishing folder location and place them in the installation folder that you configured earlier. It is important that the physical location of the files and the location specified in the configuration match; otherwise, the ClickOnce deployment will fail.

You will now be able to pull the publish page back up, or, if you closed it, open up the publish.htm file in the installation location.

Click on the "launch" link or Install button to install the application. Once the installation is complete, which should be almost instantaneous once you have accepted all of the prompts, the application will launch and you will see your form, as shown in Figure 6.

Figure 6: Your ClickOnce application

Now, you're going to make a small change to the form and deploy an update to the application.

In the example, as shown in Figure 7, the form's background color has been changed to blue.

Click the "Publish Now" button to create the update package for the 1.0.0.1 version of the application. This time, if the publish page comes up, you can close it; you will be updating the application, not installing it from the installation location.

Copy all the files found in the publishing folder location to the update location. You'll notice in the Application Files folder that there is a new folder for the 1.0.0.1 version of the application.

If you haven't already done so, close the application that was launched from the original installation. Navigate to the Start menu and launch the application. You'll notice a brief period of "searching" while the application checks for a newer version. Once it finds that version 1.0.0.1 is available, you'll be presented with the Update Available dialog. Click OK. The new version will be installed and launched automatically.

Figure 10: Your updated ClickOnce application

In the scenario of deploying different sets of configuration options, you can set up multiple installation locations with different configuration files, publish each version of the application with the respective installation location, and set all the update locations to the single update directory. If you use the default configuration settings framework, ClickOnce will manage the merging of configuration settings when updating to new versions of the application. Read up on this topic to get a better understanding of how this works.

Method 2: Configurating Applications Based on URL Parameters

The second method for deploying separate configurations is to use URL parameters to set up the configuration in code during the first installation of the application. When a ClickOnce installation is accessed via a URL on a network or the Internet, you can configure the application to accept parameters via the URL, parse the parameters in the application's code, and store settings in the application configuration file. This method is superior to the first one in that you do not have to manage multiple installation packages. Only one installation is required and you can use the same directory location for updates to the application.

To follow the demonstration below, you will need to set up the following:

Create the folder: "C:\ClickOnceDeployment"

Configure "ClickOnceDeployment" with IIS to be a virtual directory with the same name

Create a new Windows Forms project using Visual Studio (2005 or later). On the default form, change the text property to "Main Form". To configure the application to read the parameters passed to the application during deployment, open up the Code view of the default form and add the following using statements:

using System.Collections.Specialized;
using System.Deployment.Application;
using System.Web;

In addition to the using statements, add a reference to System.Web.

Figure 11: Adding the System.Web reference

Now, add the following code to the form's constructor. This code processes parameters from the URL used to deploy or launch the application. Once the parameters have been added to the dictionary collection, they can be used to change the text of the form.

Next, right-click on the Project (*.csproj) and select Properties. Navigate to the 'Publish' tab. Enter the folder you created earlier, "C:\ClickOnceDeployment" Next, enter the IIS virtual directory created earlier as the Installation Folder URL. In this example, you are publishing to, installing from, and updating from the same location.

Next, you will configure the ClickOnce deployment to accept and use parameters. Click on the "Options..." button to pull up the "Publish Options" dialog.

Figure 13: The Publish Options dialog

By default, the option to allow URL parameters is disabled. Enable it by checking the box next to it.

Figure 14: Configuring the application to accept URL parameters

Click 'OK' and exit out of the dialog. The ClickOnce deployment is now configured.

Click the "Publish Now" button to build the installation package. Once the build and publish are complete, navigate to the following URL in your browser. (Note: A browser window may launch automatically after the publish process is complete.)

The key piece of information in this URL is the "?title=Wow". This parameter will instruct the application to change the title of the form once it is launched. Accept any prompts you receive and install the application. The application will now launch. Notice that the form's title is the value of the parameter passed in the URL.

Figure 15: The application with parameter "Wow"

Close the application, change the parameter to something else, for example: "?title=ClickOnce Rocks".

Figure 16: The application with parameter "ClickOnce Rocks"

Close the application. Via the Start menu, launch the application as you would any other desktop application. You'll notice that the text of the form is "Main Form", which is the title you set during design.

Figure 17: The application launched from the Start menu instead of a URL

In this scenario, you could retain the information passed in the initial URL by storing it into the application's configuration file instead. You could send users different URLs that will configure the application correctly. You could even create a simple web page that allows users to select different options (for example, background color or language) and use the inputs to construct the correct URL with each of the options as parameters. Whichever way you construct the URL, you can store these parameters in the application's configuration file via code and use the configuration to set up the application on launch.

Conclusion

ClickOnce is a powerful tool for deploying and updating applications with a rich, responsive user experience. You examined two different methods for deploying different application configurations to your users. The first method requires separate installation packages for different configurations. The second method requires customized URL parameters and the use of code to parse and store the parameters as application settings.

About the Authors

Matt Goebel is a manager with Crowe Horwath LLP in the Indianapolis, Indiana, office. He can be reached at 317.208.2555 or matt.goebel@crowehorwath.com.

Rachel Baker is a senior developer with Crowe Horwath LLP in the Oak Brook, Illinois, office. She can be reached at 630.990.4434 or rachel.baker@crowehorwath.com.

Advertiser Disclosure:
Some of the products that appear on this site are from companies from which QuinStreet receives compensation. This compensation may impact how and where products appear on this site including, for example, the order in which they appear. QuinStreet does not include all companies or all types of products available in the marketplace.