Skip Navigation LinksHome > SSW Standards > Rules > SSW Rules to Better Windows Forms Applications - ClickOnce

There was an error displaying the testimonials. Please report this error to SSW and include the following text:
- A network-related or instance-specific error occurred while establishing a connection to SQL Server. The server was not found or was not accessible. Verify that the instance name is correct and that SQL Server is configured to allow remote connections. (provider: Named Pipes Provider, error: 40 - Could not open a connection to SQL Server)

 

ClickOnce is a technology that allows developers to write Windows Forms applications that utilize the powerful features of the client, yet are as hassle-free to deploy and update as a Web page.

ClickOnce provides a rich set of easy to use capabilities for deploying and updating smart client applications, including lots of options and ways of approaching things. Once you understand how to get your application out the door and updated, using the myriad of options that ClickOnce provides, lots of other questions arise, including how to make it more secure and how things will change in the future.

Do you agree with them all? Are we missing some? Let us know what you think.

  1. The Assembly and File Version should be the same by default

    For the purpose of consistency, version numbers should be the same there are few exceptions. One exception is for backward compilation:
    If you have other .dll files depend on the assembly, changing Assembly Version will break these dependencies and then cause a crash in your application. So you can keep the Assembly Version unchanged and increase the File Version when you release new build. It is easy to maintain the version numbers in VS.NET 2005, but we have some suggestions on modification of version numbers in VS.NET.

  2. Do you keep the version in Sync (in all 3 places)?

    The Assembly Version, File Version should be in Sync 95% of the time. The only case is backward compatibility. If you are using ClickOnce for deployment, you also need to keep the Publish Version in sync also. Yes that is 3 places Microsoft should make this easier. See suggestions on modification of version numbers in VS.NET

  3. Do you set the appropriate download (.exe or .application) for your web users?

    In general, you should set the user to download the Setup.exe of your ClickOnce application. However there are many cases where the only prerequisite of the application is .Net 2, and the users don't need the Setup.exe. Instead, the .application file would allow the user to install the application, or run it instantly if they already have .Net 2. The following code allows you to check for the .Net 2 runtime on the client's machine (note: Request.Browser.ClrVersion may return 0.0 on some browsers).

                                dim verHave as Version = Request.Browser.ClrVersion
                                dim verNeed as Version = new Version("2.0.50727")
                                                                    
                                if ( verHave < verNeed ) then
                                    Response.Write("<a href=""./Download/Setup.exe"">")
                                else
                                    Response.Write("<a href=""./Download/SSWDiagnostics.application"">")
                                end if
    			           
    Figure: Code to detect the client's CLR version and offers the download accordingly

    Note: SSW Diagnostics uses this code on its homepage.

  4. Do you make a clear symbol to inform the users that you are using a ClickOnce version application?

    If you use ClickOnce to deploy your application, you should clearly show a symbol indicating this is a ClickOnce version application. ClickOnce makes applications enjoying convenient update, maximizing to keep the safety of the users' system environment.

    Good Example
    Good Example: Showed a symbol indicates this is a ClickOnce version of application.
    Bad Example
    Bad Example: No any symbol indicates this is a ClickOnce version of application.
  5. Do you know whether you should use Click Once or MSI?

    1. Check the following table whether ClickOnce is suit for your application.
      This table compares the features of ClickOnce deployment with Windows Installer deployment. Read ClickOnce Deployment Overview for more details.

      Feature

      ClickOnce

      Windows Installer

      Automatic update1

      Yes

      Yes

      Post-installation rollback2

      Yes

      No

      Update from Web

      Yes

      No

      Does not affect shared components or other applications

      Yes

      No

      Security permissions granted

      Grants only permissions necessary for the application (more safe)

      Grants Full Trust by default (less safe)

      Security permissions required

      Internet or Intranet Zone (Full Trust for CD-ROM installation)

      Administrator

      Application and deployment manifest signing

      Yes

      No

      Installation-time user interface

      Single prompt

      Multipart Wizard

      Installation of assemblies on demand

      Yes

      No

      Installation of shared files

      No

      Yes

      Installation of drivers

      No

      Yes (with custom actions)

      Installation to Global Assembly Cache

      No

      Yes

      Installation for multiple users

      No

      Yes

      Add application to Start menu

      Yes

      Yes

      Add application to Startup group

      No

      Yes

      Add application to Favorites menu

      No

      Yes

      Register file types

      No

      Yes

      Install time registry access3

      Limited

      Yes

      Binary file patching

      No

      Yes

      Application installation location

      ClickOnce application cache

      Program Files folder

      Notes

      1. With Windows Installer, you must implement programmatic updates in the application code.

      2. With ClickOnce, rollback is available in Add or Remove Programs.

      3. ClickOnce deployment can access HKEY_LOCAL_MACHINE (HKLM) only with Full Trust permission.

      For more information, see Choosing a Deployment Strategy.

    2. Customize the Installation of the Application, including: Publish location, installation url, install mode, publish version, Download files on demand, Prerequisites, Updates, Options.

      ClickOnce Publish property
      Figure: Publish tab of the application properties

    3. Specify the code access security permissions that the application requires in order to run.

      ClickOnce Security property
      Figure: Security tab of the application properties

    4. Deploy the COM Components. Read Deploying COM Components with ClickOnce for more informations.

    5. Publish the application using Publish Wizard.

      ClickOnce Publish Wizard
      Figure: ClickOnce Publish Wizard

  6. Do you know to use async code to do the check for update? (using System.Deployment.Application classes)

    Application updates don’t have to be difficult to do for the user. Pointing the user to a website where he can download an update is not ideal. A better way is to take advantage of the System.Deployment.Application namespace. You can develop custom upgrade behaviours into your ClickOnce/Smart client application.

    System.Diagnostics.Process.Start(@"http://www.ssw.com.au/ssw/Download/ProdBasket.aspx?ID=15");
    			           
    Figure: Bad example - Using web page to do the check for a new version
    long sizeOfUpdate = 0;
    
    private void UpdateApplication()
    {
        if (ApplicationDeployment.IsNetworkDeployed)
        {
            ApplicationDeployment ad = ApplicationDeployment.CurrentDeployment;
            ad.CheckForUpdateCompleted += new CheckForUpdateCompletedEventHandler(ad_CheckForUpdateCompleted);
            ad.CheckForUpdateProgressChanged += new DeploymentProgressChangedEventHandler(ad_CheckForUpdateProgressChanged);
    
            ad.CheckForUpdateAsync();
        }
    }
    
    void  ad_CheckForUpdateProgressChanged(object sender, DeploymentProgressChangedEventArgs e)
    {
        downloadStatus.Text = String.Format("Downloading: {0}. {1:D}K of {2:D}K downloaded.", e.State, e.BytesCompleted/1024, 
        e.BytesTotal/1024);   
    }
    
    void ad_CheckForUpdateCompleted(object sender, CheckForUpdateCompletedEventArgs e)
    {
        if (e.Error != null)
        {
            MessageBox.Show("ERROR: Could not retrieve new version of the application. Reason: \n" + e.Error.Message + 
            "\nPlease report this error to the system administrator.");
            return;
        }
        else if (e.Cancelled == true)
        {
            MessageBox.Show("The update was cancelled.");
        }
    
        // Ask the user if they would like to update the application now.
        if (e.UpdateAvailable)
        {
            sizeOfUpdate = e.UpdateSizeBytes;
    
            if (!e.IsUpdateRequired)
            {
                DialogResult dr = MessageBox.Show("An update is available. Would you like to update the application now?
                \n\nEstimated Download Time: ", "Update Available", MessageBoxButtons.OKCancel);
                if (DialogResult.OK == dr)
                {
                    BeginUpdate();
                }
            }
            else
            {
                MessageBox.Show("A mandatory update is available for your application. We will install the update now, 
                after which we will save all of your in-progress data and restart your application.");
                BeginUpdate();
            }
        }
    }
    
    private void BeginUpdate()
    {
        ApplicationDeployment ad = ApplicationDeployment.CurrentDeployment;
        ad.UpdateCompleted += new AsyncCompletedEventHandler(ad_UpdateCompleted);
    
        // Indicate progress in the application's status bar.
        ad.UpdateProgressChanged += new DeploymentProgressChangedEventHandler(ad_UpdateProgressChanged);
        ad.UpdateAsync();
    }
    
    void ad_UpdateProgressChanged(object sender, DeploymentProgressChangedEventArgs e)
    {
        String progressText = String.Format("{0:D}K out of {1:D}K downloaded - {2:D}% complete", 
        e.BytesCompleted / 1024, e.BytesTotal / 1024, e.ProgressPercentage);
        downloadStatus.Text = progressText;
    }
    
    void ad_UpdateCompleted(object sender, AsyncCompletedEventArgs e)
    {
        if (e.Cancelled)
        {
            MessageBox.Show("The update of the application's latest version was cancelled.");
            return;
        }
        else if (e.Error != null)
        {
            MessageBox.Show("ERROR: Could not install the latest version of the application. Reason: \n" + e.Error.Message + 
            "\nPlease report this error to the system administrator.");
            return;
        }
    
        DialogResult dr = MessageBox.Show("The application has been updated. Restart? (If you do not restart now, 
        the new version will not take effect until after you quit and launch the application again.)", 
        "Restart Application", MessageBoxButtons.OKCancel);
        if (DialogResult.OK == dr)
        {
            Application.Restart();
        }
    }
    			           
    Figure: Good example - Using System.Deployment.Application classes to do the check for a new version

    More Information:

    When testing whether your deployment has an available update by using either the CheckForUpdate or CheckForUpdateAsync methods; the latter method raises the CheckForUpdateCompleted event when it has successfully completed. If an update is available, you can install it by using Update or UpdateAsync; the latter method raises the UpdateCompleted event after installation of the update is finished.

  7. Do you know what the user experience should be like?

    As per the rule Do you know there should be a standard menu item "Check for Updates"? on Rules to Better Windows UI, you should have a standard menu item "Check for Updates" in the Help menu.

    Here are a couple of examples of Check for Updates results:

    Bad Example
    Figure: Skype does a good job, with a green tick and simple message. The actual version number would have made it more complete.
    Bad Example
    Figure: Snagit has horrible UI (red text when it is not an error and Hyperlinks without underlines), however the link to the latest features is not bad
    Good Example
    SSW Code Auditor has a great UI (using the freely available component in .NET Toolkit)

    More Information:

    If you implement this code from the SSW Toolkit, you will get this UI.

    Help | Check for Updates opens the Updater form
    Figure 1: Help | Check for Updates opens the Updater form.
    Confirmation that they already have the latest version
    Figure 2: Confirmation that they already have the latest version.
    The simple prompt to upgrade when a new version is available.
    Figure 3: The simple prompt to upgrade when a new version is available.
    Showing the upgrading progress.
    Figure 4: Showing the upgrading progress.
    Restarting the application is required.
    Figure 5: Restarting the application is required because the new version will not take affect until quit and launch the app again.

Acknowledgements

Adam Cogan
Marten Ataalla

Benefit from our knowledge and experience!

SSW is the industry leader in Custom Software Development, Software Auditing & Developer Training.

Call us on +61 2 9953 3000 or email us for a free consultation

What does it cost? I’m not in Australia. Can you still help?