Enhanced Logging in ClickOnce Deployment

With the .NET 4.0 Framework, Microsoft has added the ability to turn on verbose logging for the install, update, and uninstall of a ClickOnce application. Of course, it doesn’t do much good to modify the amount of logging without providing access to the log file, so they have also added the ability to let you specify the location and name of the output file for the logging. When you define the log file path, it creates or appends to the log file every time a ClickOnce application is installed, updated, or uninstalled. It even works if you are doing programmatic updates.

What’s particularly keen about these features is that they work for any ClickOnce application as long as .NET 4.0 is installed. In other words, if your ClickOnce application targets the .NET 2.0, 3.0, or 3.5 Framework, you can still install the .NET 4.0 Framework on the computer and take advantage of the new logging features. (Installing .NET 4.0 also installs the updated ClickOnce engine, which is more stable.)

Now what you really want to know is what the log files look like, so you’ll know whether this is worth the trouble. I created a small application that has one Windows Form, and I deployed it with ClickOnce. I installed and uninstalled it with verbose logging turned on and with verbose logging turned off. Then I added programmatic updates and let it update asynchronously and restart the application. The logging for automatic updates is the same as an install, but it’s less detailed if you are using programmatic updates. Here are the log files:

ClickOnceLog_Verbose_Install
ClickOnceLog_Verbose_Uninstall
ClickOnceLog_Verbose_Update_Programmatic
ClickOnceLog_NotVerbose_Install
ClickOnceLog_NotVerbose_Uninstall
Zip file of all five log files

Since you’re still reading this, you probably want to know how to turn on the verbose logging and set up the log file. Or at least, how to set up the log file (you may think the verbose logging is too chatty). It’s very simple. You need to add some entries to the Windows registry.

The log file path goes here:
HKEY_Current_User\Software\Classes\Software\Microsoft\Windows\CurrentVersion\Deployment\LogFilePath

The registry key for verbose logging goes here:
HKEY_Current_User\Software\Classes\Software\Microsoft\Windows\CurrentVersion\Deployment\LogVerbosityLevel

To add these, open the registry editor and drill down to the Deployment sub-key. Right-click on Deployment and select “New” and then “String Value” as displayed here:

Type in the key name and press Enter. Then press Enter again or double-click on the entry to set the value.

Type in the value and press Enter.

If you want to stop outputting the logging, delete the registry key for the LogFilePath.

If you change or set the LogFilePath, it takes effect immediately. If you change or set the LogVerbosityLevel, it does not take effect until the user logs off and logs back in.

Another fun piece of information: If you set the LogFilePath to an empty string instead of deleting the registry entry, every time you run the ClickOnce application, you will get an error that dfsvc.exe (the ClickOnce service) is no longer working. (I’m thinking that’s not a feature.)

One word of caution: there is no automatic cleanup of the log file, no rollover when it gets to a certain size or anything like that. ClickOnce continues to append to the log file with every install, update, and uninstall. So if you start up the logging on someone’s computer, you must remember to come back around and turn it back off.

If you want to leave the logging turned on, I strongly recommend that you have your application manage the log file. For example, you could rename the log file every time a new one is created, and make sure you only keep the most recent one. You can tell if the application is newly installed or if an update is newly installed by checking the IsNetworkDeployed property of System.Deployment.Application.ApplicationDeployment. If true, the user just installed the application, or installed an update, and you could manage the log file at that time.

Programmatically modifying the registry

Editing the registry is fraught with peril. I remember the old days when you used to be able to call Microsoft for help with Windows (the REALLY old days). One of the first things they would ask you was, “Did you edit the Windows registry?” It only took one phone call to learn that if you said “Yes”, they would not help you. This taught many developers to, well, lie.

So just for grins, I wrote a small .NET application that provides a user interface you can use to change the registry entries for the ClickOnce logging. Basically it displays a screen where you can browse to the folder where you want your log files, and you can turn verbose logging on and off. Here’s what the UI looks like:

You could take this project and set the target Framework to the same as your application. If your user has the .NET Framework installed on their computer, you can just build this application and then copy the executable to the user’s machine and run it to set the values.  Or better yet, put it on a thumb drive and run the executable from there.

Since the registry entries are in HKCU, you could also have your ClickOnce application update these values, but that’s not helpful for the first install!

Let’s take a look at the LogSettings class that does all the work. This is in C#, but the whole solution is available in both C# and VB at the end of this article.

First, here are the namespaces you need to include. Microsoft.Win32 is for the registry changes.

using System.IO;
using Microsoft.Win32;

Next are the constants and properties. This includes the registry sub-key name. When you retrieve the registry sub-key, you specify which hive, such as HKCU, so it is not part of the sub-key name.

//This is where the values go for the ClickOnce logging, in HKEY_Current_User.
private static string ClickOnceLoggingSubKeyName = 
  @"Software\Classes\Software\Microsoft\Windows\CurrentVersion\Deployment";

/// <summary>
///This is the registry value name for the log file path. 
///The value should be the fully-qualified path and file name of the log file.
/// </summary>
private static string rkName_LogFilePath = "LogFilePath";
      
/// <summary>
/// This is the registry value name for the logging level. 
/// The value should be = 1 if you want verbose logging. 
/// To turn off verbose logging, you can delete the entry or set it to 0.
/// </summary>
private static string rkName_LogVerbosityLevel = "LogVerbosityLevel";

/// <summary>
/// Fully-qualified path and name of the log file.
/// </summary>
public string LogFileLocation { get; set; }

/// <summary>
/// Set this to 1 for verbose logging.
/// </summary>
public int LogVerbosityLevel { get; set; }

/// <summary>
/// Set to true if doing verbose logging.
/// </summary>
public bool VerboseLogging { get; set; }

Here is the method called to create an instance of the class; this reads the current entries from the registry and stores them in the class properties. First you open the sub-key, and then you retrieve the two values that you need.

/// <summary>
/// Create a new instance of this class and get the value for the registry entries (if found).
/// </summary>
/// <returns>An instance of this class.</returns>
public static LogSettings Create()
{
  LogSettings ls = new LogSettings();

  //open the Deployment sub-key.
  RegistryKey rk = Registry.CurrentUser.OpenSubKey(ClickOnceLoggingSubKeyName);

  //get the values currently saved (if they exist) and set the fields on the screen accordingly
  string logLevel = rk.GetValue(rkName_LogVerbosityLevel, string.Empty).ToString();
  if (logLevel == "1")
  {
    ls.VerboseLogging = true;
    ls.LogVerbosityLevel = 1;
  }
  else
  {
    ls.VerboseLogging = false;
    ls.LogVerbosityLevel = 0;
  }
  ls.LogFileLocation = rk.GetValue(rkName_LogFilePath, string.Empty).ToString();           
  return ls;
}

And last, but not least, here is the method to save the entries back to the registry. You open the sub-key in write mode, so you can modify the associated values. If the log level is not set to verbose, this deletes the value for the logging level from the registry. If no file name is specified for the log file, this deletes that registry entry. Otherwise, the entries are updated with the values set on the screen.

/// <summary>
/// Save the values to the registry.
/// </summary>
/// <returns></returns>
public bool Save()
{
  bool success = false;
  try
  {
    //Open the Deployment sub-key.
    RegistryKey rk = Registry.CurrentUser.OpenSubKey(ClickOnceLoggingSubKeyName, true);
    //Set the values associated with that sub-key.
    if (this.VerboseLogging)
      rk.SetValue(rkName_LogVerbosityLevel, "1");
    else
    {
      //check to make sure the [value] exists before trying to delete it 
      object chkVal = rk.GetValue(rkName_LogVerbosityLevel);
      if (chkVal != null)
      {
        rk.DeleteValue(rkName_LogVerbosityLevel);
      }
    }

    if (this.LogFileLocation.Length == 0)
    {
      //check to make sure the [value] exists before trying to delete it 
      //Note: If you set the values to string.Empty instead of deleting it,
      //  it will crash the dfsvc.exe service.
      object chkPath = rk.GetValue(rkName_LogFilePath);
      if (chkPath != null)
        rk.DeleteValue(rkName_LogFilePath);
    }
    else
    {
      rk.SetValue(rkName_LogFilePath, this.LogFileLocation);
      string logFolder = Path.GetDirectoryName(this.LogFileLocation);
      if (!Directory.Exists(logFolder))
          Directory.CreateDirectory(logFolder);
    }
    success = true;
  }
  catch
  {
    throw;
  }
  return success;
}

The Visual Studio 2010 solutions can be downloaded in either CSharp or VB.

Download the C# version

Download the VB version

Acknowledgements

Thanks very much to Jason Salameh at Microsoft, who I believe was largely responsible for adding this feature. I believe it will provide some clarity and help with troubleshooting when people have problems installing ClickOnce applications.

[Edit 7/7/2011 Move downloads to Azure blob storage]

[Edit 3/8/2014 Move to different Azure blob storage]

What’s New in ClickOnce Deployment in .NET 4.0

There are some cool new features in .NET 4.0 and VS2010 for ClickOnce deployment. I’m going to summarize the new features here and provide some links to the details.

The ClickOnce engine has been updated and strengthened, and the team that supports the runtime says that the errors that seem to have no solution, such as "dfsvc.exe has stopped working", should be fixed. They have also added enhanced logging and the option to set the location (and name) of the ClickOnce log file — no more searching through your Temp folder! What’s cool about these changes is that they apply if you install .NET 4.0 on the computer, regardless of the version your application targets. So if you have a Windows Forms application that targets .NET 2.0 and you are having problems installing it, you can install .NET 4.0 on the computer and turn on the verbose logging. This has already been useful to me, so I will blog about it next.

They have fixed “the certificate problem” in all cases. The problem is discussed in detail here. The basic problem was that when you changed the certificate used to sign the ClickOnce deployment, the customers would have to uninstall and reinstall the application. They fixed this in .NET 3.5 SP-1 if you used automatic updates, but not for programmatic updates, and not for VSTO projects. Now they have fixed it in all cases when targeting the .NET 4.0 Framework.

With VS2010, you can configure your application to target multiple versions of the .NET Framework. Of course, this doesn’t mean it will run on multiple versions – you will have to verify that yourself. To use this feature, you have to manually edit the manifest files and app.config file and re-sign the manifests. For details, click here.

For XBAP applications (browser-hosted WPF applications), these can now elevate to Full Trust just like any other ClickOnce application. For more info, check out this article.

For VSTO projects, you can now deploy multiple Office solutions together with one ClickOnce installation. Like the Three Musketeers, it’s all for one and one for all. All of them are installed together, and if you uninstall through Programs, it uninstalls all of them. 

For VSTO projects, you also now have the ability to do some post-deployment actions. For example, you can create registry keys, modify a config file, or copy a document to the end user computer.

Another interesting change for VSTO projects is if you are targeting the .NET 4.0 Framework, you no longer have to include the Primary Interop Assemblies as a prerequisite. The type information for the PIAs that you use in your add-in is embedded into the solution assembly and used at runtime instead of the PIAs.

And last, but not least — in .NET 3.5 SP-1, they quietly introduced the ability to create your own custom UI for your ClickOnce deployment, while still using the ClickOnce engine to install and update your application. They have improved this feature for .NET 4.0; check out the walkthrough example here.

I think there’s something useful in the new features for everyone. If there are other features you would like to see – other than “install for all users”, which is a complete paradigm shift – please leave a comment. I will summarize the requests and pass them on to the ClickOnce team at Microsoft.