Walkthrough: Enabling a ClickOnce Application to Run on Multiple .NET Framework Versions

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

By default, Visual Studio configures ClickOnce applications to install and run on a particular version and profile of the .NET Framework. However, an application can install and run on more than one version of the .NET Framework. This walkthrough describes how to enable a ClickOnce application compiled for the .NET Framework 2.0 to also install and run on either the .NET Framework 2.0 or the .NET Framework 4 Beta 2.

Note

Before enabling your ClickOnce application to run on multiple versions of the .NET Framework, you must completely test your application on each version of the .NET Framework.

Prerequisites

This walkthrough assumes that you have published your .NET Framework 2.0 application previously using Visual Studio.

To create a dual-platform application

1. Start with an existing ClickOnce application that targets the .NET Framework 2.0. For more information, see How to: Target a Specific .NET Framework Version or Profile.

2. If your application does not have an application configuration file in the publish\Application Files\<appname>_<version> directory, add one. The name of the configuration file is the name of the application with a .config extension (<appname>.exe.config). For more information, see Configuration File Schema for the .NET Framework.

3. Open the configuration file (<appname>.exe.config) and add the following code. Windows will run your application on the first available runtime in this list.

   <configuration> 
     <startup> 
       <supportedRuntime version="v4.0" /> 
       <supportedRuntime version="v2.0.50727" /> 
     </startup> 
   </configuration>
   

4. Temporarily remove the .deploy extension for all file names in the publish directory by renaming the files. You will undo these renames later.

   Most ClickOnce deployments append a .deploy extension to some file types.

5. Open the publish\Application Files\<appname>_<version> directory and if there is a copy of the deployment manifest (<appname>.application), delete it. (You can re-copy the master deployment manifest to this directory in the last step.)

6. Use the following command to update the application manifest (<appname>.exe.manifest) to show the details of the new or modified configuration file. To do this, open the Visual Studio command prompt and navigate to the publish\Application Files\<appname>_<version> directory. Run the following command to detect the new configuration file and include it in your application manifest. Replace appname with your application name.

   mage -Update appname.exe.manifest -fd .
   

7. Sign the updated application manifest with the following command. Replace \certs\cert.pfx with the name and location of your certificate file. Replace passwd with the password for your certificate file.

   mage -Sign appname.exe.manifest -CertFile \certs\cert.pfx -Password passwd
   

8. Restore the .deploy extension to all file names renamed in step 4, by renaming these files again.

9. Rename your .config file to <appname>.exe.config.deploy.

10. In the publish directory, open the deployment manifest. For an .exe deployment, the deployment manifest file ends in .application (<appname>.application). Most ClickOnce deployments keep a copy of the deployment manifest for each version, but you need to update the master deployment manifest, usually found in the root of the deployment, along with the setup.exe prerequisite bootstrapper.

11. Find the asmv1:assembly element. For more information, see ClickOnce Deployment Manifest.

12. As a child of the asmv1:assembly element, add a compatibleFrameworks element, containing two framework elements. In the following example, the .NET Framework 2.0 platform is the preferred platform for your application. Replace yourVersion with the version found in the directory name in C:\Windows\Microsoft.NET\Framework.

    <compatibleFrameworks xmlns="urn:schemas-microsoft-com:clickonce.v2">
      <framework targetVersion="2.0" supportedRuntime="2.0.50727" />
      <framework targetVersion="4.0" profile="Full" supportedRuntime="4.0.yourVersion" />
    </compatibleFrameworks>
    

13. Save and close the deployment manifest.

14. In the Visual Studio command prompt, change to the publish directory.

15. Use the following command to update your deployment manifest to reflect all changes.

    mage -Update appname.application -AppManifest "Application Files\appname_1_0_0_3\appname.exe.manifest"
    

16. Sign the updated deployment manifest.

    mage -Sign appname.application -CertFile \certs\cert.pfx -Password passwd
    

17. Optionally, copy the master deployment manifest (publish\<appname>.application) to your version deployment directory (publish\Application Files\<appname>_<version>).

Next Steps

ClickOnce applications that you set to run on either .NET Framework 4 Beta 2 or an earlier version of the .NET Framework must set the group attribute of the <dependentAssembly> element to framework to identify all dependency assemblies within the earlier .NET Framework that are .NET Framework binaries. For more information, see <dependency> Element (ClickOnce Application).

See Also

Reference

<compatibleFrameworks> Element (ClickOnce Deployment)