Types of LightSwitch Applications

The application run by a user which was published from LightSwitch is a Silverlight application. This client application can take one of 2 forms: Desktop or Web. As the property pages and publish wizard state, a Web application runs in the user's browser and is not be able to access other programs. This means that to run the application, a user will have to point their browser to an IIS (or Azure) server which is hosting the application. The server will then serve up the LightSwitch application (packaged as a .xap file) which will run in Silverlight's partial trust sandbox. Whether the application server type is IIS or Windows Azure the experience of running the application client should be fundamentally the same. This type of application is known as a 3-Tier browser application: client, database, and server.

On the other hand, a Desktop application "runs on the user's desktop and can access other programs". So, a desktop application is not ultimately run in the browser (although to initially get to the application, a user may have to use the browser). Instead, it is run in by the Silverlight Out-of-browser Launcher, a tool installed with Silverlight. A desktop application is installed on the client computer, and can be uninstalled using Add/Remove Programs. Once installed, the application is launched from the user's desktop or Start menu. Most notably, the application runs in partial trust. This means that the application can interact with other programs, provided there are entrypoints for those applications. For example, you could have an application write out invoices to Microsoft Word. When you choose a desktop application, LightSwitch modifies the OutOfBrowserSettings.xml file in the client project to tell the Silverlight runtime that the application requires elevated permissions.

Desktop applications come in two forms, depending on the application server type: 2-tier applications or 3-tier applications. A 2-tier application is deployed as a ClickOnce application. The client and server tiers are the same in this case: the user's machine, kind of like what is done when the application is debugged in the LightSwitch IDE. A handy feature within ClickOnce is that the application can be automatically updated when a newer version of the application is available.

A 3-tier desktop application is also hosted on either IIS or Windows Azure, and the experience of running that application should be the same, regardless of which is chosen.

When to Sign

How does signing relate to the application's trust level? It doesn't. The application does not need to be signed to run in elevated trust (that is, to be a desktop application); the trust level is dictated by that OutOfBrowserSettings.xml file that is hidden away. This is handy when debugging your application: you are under no obligation to specify a signing certificate to F5 your application.

Signing is only used for one deployed application type: 3-tier desktop applications. Signing is relevant during the install and update of the application. The application user will be prompted with a security warning prior to installation of the application. The level of the warning can vary based on the state of the application signature. Once installed, the application will automatically detect if a newer version of the application has been published. If so, the application will attempt to install the latest version of the application. However, in order for the auto-update to work, the latest version of the application must be signed with the same key as the previous version.

How to Sign

Application signing is now built into the publish wizard. You can go to the "Specify a Certificate" to turn on application signing by checking the "Specify a certificate" checkbox. There are 3 ways to supply a certificate for the application singing. You may

• "Select a certificate from the computer's store" shows you the set of relevant certificates that are available on your computer
• "Browse for a certificate" allows you to select a certificate file (.pfx) that you may have on your computer
• "Create a test certificate" creates a self-signed certificate used to sign the application. You must enter a password for the new cert, which will expire after 1 year

This wizard page also shows additional information about the cert you have selected. By default, the checkbox is checked only if you are application is a 3-tier desktop application.

Running the Application

Once your application has been published to a web server, a client who wants to run that application will navigate to the publish location. The application will start, and the user will be told to install the application by clicking on the Install button:

Depending on how the application was signed, the user will then be issued an installation prompt from Silverlight. For applications which have not been signed, or are signed with a self-signed certificate, the  user will be presented with an installation screen that looks something like this:

Or for a more trusted certificate something like this:

The user has the ability to choose if they want to install a shortcut to the application on their desktop, on the Start menu, or both, by clicking on the "More options" button on the installation dialog.

After installation, navigating to the publish location shows that a screen telling the user to launch the application from the Start menu. If there are subsequent updates to the application, the application will detect  and automatically install these updates:

Unless, that is, the original application was not signed, or was signed with a different cert. In that case, the update would fail, and you would have to uninstall and then re-install the application:

Signing your 3-tier desktop application helps ensure the application upgrade works.

Additional Resources
LightSwitch documentation: Signing a XAP File by Using a Certificate
Silverlight Out-of-browser support

I meant to write a quick overview of LightSwitch application deployment after Beta 1 shipped, but I never got around to it. And then some of my colleagues started writing some good stuff about LightSwitch and deployment, so I figured why screw things up by adding my take on things?

I've since come around: hopefully there is a spot for my behind-the-scenes insight into LightSwitch and application deployment. So I'm back, baby! With a vengeance!

Let's start off with a softball of a post: How has deployment changed between Beta 1 and Beta 2? Here's a quick summary.

Publish to Azure This is by far the biggest deployment change in Beta 2. If you have a Windows Azure account, you can publish your LightSwitch application to it. The publish wizard should walk you through the steps to get your application onto Azure. And of course its also possible to publish your data to SQL Azure as well. Andy Kung has a nice writeup of how to publish your LightSwitch application to Windows Azure.

Server Runtime is Copied Locally In Beta 1 there was a separate runtime that needed to be installed on the server for the server-side code. Such a runtime is highly impactful to the hosting machine (which can be good, but can also be bad). In Beta 2, LightSwitch no longer requires a runtime to be installed to the server to run a LightSwitch application.

Publishing to a Web Hosting Company Publishing the server runtime with the application opens the scenario of publishing to a web hoster, without the need for that hoster to have files installed to the Global Assembly Cache. However, publishing a LightSwitch project uses an extension  for MSDeploy to help configure the web application. The provider is shipped in a separate installer, titled the Visual Studio LightSwitch Deployment Prerequisites. If your web hoster does not have the provider available, it is possible to bypass this configuration step while publishing simply by selecting this option within the Server Configuration page of the Publish Wizard. You will then have to make sure the web location is properly configured to handle a LightSwitch application by adding the application to a .NET 4.0 application pool, and potentially configuring the application Authentication type.

Support for Additional IIS Platforms A common misconception for Beta 1 was that the only IIS platform capable of hosting a LightSwitch application was Windows 2008. This was not entirely true: it was possible to generate an MSDeploy package of your LightSwitch application and install it on Windows 7 and IIS 7, or even Windows 2003 Server and IIS 6. However, it was not possible to publish from the IDE directly to either of those platforms. For LightSwitch Beta 1, the remote publish scenario was based on the capabilities of Visual Studio 2010 Beta 2. However, between VS 2010 Beta 2 and RTM, the One-Click publish feature for web applications added the capability of publishing directly to IIS 6 and Windows 7. LightSwitch Beta 2 follows this lead. The server requires MSDeploy with the Web Deployment Agent Service installed. You can also deploy to localhost, provided you start LightSwitch with administrative privileges.

Database Schema Publishing has been updated as well. The publish wizard handles 2 different connection strings: one for publishing the database schema (the "administrator connection"), and a second for accessing that data from the application (the "user connection"). The administrator connection obviously needs more permissions than the user connection would typically require, but if you want to use the same for both connection strings that is allowed. If you want to create a new login for the for the user connection string, that capability is also added to the Database Connections wizard page.

Xap Signing A desktop application deployed to IIS or Windows Azure will also check for updates as part of application launch. Unfortunately, the update is not applied unless the .xap file is properly signed. LightSwitch Beta 1 provided no means to sign the application, a problem that has been corrected with LightSwitch Beta 2. (Update 6/13/2011: Read more about this topic here).

There is a lot more that could be written about all of these topics. And there will be! As each new entry is written, this space will be updated with a link to the in-depth examination of the issue.

There are several circumstances when you want thte web page created as part of the manifest generation process instead of the publish process. For example, when manifests are generated as part of an automated build process. Perhaps you want to use your own template for the web page, but still want some aspects of the page to be dynamically set. Or, matbe you want to translate the template into a different language, be it one available from a Visual Studio language pack, or one not supplied by Microsoft. Whatever your reason, this blog post will show you one way to get that done.

Background: How publish.htm is generated

Let's begin by looking at the template used to generate the web page. It is embedded as a resource in Microsoft.ViualStudio.Publish.dll, available in the GAC. I have attached it at the end of the post, but it is an XSL style sheet. Here's a little snippet:

<xsl:template  match="PageData"> 
 
  <HTML> 
 
    <HEAD> 
      <TITLE> 
        <xsl:value-of  select="ProductName"/> 
      </TITLE> 
      <META  HTTP-EQUIV="Content-Type"  CONTENT="text/html; charset=utf-8"/>

The stylesheet reads info out of an XML fragment, of which PageData is the root element. A scan of the stylesheet shows that the data used to transform the stylesheet may look something like this:

<PageData  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
  <ApplicationVersion>1.0.0.0</ApplicationVersion> 
  <InstallUrl>ConsoleApplication.application</InstallUrl> 
  <ProductName>ConsoleApplication</ProductName> 
  <PublisherName>Mike Wade</PublisherName> 
  <SupportUrl>http://blogs.msdn.com/mwade</SupportUrl> 
  <Prerequisites> 
    <Prerequisite>.NET Framework 3.5</Prerequisite> 
    <Prerequisite>Windows Installer 3.1</Prerequisite> 
  </Prerequisites> 
  <RuntimeVersion>2.0.0</RuntimeVersion> 
  <BootstrapperText>The following prerequisites are required:</BootstrapperText> 
  <ButtonLabel>Install</ButtonLabel> 
  <BypassText>If these components are already installed, you can {launch} the application now. Otherwise, click the button below to install the prerequisites and run the application.</BypassText> 
  <HelpText>ClickOnce and .NET Framework Resources</HelpText> 
  <HelpUrl>http://msdn.microsoft.com/clickonce</HelpUrl> 
  <NameLabel>Name:</NameLabel> 
  <PublisherLabel>Publisher:</PublisherLabel> 
  <SupportText>Mike Wade Customer Support</SupportText> 
  <VersionLabel>Version:</VersionLabel> 
</PageData>

The xml input contains 3 basic types of information:

1. Application specific information (publisher, product, install, etc.)
2. Application prerequisite information (bootsrapper packages installed, a .NET Framework runtime used by the jscript)
3. Static strings read from Microsoft.VisualStudio.Publish.dll

A build task to create publish.htm

namespace CreatePublishWebPage 
{ 
    public class CreatePublishWebPage : Task 
    { 
    } 
}

This task will be performing the XML transform. Most of the work that the task does will be to populate the page data to get it ready for serialization and then used in the transform. The page data is declared like this:

public struct PageData 
{ 
    public string ApplicationVersion; 
    public string InstallUrl; 
    public string ProductName; 
    public string PublisherName; 
    public string SupportUrl; 
 
    [XmlArray()] 
    [XmlArrayItem("Prerequisite")] 
    public string[] Prerequisites; 
    public string RuntimeVersion; 
 
    public string BootstrapperText; 
    public string ButtonLabel; 
    public string BypassText; 
    public string HelpText; 
    public string HelpUrl; 
    public string NameLabel; 
    public string PublisherLabel; 
    public string SupportText; 
    public string VersionLabel; 
}

The first 5 items are all part of the deploy manifest. It would be possible to populate the information with the project properties used to build the manifest, or the information could be pulled directly from the manifest. Let's choose the latter. One slight difference is that the publisher and product are automatically populated when the manifest is generated, even if the properties are blank.

The prerequisites will be taken from the bootrapper build information, both the bootstraper package items as well as the bootstrapper enabled property. The RuntimeVersion data is only used when the jscript is written into the web page. There are 2 potential sources for this version: either by inspecting the list of bootstrapper packages, or by inspecting the application manifest's prerequisites. VisualStudio uses the former, but this task will use the latter: its a more accurate reflection of the true requirements of the application.

Finally, the other information will be part of the build tasks resources, which I also pulled out of Microsoft.VisualStudio.Publish.dll

With this in mind, it is easy to stub out the task, like this:

[Required] 
public string ApplicationManifestFileName { get; set; } 
 
[Required] 
public string DeploymentManifestFileName { get; set; } 
 
[Required] 
public bool BootstrapperEnabled { get; set; } 
 
public ITaskItem[] BootstrapperPackages { get; set; } 
 
public string TemplateFileName { get; set; } 
 
public string OutputFileName { get; set; } 
 
public override bool Execute() 
{ 
    PageData data = new PageData(); 
 
    WriteManifestInfo(ref data); 
    if (BootstrapperEnabled) 
    { 
        WriteBootstrapperInfo(ref data); 
    } 
    WriteStaticText(ref data); 
 
    XmlTransform(data); 
     
    return true; 
}

Now, let's get to th actual meat of the task, starting with WriteManifestInfo. The code will use the ManifestUtilities API to directly access the appropriate properties from DeployManifest. ManifestUtilities is defined in Microsoft.Build.Tasks.v3.5.dll, which unfortunately only exists in the GAC. You will have to copy it out of the GAC in order to add a reference to it. The code to populate the page data is not terribly tricky:

using Microsoft.Build.Tasks.Deployment.ManifestUtilities;

private DeployManifest deployManifest = null; 
private DeployManifest DeployManifest 
{ 
    get 
    { 
        if (deployManifest == null) 
        { 
            deployManifest = (DeployManifest)ManifestReader.ReadManifest(this.DeploymentManifestFileName, true); 
        } 
        return deployManifest; 
    } 
} 
 
 private void WriteManifestInfo(ref PageData data) 
{ 
    data.ApplicationVersion = DeployManifest.AssemblyIdentity.Version; 
    data.InstallUrl = Path.GetFileName(DeployManifest.SourcePath); 
    data.ProductName = DeployManifest.Product; 
    data.PublisherName = DeployManifest.Publisher; 
    data.SupportUrl = DeployManifest.SupportUrl; 
}

The code uses a simple accessor to access the DeployManifest, and then writes appropriate information to the page data.

Dealing with prerequisites is a little more complicated in. There are 3 important steps in the process:

1. Add a list of all installed prerequisites into the Prerequisites field
2. Determine if the only prerequisites are .NET Frameowrk (or Windows Installer 3.1) only
3. Determine the required framework version based on the presence of specific .NET assemblies in the application manifest

For this last point, the WindowsBase prereq corresponds to the 3.0 framework, while System.Core corresponds to the 3.5 framework. The prereqs are looked by examining the AssemblyReferences of the application manifest. Now for the actual code:

using Microsoft.Build.Tasks.Deployment.Bootstrapper;

private static readonly string[] DOTNET30AssemblyIdentity = { "WindowsBase", "3.0.0.0", "31bf3856ad364e35", "neutral", "msil" }; 
private static readonly string[] DOTNET35AssemblyIdentity = { "System.Core", "3.5.0.0", "b77a5c561934e089", "neutral", "msil" }; 
private const string METADATA_INSTALL = "Install"; 
private const string PRODUCT_CODE_DOTNET_PREFIX = "Microsoft.Net.Framework."; 
private const string PRODUCT_CODE_WINDOWS_INSTALLER = "Microsoft.Windows.Installer.3.1";

private void WriteBootstrapperInfo(ref PageData data) 
{ 
    BootstrapperBuilder builder = new BootstrapperBuilder(); 
    ProductCollection products = builder.Products; 
     
    bool isDotNetOnly = true; 
    List<string> productNames = new List<string>(); 
    foreach (ITaskItem bootstrapperPackage in this.BootstrapperPackages) 
    { 
        string productCode = bootstrapperPackage.ItemSpec; 
        bool install = false; 
        bool.TryParse(bootstrapperPackage.GetMetadata(METADATA_INSTALL), out install); 
        if (install) 
        { 
            string productName = productCode; 
            Product product = products.Product(productCode); 
            if (product != null) 
            { 
                productName = product.Name; 
            } 
            productNames.Add(productName); 
 
            if (!productCode.StartsWith(PRODUCT_CODE_DOTNET_PREFIX, StringComparison.OrdinalIgnoreCase) && 
                !productCode.Equals(PRODUCT_CODE_WINDOWS_INSTALLER, StringComparison.OrdinalIgnoreCase)) 
            { 
                isDotNetOnly = false; 
            } 
        } 
    } 
 
    data.Prerequisites = productNames.ToArray(); 
    if (data.Prerequisites.Length > 0 && isDotNetOnly) 
    { 
        data.RuntimeVersion = GetRuntimeVersion(); 
    } 
} 
 
private string GetRuntimeVersion() 
{ 
    string version = "2.0.0"; 
    AssemblyReference dotNet30AssemblyReference = ApplicationManifest.AssemblyReferences.Find(CreateAssemblyIdentity(DOTNET30AssemblyIdentity)); 
    if (dotNet30AssemblyReference != null && dotNet30AssemblyReference.IsPrerequisite) 
    { 
        version = "3.0.0"; 
    } 
    AssemblyReference dotNet35AssemblyReference = ApplicationManifest.AssemblyReferences.Find(CreateAssemblyIdentity(DOTNET35AssemblyIdentity)); 
    if (dotNet35AssemblyReference != null && dotNet35AssemblyReference.IsPrerequisite) 
    { 
        version = "3.5.0"; 
    } 
 
    return version; 
} 
 
private AssemblyIdentity CreateAssemblyIdentity(string[] info) 
{ 
    return new AssemblyIdentity(info[0], info[1], info[2], info[3], info[4]);  
}

Getting the static text is not terribly exciting. There are only two things of note: the text for the "go" button changes depending on whether the application is installed or is online only, and the support information also incorporates the publisher name.

private void WriteStaticText(ref PageData data) 
{ 
    data.BootstrapperText = Properties.Resources.BootstrapperText; 
    if (deployManifest.Install) 
    { 
        data.ButtonLabel = Properties.Resources.InstallButtonLabel; 
    } 
    else 
    { 
        data.ButtonLabel = Properties.Resources.RunButtonLabel; 
    } 
    data.BypassText = Properties.Resources.BypassText; 
    data.HelpText = Properties.Resources.HelpText; 
    data.HelpUrl = Properties.Resources.HelpUrl; 
    data.NameLabel = Properties.Resources.NameLabel; 
    data.PublisherLabel = Properties.Resources.PublisherLabel; 
    data.SupportText = string.Format(CultureInfo.CurrentCulture, Properties.Resources.SupportText, DeployManifest.Publisher); 
    data.VersionLabel = Properties.Resources.VersionLabel; 
}

The last item of note is actually performing the transform, based on either a supplied template or using the default one (read from the task assembly's resources). The input is created by serializing the page data.

private void XmlTransform(PageData data) 
{ 
    if (!string.IsNullOrEmpty(this.OutputFileName)) 
    { 
        // Serialize all of the web page data 
        XmlSerializer serializer = new XmlSerializer(data.GetType()); 
        MemoryStream dataStream = new MemoryStream(); 
        StreamWriter streamWriter = new StreamWriter(dataStream); 
        serializer.Serialize(streamWriter, data); 
        dataStream.Position = 0; 
        XmlReader dataReader = XmlReader.Create(dataStream); 
 
        // Set up the transform 
        XmlDocument stylesheet = new XmlDocument(); 
        if (!string.IsNullOrEmpty(TemplateFileName)) 
        { 
            stylesheet.Load(TemplateFileName); 
        } 
        else 
        { 
            stylesheet.LoadXml(Properties.Resources.PublishPage); 
        } 
        XslCompiledTransform transform = new XslCompiledTransform(); 
        transform.Load(stylesheet); 
 
        // Perform the transform, writing to the output file 
        using (XmlTextWriter outputFile = new XmlTextWriter(this.OutputFileName, Encoding.UTF8)) 
        { 
            outputFile.Formatting = Formatting.Indented; 
            transform.Transform(dataReader, outputFile); 
        } 
    } 
}

<UsingTask  TaskName="CreatePublishWebPage"  AssemblyFile="$(MSBuildExtensionsPath)\\CreatePublishWebPage.dll" /> 
<Target  Name="AfterPublish"> 
  <CreatePublishWebPage  ApplicationManifestFileName="$(_DeploymentApplicationDir)$(_DeploymentTargetApplicationManifestFileName)"  
                          
                        DeploymentManifestFileName="$(PublishDir)$(TargetDeployManifestFileName)"  
                          
                        BootstrapperEnabled="$(BootstrapperEnabled)"  
                          
                        BootstrapperPackages="@(BootstrapperPackage)"  
                          
                        OutputFileName="$(PublishDir)$(WebPage)" /> 
</Target>

The above snippet writes the publish.htm to the app.publish folder under your config's output (e.g. bin\debug\app.publish). The relevant paths were pulled from the Microsoft.common.targets file. It may make sense to add a condition or 2 to the target, taking into account whether or not the build is happening from within Visual Studio (BuildingInsideVisualStudio) as well as whether or not the user wants to generate a publish.htm file (CreateWebPageOnPublish). Unfortunately, it appears the file is not picked up as part of the publish phase, so you may have to transport the file to its final resting place yourself.

I have attached the full project as a to the end of this post.

There was a little bit of change around the web page, specifically the jscript used to detect the framework. I believe the SP behavior around the .NET Framework versions was similar to what was done here, in that the jscript could actually check for 3.0, 3.5, or 3.5 SP1. It seems that the Visual Studio 2008 RTM could only deal with 2.0 of the Framework. The SP also introduced the client version of the .NET Framework. While the jscript code was updated to take that into account, the PageData is not able to properly detect that the cllient framework bootstrapper package is being used, because of the ProductName used by the client bootststrapper package. Unfortunately, I can't remember for sure, and of course the SP 1 install from MSDN doesn't seem to work on my laptop.

CreatePublishWebPage.zip

One great thing about ClickOnce applications is that the deployment model is very declarative: simply by looking at an XML file, you can earn all sorts of things about the installation. Have you ever tried looking at an MSI file? It's pretty complicated. And that's not a knock: it's complicated because it has to be (okay, maybe a small knock). One of the items in the ClickOnce manifest are "pre-requisite assemblies", which are expressed as a preRequisite assembly dependency:

<dependency> 
  <dependentAssembly dependencyType="preRequisite" allowDelayedBinding="true"> 
    <assemblyIdentity name="ClassLibrary1" version="1.0.0.0" publicKeyToken="F10848788BBE80F6" language="neutral" processorArchitecture="msil" /> 
  </dependentAssembly> 
</dependency>

This is stating that the application requires a specific strongly-named assembly (ClassLibrary1) in order to run. Especially noteworthy is the "dependencyType" attribute: a value of "preRequisite" means that the stated dependency must be available on the machine in order for the ClickOnce application to run. More succinctly, the assembly has to be installed to the global assembly cache. How to get the assembly into the cache is your problem.

Consider the following fragment, which I took out of an application manifest that targets the 2.0 framework. For the simple application I created, this is the only prerequisite assembly listed.

<dependency> 
  <dependentAssembly dependencyType="preRequisite" allowDelayedBinding="true"> 
    <assemblyIdentity name="Microsoft.Windows.CommonLanguageRuntime" version="2.0.50727.0" /> 
  </dependentAssembly> 
</dependency>

This is the one assembly dependency that breaks the rules. First of all, what is this assembly? There isn't anything in the GAC called Microsoft.Windows.CommonLanguageRuntime! Well, this particular assembly dependency is basically a code to the ClickOnce runtime engine saying that the 2.0 CLR needs to be installed in order to run the application (I won't bother to mention that this seems a little strange: since the ClickOnce runtime engine is reading the file, and the engine is only installed as part of the 2.0 Framework, it stands to reason the 2.0 CLR is there. Okay, I guess I will bother to mention it.).

Another thing to notice: why is this the only dependency listed? My application has a reference to System.dll and System.Windows.Forms.dll, so shouldn't these be listed as well? The answer: probably. But as part of the manifest generation the references that are redistributed with parts of the .NET Framework are stripped from the manifest. All of the references which are installed with the 2.0 framework are replaced with this one, because we take it on faith that if this one assembly is installed, all of the assemblies from that .NET Framework version are also installed. This one assembly has a special name: the "sentinel assembly".

When Visual Studio 2008 and its multi-targeting features came out, the sentinel assembly pattern was continued. When targeting the 3.0 Framework, the 3.0 assembly references are covered by the "WindowsBase" sentinel:

<dependentAssembly dependencyType="preRequisite" allowDelayedBinding="true"> 
  <assemblyIdentity name="WindowsBase" version="3.0.0.0" publicKeyToken="31bf3856ad364e35" language="neutral" processorArchitecture="msil" /> 
</dependentAssembly>

Targeting the 3.5 framework used the "System.Core" sentinel:

<dependentAssembly dependencyType="preRequisite" allowDelayedBinding="true"> 
  <assemblyIdentity name="System.Core" version="3.5.0.0" publicKeyToken="b77a5c561934e089" language="neutral" processorArchitecture="msil" /> 
</dependentAssembly>

The GenerateApplicationManifest task figures out which sentinel assembly to write based on a project property: the TargetFrameworkVersion property, which has an expected value of 2.0, 3.0, or 3.5. It does not use project references; within the project system, it's this framework version property which dictates the references that can be added to the appliction.

This brings us to Visual Studio 2008 SP1. When we first started planning for ClickOnce tooling for the service pack, it was obvious there would be the need for a new sentinel assembly. Once we heard the ginormous new set of features being added to the .NET Framework, we assumed there would be a whole new framework version. We were told there wouldn't be: the new feature set would be billed as a 3.5 "service pack", with the features being added into existing assemblies or entirely new assemblies.

Well, surely there will be a new "TargetFrameworkVersion" property the project system so that the manifest generation knows which set of sentinel assemblies to write into the manifest. Afraid not: the team that owned that property didn't have time to add a new option.

Okay, how about if we decide to always write out the 3.5 SP1 sentinel assembly? We were told that was fine: and there's even a good sentinel assembly to write out:

<dependentAssembly dependencyType="preRequisite" allowDelayedBinding="true"> 
  <assemblyIdentity name="System.Data.Entity" version="3.5.0.0" publicKeyToken="b77a5c561934e089" language="neutral" processorArchitecture="msil" /> 
</dependentAssembly>

With that sentinel assembly decision out of the way, we decided to focus on adding tooling support for the 3.5 features that we missed, and were being added to the 3.5 SP1. These features are:

• File Associations: I already wrote about this, but we added UI support for file associations.
• Exclude deployment provider: When this options is checked, manifest generation will NOT include the deploymentProvider tag when it would under "normal" circumstances. This was supported in the VS 2008 product, but there was no UI for it.

• Suite Name: Places the start menu shortcut into a sub-folder. I think the goal of this one was to create a means for grouping similar applications into the same start menu folder, like Microsoft Office.
• Error URL: Specifies the web page a user will be sent to if the installation of an application fails. My 2 cents: while I understand the ClickOnce team's heart was in the right place, I think this feature could have been executed better. At the very least, I would have liked to have seen 2 additions to this feature:
  1. A published web page template that would show reasonable help for some of the more common installation errors (something like the generated publish.htm, except about 1000 times more complicated)
  2. Including the application identity for the failed installation
• Create desktop shortcut: Adds a shortcut to the desktop for the application that is being installed. A lot of people like this, a lot of people don't (I fall into the latter). But its nice to have the option.
• Optional hashing: In the past, a file deployed with the application included a hash of the file when it was published. The hash was included for 2 reasons. Security: to make sure that the file that was published was consistent with the file that was downloaded. Updates: If ClickOnce is installing an update, downloading of a file would be skipped if the hash values for the old application and the new application were the same. Excluding a hash means that you can change a file post-publish. A potentially useful feature; I'm curious to hear if people modify files other than the .exe.config file.
• Optional Signing: In the past, ClickOnce manifests needed to be signed in order to install. That restriction has been removed. Note that if a hash has been excluded, the manifests can not be signed. Publishing still defaults to signing the manifests, but once an application has been published, it is possible to turn off this feature (yes, this means you have to publish twice. We are sorry).

Of course, all of this required a new and improved publish options page: the old one was getting too crowded. The available properties were re-grouped into a format similar to what's in Tools: Options.

While the next set of features weren't added by the ClickOnce tooling team, they do affect ClickOnce published applications:

• .NET Framework Client Profile: Publishing your Client Profile application adds additional information into the manifest to make sure that it can run on either the full 3.5 SP1 or the .NET Framework Client Profile. The profile includes all of the new 3.5 SP1 ClickOnce enhancements. I see how this profile might be a wonderful idea, but unfortunately additional tooling support is required to turn this into a nice experience.The good news: I'll probably get another blog post out of this.
• Additional Bootstrapper Packages: Bootstrapper packages have been added for the full 3.5 SP1, the client profile, Visual Basic Power Packs (1.2), and Visual Studio Tools for Office. The bootstrapper for SQL Server Express 2008 is available when you install VB or C# Express.

• Publishing WPF applications: In VS 2008, strange errors may crop up when publishing a WPF application: "...g.i.cs file can not be found".
• Update to publish.htm: The javascript detection that is in place for detecting .NET Framework 2.0 of your application has been expanded to include .NET 3.0 and 3.5 SP1
• XML Serializer assemblies are now published with the application: I wrote a blog post about this one, too. No need to use this work-around.

After all of this work was done, the tooling team was told that it was no longer acceptable to target 3.5 SP1 by default. Instead, when pulishing the application, the manifest generation tasks should be smart about this and only include the 3.5 SP1 sentinel assembly when it is "necessary". Unfortunately, because of how the service pack is constructed it is very difficult for manifest generation to know whether or not 3.5 SP1 is necessary. At manifest generation time, the relevant tasks deal only with project references, files, and ClickOnce properties. Manifest generation has no idea what a user is doing with those references, it only know the names of the references. And because 3.5 SP1 features were added to existing (2.0, 3.0, and 3.5) Framework assemblies, it isn't possible to base the sentinel addition on the referenced assembly list. This is why the a hack was settled upon: if your application requires 3.5 SP1, you should explicitly reference System.Data.Entity.dll. The manifest generation tool will understand what this means, and will add this sentinel assembly into the manifest file. Manifest generation will also (silently) add the 3.5 SP1 sentinel assembly if your application uses features only available in the 3.5 service pack.

Sub ListAll() 
    For Each proj As Project In DTE.Solution.Projects 
        Dim groupInfo As New StringBuilder() 
        If proj.ConfigurationManager IsNot Nothing Then 
            For Each group As OutputGroup In proj.ConfigurationManager.ActiveConfiguration.OutputGroups 
                groupInfo.AppendLine(String.Format("{0}: {1} ({2})", group.CanonicalName, group.DisplayName, group.FileCount)) 
            Next 
            MsgBox(groupInfo.ToString(), MsgBoxStyle.OkOnly, proj.Name) 
        End If 
    Next 
End Sub

The results for a very basic Winform Application is shown below:

It is a design limitation decision that ClickOnce projects are capable of publishing all of these output groups from its own project, but if you want the content, source, symbols, or documentation files from a different project in the solution, you are just plain out of luck. However, if you are willing to modify your project file just a little bit, your luck has just changed. Let's build upon an entry from last month and have a ClickOnce project publish output from other projects.

Its not well advertised, but there are Targets within Microsoft.Common.targets which expose the output groups of a project. For example, here is the Target which exposes the Content Files output group:

<Target 
            Name="ContentFilesProjectOutputGroup" 
            Outputs="@(ContentFilesProjectOutputGroupOutput)" 
            DependsOnTargets="$(ContentFilesProjectOutputGroupDependsOn)"> 
 
    <!-- Convert items into final items; this way we can get the full path for each item. --> 
    <ItemGroup> 
        <ContentFilesProjectOutputGroupOutput Include="@(ContentWithTargetPath->'%(FullPath)')"/> 
    </ItemGroup> 
</Target>

It would be tempting to simply add this Target as a dependency to the BeforePublish target used in the project file. However, doing so would get the contents of this project, not some other project. What we really need is to run MSBuild on a different project, call this target, and consume that target's outputs. And MSBuild has a way to do exactly that: The MSBuild task.

<ItemGroup> 
    <PublishPOG Include="..\\ClassLibrary1\\ClassLibrary1.vbproj"> 
        <Visible>false</Visible> 
        <OutputGroup>DebugSymbolsProjectOutputGroup</OutputGroup> 
    </PublishPOG> 
    <PublishPOG Include="..\\ClassLibrary2\\ClassLibrary2.vbproj"> 
        <Visible>false</Visible> 
        <OutputGroup>ContentFilesProjectOutputGroup</OutputGroup> 
    </PublishPOG> 
</ItemGroup> 
<Target Name="BeforePublish"> 
    <Touch Files="@(IntermediateAssembly)" /> 
    <MSBuild Projects="%(PublishPOG.Identity)"  Targets="%(OutputGroup)"> 
        <Output TaskParameter="TargetOutputs"  ItemName="_DeploymentManifestFiles" /> 
    </MSBuild> 
</Target>

This change consumes the outputs of two different projects: the debug symbols from ClassLibrary1 and the content files from ClassLibrary2 (why anyone would want to publish the pdbs of another project is left as an exercise to the reader). This information is stored as an item with identity of the project to build and the output group to consume. BeforePublish then calls the MSBuild task to append the outputs onto the _DeploymentManifestFiles item, which is consumed by the GenerateApplicationManifest task (amongst others). So, which outputs are available for consumption? Here is a handy chart for reference:

Note that the satellite dlls, serialization assemblies, and primary output of another project are generally included simply by adding a reference to that other project. But if you do go down this route for these output types, you should append the output to the _DeploymentManifestDependencies item instead of _DeploymentManifestFiles.

All of this talk of "output groups" and "ClickOnce" naturally (I think) leads to another question. I don't want to ask it because I don't want to answer it (right now). But if someone wants to ask, feel free to leave a comment. Its a question I want to answer with a later post, but we'll see if it happens.

• Expose the web service methods through a partner Class Library, and take a reference on that Class Library
• Make some modifications to Microsoft.Common.targets

In fact there is an easier way, which is similar to my last blog post. By adding the following information to your project file, the XmlSerializers assembly will start getting published with your application:

<Target Name="BeforePublish"> 
  <CreateItem Include="%(SerializationAssembly.FullPath)" Condition="'%(Extension)' == '.dll'"> 
    <Output TaskParameter="Include" ItemName="_SGenDllsRelatedToCurrentDll" /> 
  </CreateItem> 
</Target>

Once again, BeforePublish is pre-populating some items to include some information for the ClickOnce manifest generation. In this case, the _SGenDllsRelatedToCurrentDll items are used by the ResolveManifestFiles task to figure out what should be published. The definition of SGenDllsRelatedToCurrentDll in Microsoft.Common.targets only picks up on SGen Dlls from referenced projects, but misses the XmlSerializers from the exe project (which is why the first work-around mentioned above will work). Making this change allows the XmlSerializers to be picked up, and you can even set properties on them in the Application Files dialog.

Note: This problem existed in both VS 2005 and VS 2008. This work-around doesn't work for VS 2005 (so far, I haven't been able to come up with something that didn't require modifying Microsoft.Common.targets (or re-defining GenerateApplicationManifest target)). Furthermore, this issue is fixed in VS 2008 SP1 (to be precise: it is fixed in .NET Framework 3.5 SP1). The fix taken in there is basically what I showed here: Including the SerializationAssembly in the _SGenDllsRelatedToCurrentDll items.

This wouldn't be an issue if the ClickOnce project were able to deal with Project Output Groups like a setup project can. Hopefully I will get to that in a later post, but for now let's keep it a little more simple: is there some way to include all of the files in a given directory in the ClickOnce publish? This is, after all, how mage operates. The answer is "yes", if you are willing to make some by-hand modifications to a project file. I won't be dealing with assemblies in this post; the need to do so isn't as pressing: I think it's more rare for an application to require a lot of assemblies as references that aren't adequately addressed with the current system for dealing with references. Indeed, you can think of project-to-project references as similar to project output groups, and other references match the "link" analogy, as references are not copied locally and then dealt with statically by the project system. Instead, I want to focus on how those assemblies which may require their own content files can make sure those are deployed with the ClickOnce application.

Let's get started by exploring how information from the application files dialog makes the journey to what gets written into the application manifest. For those of you who want to play along at home, I created a solution containing a Windows Forms Application and 2 class library projects. I also added 5 text files to a sub-folder of the WinForms project, one of which was added as a link. I changed a bunch of settings in the application files dialog, like this:

Viewing the contents of the project file, we see this:

<ItemGroup> 
  <PublishFile Include="ClassLibrary1"> 
    <Visible>False</Visible> 
    <Group></Group> 
    <PublishState>Include</PublishState> 
    <TargetPath></TargetPath> 
    <FileType>Assembly</FileType> 
  </PublishFile> 
  <PublishFile Include="ClassLibrary2"> 
    <Visible>False</Visible> 
    <Group></Group> 
    <PublishState>Prerequisite</PublishState> 
    <TargetPath></TargetPath> 
    <FileType>Assembly</FileType> 
  </PublishFile> 
  <PublishFile Include="NewFolder1\\TextFile2.txt"> 
    <Visible>False</Visible> 
    <Group>Foo</Group> 
    <PublishState>Auto</PublishState> 
    <TargetPath></TargetPath> 
    <FileType>File</FileType> 
  </PublishFile> 
  <PublishFile Include="NewFolder1\\TextFile3.txt"> 
    <Visible>False</Visible> 
    <Group></Group> 
    <PublishState>Exclude</PublishState> 
    <TargetPath></TargetPath> 
    <FileType>File</FileType> 
  </PublishFile> 
  <PublishFile Include="NewFolder1\\TextFile4.txt"> 
    <Visible>False</Visible> 
    <Group>Foo</Group> 
    <PublishState>DataFile</PublishState> 
    <TargetPath></TargetPath> 
    <FileType>File</FileType> 
  </PublishFile> 
  <PublishFile Include="NewFolder1\\TextFileLink.txt"> 
    <Visible>False</Visible> 
    <Group></Group> 
    <PublishState>Include</PublishState> 
    <TargetPath></TargetPath> 
    <FileType>File</FileType> 
  </PublishFile> 
</ItemGroup>

All sorts of observations can be made:

• Application File items are stored as Items with name "PublishFile"
• The Include value is the name of the file in the application files dialog
• If a metadata value is in the default state, it is generally left blank
• If the entire item is in a default state, there is no entry for it in the project file (see TextFile1.txt for example)
• There are 5 different metadata values for the PublishFile item
1. Visible, which determines whether or not the Item appears in the solution explorer (always "False" because all of these have different representations within the project file)
2. Group, which corresponds to the Download Group in the application files dialog
3. PublishState, which corresponds to how the file is distributed. There appear to be 5 different values
• (Auto): The file is in its default state
• Include: The file will be published with the project
• Exclude: The file will NOT be published with the project
• DataFile: The file will be published as a data file
• Prerequisite: The assembly will not be published with the application, but will be written into the manifest as a prerequisite
4. TargetPath, which corresponds to the location relative to the application manifest the file will be published to (this is value is not settable through the application files dialog)
5. FileType, which describes what kind of file this is
• Assembly
• File

Now that we have some idea of how files are included in output, let's see how they are applied by MSBuild. To do that, we start by opening Microsoft.Common.targets. Performing a search for @(PublishFile), we see the following entry:

<!-- Create list of items for manifest generation --> 
<ResolveManifestFiles 
                EntryPoint="@(_DeploymentManifestEntryPoint)" 
                ExtraFiles="@(_DebugSymbolsIntermediatePath);$(IntermediateOutputPath)$(TargetName).xml;@(_ReferenceRelatedPaths)" 
                Files="@(ContentWithTargetPath);@(_DeploymentManifestIconFile);@(AppConfigWithTargetPath)" 
                ManagedAssemblies="@(_DeploymentReferencePaths);@(ReferenceDependencyPaths);@(_SGenDllsRelatedToCurrentDll)" 
                NativeAssemblies="@(NativeReferenceFile);@(_DeploymentNativePrerequisite)" 
                PublishFiles="@(PublishFile)" 
                SatelliteAssemblies="@(IntermediateSatelliteAssembliesWithTargetPath);@(ReferenceSatellitePaths)" 
                TargetCulture="$(TargetCulture)"> 
 
    <Output TaskParameter="OutputAssemblies"  ItemName="_DeploymentManifestDependencies"/> 
    <Output TaskParameter="OutputFiles"  ItemName="_DeploymentManifestFiles"/> 
 
</ResolveManifestFiles>

This ResolveManifestFiles task takes all sorts of information (including PublishFile items). It returns the OutputAssemblies and OutputFiles as _DeploymentManifestDependencies and _DeploymentManifestFiles items, respectively. These items are then used by the GenerateApplicationManifest and a pair of Copy tasks within the _CopyFilesToPublishFolder target. Before we latch onto these values to publish files not in the project, let's see what sort of metadata the items carry along.

You could write your own task to figure this out, or you could take my word for it: here is the relevant metadata names for _DeploymentManifestFiles:

• Group
• TargetPath
• IsDataFile

It's a similar group to what was written for PublishFile items. It appears that (for files) PublishState was used mapped to IsDataFile by the ResolveManifestFiles task. The FileType metadata was used used to break all PublishFile items into the assemblies and files group.

Let's check out the metadata values from these names. Let's modify the winform project file to display all of this metadata. Unload the project within Visual Studio and edit it with the following info:

<Target Name="AfterPublish"> 
  <Message Text="_DeploymentManifestFiles (Identity=%(_DeploymentManifestFiles.Identity))
\tab Group=%(_DeploymentManifestFiles.Group)
\tab TargetPath=%(_DeploymentManifestFiles.TargetPath)
\tab IsDataFile=%(_DeploymentManifestFiles.IsDataFile)" /> 
</Target> 
</Project>

After publishing, the output window shows (amongst other things):

_DeploymentManifestFiles (Identity=..\..\..\..\TextFileLink.txt)
    	Group=
    	TargetPath=NewFolder1\TextFileLink.txt
    	IsDataFile=false
_DeploymentManifestFiles (Identity=NewFolder1\TextFile1.txt)
    	Group=
    	TargetPath=NewFolder1\TextFile1.txt
    	IsDataFile=false
_DeploymentManifestFiles (Identity=NewFolder1\TextFile2.txt)
   	Group=Foo
    	TargetPath=NewFolder1\TextFile2.txt
    	IsDataFile=false
_DeploymentManifestFiles (Identity=NewFolder1\TextFile4.txt)
    	Group=
    	TargetPath=NewFolder1\TextFile4.txt
    	IsDataFile=true

So to add additional files to our output, we need only figure out how to generate new _DeploymentManifestFiles items. It turns out this is easy enough. Consider the following piece of information written into the project file:

<ItemGroup> 
  <AdditionalPublishFile Include="C:\\Documents and Settings\\mwade\\My Documents\\My Pictures\\*.jpg"> 
    <Visible>False</Visible> 
  </AdditionalPublishFile> 
</ItemGroup> 
<Target Name="BeforePublish"> 
  <Touch Files="@(IntermediateAssembly)" /> 
  <CreateItem Include="@(AdditionalPublishFile)" AdditionalMetadata="TargetPath=%(FileName)%(Extension);IsDataFile=false"> 
    <Output TaskParameter="Include" ItemName="_DeploymentManifestFiles" /> 
  </CreateItem> 
</Target>

These statements take all of the jpg files in my My Pictures directory, stores each item in a AdditionalPublishFile. Then as part of BeforePublish target, the PublishDirectoryFile are used (via the CreateItem task) to pre-populate the _DeploymentManifestFiles items. The CreateItem task sets the necessary metadata for _DeploymentManifestFiles: TargetPath, Group, and IsDataFile. The Touch task is used to make sure that GenerateApplicationManifest task is re-run as part of the publish process. Touch modifies the write time of the primary executable. This file is an input to the GenerateApplicationManifest task, and with a write time later than the write time of the application manifest (the task output), MSBuild will not skip the task. Publishing the project shows that these files are indeed written into the application manifest. Furthermore, the publishing service makes sure these files are published to the remote server. You can use your own MSBuild magic to include which ever files you want to include.

One thing to note: I have only tested this on VS 2008, and I don't know how well things will work on Visual Studio 2005. My expectation is that the manifest generation should be basically the same; however, its possible the files will not be automatically published with the application.

One final note: strictly speaking, MSBuild guidelines indicate that things which begin with "_" are supposed to indicate that the things are not for public consumption. So, we could take the approach of re-defining the Publish tasks to enable this scenario (and we could get that to work), but that would involve re-defining targets which are also considered "private" because they start with "_" as well. So either way, we're doing something we shouldn't; taking this approach will definitely be the easiest route.

Displaying publish properties and values

Let's start by viewing all available publishing properties. Before going too far, let's show some helper functions to accomplish our tasks. Here is some code I copied from my macro explorer:

Function GetPublishProperties() As EnvDTE.Properties
    Dim proj As Project = DTE.Solution.Projects.Item(1)
    If proj Is Nothing Then
        ShowError("Unable to retrieve a project", "GetPublishProperties")
        Return Nothing
    End If

    Dim publishProperty As EnvDTE.Property = proj.Properties.Item("Publish")
    If publishProperty IsNot Nothing Then
        Dim publishProperties As EnvDTE.Properties = TryCast(publishProperty.Value, EnvDTE.Properties)
        Return publishProperties
    End If

    ShowError("Unable to get publish properties of project " & proj.Name, "GetPublishProperties")
    Return Nothing
End Function

Sub ShowError(ByVal message As String, ByVal title As String)
    MsgBox(message, MsgBoxStyle.Exclamation Or MsgBoxStyle.OkOnly, title)
End Sub

Sub ShowException(ByVal ex As Exception, ByVal methodName As String)
    Dim message As String = ex.Message
    If ex.InnerException IsNot Nothing Then
        message = ex.InnerException.Message
    End If
    ShowError(message, methodName)
End Sub

GetPublishProperties is a function to retrieve the object which contains the publish properties. It grabs the first project in the solution, and selects the "Publish" property from there. Next, the resultant property value is converted to another properties container. Some error handling is also included (although probably not enough).

With that as a baseline, this macro will show all of the publish properties, types, and values:

Sub ShowPublishProperties()
    Dim publishProperties As EnvDTE.Properties = GetPublishProperties()
    If publishProperties IsNot Nothing Then
        Dim sb As New System.Text.StringBuilder()
        For Each prop As EnvDTE.Property In publishProperties
            sb.Append(String.Format("{0} [{1}]: {2}", prop.Name, prop.Value.GetType().ToString(), prop.Value.ToString()))
            sb.Append(vbCrLf)
        Next
        MsgBox(sb.ToString())
    End If
End Sub

This macro simply iterates through all of the publish properties, gathers the property names, types, and values and show them all in a message box. Here is a subset of the output:

PublisherName [System.String]: 
OpenBrowserOnPublish [System.Boolean]: True
BootstrapperComponentsLocation [System.Int32]: 0
PublishFiles [System.__ComObject]: System.__ComObject

Most of the values are strings, ints, or booleans. If you were to look in the project file, you would see that these values correspond to properties within the file. The exception are PublishFiles and BootstrapperPackages, which correspond to the Items in the project file, as well as the the lists within the Application Files dialog and Prerequisites dialog. These will be explored further in a bit. But first, let's try setting some easy values.

Setting Property values

Setting a value is as easy as reading a value. For example, to set the PublisherName property, one could write a macro like this:

Sub SetPublisherName()
    Dim publishProperties As EnvDTE.Properties = GetPublishProperties()
    If publishProperties IsNot Nothing Then
        Dim publisherNameProperty As EnvDTE.Property = publishProperties.Item("PublisherName")
        publisherNameProperty.Value = "Test Value"
    End If
End Sub

Some properties perform validation when the values are set. For example, the PublishUrl:

Sub SetPublishUrl()
    Dim publishProperties As EnvDTE.Properties = GetPublishProperties()
    If publishProperties IsNot Nothing Then
        Try
            publishProperties.Item("PublishUrl").Value = ""
        Catch ex As Exception
            ShowException(ex, "SetPublishUrl")
        End Try
    End If
End Sub

In the above example, an attempt is made to blank out the PublishUrl property. However, the PublishUrl can not be set to an empty string, as the thrown exception indicates:

An empty string is not allowed for property 'Publish Location'.

The thrown message uses "Publish Location" because that is what the label for the text box which corresponds to this property uses. In fact, the property page is pretty much setting this property in the exact same manner as the macro.

Modifying Items

There are 2 different types of Items exposed by the Publish

Sub ListFiles()
    Dim publishProperties As EnvDTE.Properties = GetPublishProperties()
    If publishProperties IsNot Nothing Then

        Dim filesObject As Object = publishProperties.Item("PublishFiles")
        If filesObject Is Nothing Then
             ShowError("Could not get PublishFiles object", "ListFiles")
            Return
        End If

        Try
            Dim numFiles As Integer
            numFiles = filesObject.Value.Item("Count").Value
            Dim sb As New System.Text.StringBuilder()
            For i = 0 To numFiles - 1
                'display file name and publish status.
                sb.AppendLine("File Name=" & filesObject.Object.Item(i).Name & ", Status=" & filesObject.Object.Item(i).PublishStatus)
            Next
            MsgBox(sb.ToString(), MsgBoxStyle.DefaultButton1, "Application Files")
        Catch ex As Exception
            ShowException(ex, "ListFiles")
        End Try
    End If
End Sub

This macro relies on latebinding in doing its work: filesObject is declared as Object, yet it uses properties from that object. The filesObject.Object contains an accessor to a collection; there are actually 2 ways to get a value out of the collection: one could use either a string to get a file by name, or an index, like what was done above. Here is some sample output from running this macro:

File Name=WindowsApplication2.exe, Status=0 
File Name=WindowsApplication2.pdb, Status=0 
File Name=WindowsApplication2.xml, Status=0 

The "Status" of the file corresponds to the Publish Status column in the Application Files dialog. 0 corresponds to the "(Auto)" value.

Accessing the bootstrapper packages is similar:

Sub IncludeAllPrerequisites()
    Dim publishProperties As EnvDTE.Properties = GetPublishProperties()
    Dim bootstrapperPackages As Object = publishProperties.Item("BootstrapperPackages")
    If bootstrapperPackages IsNot Nothing Then
        Dim numPackages As Integer = bootstrapperPackages.Value.Item("Count").Value
        For i As Integer = 0 To numPackages - 1
            bootstrapperPackages.Object.Item(i).Install = True
        Next
    End If
End Sub

Sub ExcludeWindowsInstaller31()
    Dim publishProperties As EnvDTE.Properties = GetPublishProperties()
    Dim bootstrapperPackages As Object = publishProperties.Item("BootstrapperPackages")
    If bootstrapperPackages IsNot Nothing Then
        Dim windowsInstaller31Package As Object = bootstrapperPackages.Object.Item("Microsoft.Windows.Installer.3.1")
        If windowsInstaller31Package IsNot Nothing Then
            windowsInstaller31Package.Install = False
        End If
    End If
End Sub

Publishing via a macro

Finally, just like it is possible to build from a macro, it is possible to publish as well. Here is an example that does something similar to what the Publish Now button does on the Publish property page:

Sub Publish()
    Dim proj As Project = DTE.Solution.Projects.Item(1)
    Dim sb2 As EnvDTE80.SolutionBuild2 = CType(DTE.Solution.SolutionBuild, EnvDTE80.SolutionBuild2)
    Dim config2 = CType(sb2.ActiveConfiguration, EnvDTE80.SolutionConfiguration2)
    Dim configName = String.Format("{0}|{1}", config2.Name, config2.PlatformName)
    sb2.BuildProject(configName, proj.UniqueName, True)
    sb2.PublishProject(configName, proj.UniqueName, True)
End Sub

About the package: The package exposes an editor to work with file associations in the app.manifest file, as I wrote about in an earlier post. The editor tries to provide some error and warning feedback to cover the cases I mentioned in that post.

Installing the package: A link is provided at the bottom of the post to install the package.

Launching the editor: To bring up the editor, bring up the context menu of a ClickOnce publishable project, and select "Edit File Associations...". The menu item should only be available for ClickOnce applications. The menu item is disabled for other project flavors; I couldn't figure out how to make a menuitem invisible (one would think setting the .Visible property to false would do it, but you would be sadly mistaken).

 About the Editor: Here's a screen shot of the editor. I'll go into the pieces below.

Grid: Sets the 4 values required for file associations. Editing is done in-place, but new items must be added via the New button. Errors and tool tips appear when an invalid value is set in the grid.

New button: Adds a new row to the grid, with some default values.

Delete button: Deletes a row from the grid.

Warning: Appears if some project properties would prevent the installation of the file associations from being valid.

Feedback/Updates: I imagine there are a few problems with the package. If you have issues, please add a comment, and I'll try to update when I can.

FileAssociationsSetup.msi

Adding File Associations to Your ClickOnce Manifest

File associations are adding to your ClickOnce manifest by specifying the fileAssociation tag and it's 4 attributes:  extension, description, progid, and defaultIcon. This new tag is in the clickonce.v1 namespace. So, one example looks like this:

<fileAssociation xmlns="urn:schemas-microsoft-com:clickonce.v1"
    extension=".mwade"
    description="MWadePad Document"
    progid="MWadePad.Document"
    defaultIcon="mwade.ico"
/>

A little background information about all of these:

• extension: This is the file extension for which your application will be associated. You should make sure that your extension adds the "." to the front of the file. You should aim to use a unique extension for your file association. If, at install time, ClickOnce determines that this file association is already being used, it won't add the necessary system information to register your file association.
• description: A brief statement describing the type of document. This appears in the tooltip when hovering over the document, as well as the Type column in explorer when looking at the document.
• progid: Helps tie the file extension to your ClickOnce application.
• defaultIcon: The icon file from the ClickOnce application to use as the document icon

Of course, adding file association information to your application manifest is only half of the battle. How can you tell if your application was launched by launching one of its documents? Well, this information is stored in the ActivationData of the current app domain:

AppDomain.CurrentDomain.SetupInformation.ActivationArguments.ActivationData[0]

Even if the application is activated through file association, the standard ClickOnce update servicing will be applied.

Adding File Associations through Visual Studio

There is no fancy UI to allow you to add file associations to your ClickOnce application in Visual Studio. It is also not possible to add the information to your application manifest after publishing, because that would invalidate the signature. So, does that mean you are forced to modify your manifest and then re-sign with mage after publishing?

Nope. When publishing in Visual Studio, it is possible to add a app.manifest file to your project. This app.manifest acts as an base application manifest, whose information gets added into the generated application manifest. The manifest can be added by clicking the "Enable ClickOnce Security Settings" checkbox on the Security property page.

For example, here is what my app.manifest file looks like when adding the information from above:

<?xml version="1.0" encoding="utf-8"?>
<asmv1:assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1" xmlns:asmv1="urn:schemas-microsoft-com:asm.v1" xmlns:asmv2="urn:schemas-microsoft-com:asm.v2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <assemblyIdentity version="1.0.0.0" name="MyApplication.app" />
  <trustInfo xmlns="urn:schemas-microsoft-com:asm.v2">
    <security>
      <applicationRequestMinimum>
        <PermissionSet class="System.Security.PermissionSet" version="1" Unrestricted="true" ID="Custom" SameSite="site" />
        <defaultAssemblyRequest permissionSetReference="Custom" />
      </applicationRequestMinimum>
    </security>
  </trustInfo>

  <fileAssociation xmlns="urn:schemas-microsoft-com:clickonce.v1"
      extension=".mwade"
      description="MWadePad Document"
      progid="MWadePad.Document"
      defaultIcon="mwade.ico"
  />

</asmv1:assembly>

Additional Notes

There are some rules and regulations that need to be pointed out for file associations in ClickOnce:

• Values must be given for all 4 xml attributes
• File associations only work for pure ClickOnce applications. That means that browser-hosted applications and Office documents can't take advantage
• The application must be targeting the 3.5 version of the .NET Framework
• The application must be full trust
• The application must be installed (not run from web)
• There is a limit of 8 file associations per application

MWadePad.zip