How to: Specify a Support URL for Individual Prerequisites in a ClickOnce Deployment

As described in Application Deployment Prerequisites, a ClickOnce deployment can test for a number of prerequisites that must be available on the client computer for the ClickOnce application to run. These include the required minimum version of the .NET Framework, the version of the operating system, and any assemblies that must be preinstalled in the global assembly cache (GAC). ClickOnce, however, cannot install any of these prerequisites itself; if a prerequisite is not found, it simply halts installation and displays a dialog box explaining why the installation failed.

There are two methods for installing prerequisites. You can, as explained in the document named above, install them using a bootstrapper application. Alternatively, you can specify a support URL for individual prerequisites, which is displayed to users on the dialog box if the prerequisite is not found. The page referenced by that URL can contain links to instructions for installing the required prerequisite. If an application does not specify a support URL for an individual prerequisite, ClickOnce displays the support URL specified in the deployment manifest for the application as a whole, if it is defined.

While Visual Studio, Mage.exe, and MageUI.exe can all be used to generate ClickOnce deployments, none of these tools directly support specifying a support URL for individual prerequisites. This document describes how to modify your deployment's application manifest to include these support URLs.

Specifying a support URL for an individual prerequisite

1. Open the application manifest for your ClickOnce application in a text editor.

2. For an operating system prerequisite, add the supportUrl attribute to the dependentOS element:

    <dependency>
       <dependentOS supportUrl="http://www.adatum.com/MyApplication/wrongOSFound.htm">
         <osVersionInfo>
           <os majorVersion="4" minorVersion="0" servicePackMajor="0" servicePackMinor="0" />
         </osVersionInfo>
       </dependentOS>
     </dependency>
   

3. For a prerequisite for a certain version of the common language runtime, add the supportUrl attribute to the dependentAssembly entry that specifies the common language runtime dependency:

     <dependency>
       <dependentAssembly dependencyType="preRequisite" allowDelayedBinding="true" supportUrl=" http://www.adatum.com/MyApplication/wrongClrVersionFound.htm">
         <assemblyIdentity name="Microsoft.Windows.CommonLanguageRuntime" version="2.0.40607.0" />
       </dependentAssembly>
     </dependency>
   

4. For a prerequisite for an assembly that must be preinstalled in the global assembly cache, set the supportUrl for the dependentAssembly element that specifies the required assembly:

     <dependency>
       <dependentAssembly dependencyType="preRequisite" allowDelayedBinding="true" supportUrl=" http://www.adatum.com/MyApplication/missingSampleGACAssembly.htm">
         <assemblyIdentity name="SampleGACAssembly" version="5.0.0.0" publicKeyToken="04529dfb5da245c5" processorArchitecture="msil" language="neutral" />
       </dependentAssembly>
     </dependency>
   

5. Once you have manually altered the application manifest, you must re-sign the application manifest using your digital certificate, then regenerate and re-sign the deployment manifest as well. You must use the Mage.exe or MageUI.exe SDK tools to accomplish this task, as regenerating these files using Visual Studio erases your manual changes. For more information on using MageUI.exe to sign and generate manifests, see Manifest Generation and Editing Tool (Mage.exe) and Walkthrough: Deploying a ClickOnce Application Manually.

Security

The support URL is not displayed on the dialog box if the application is marked to run in partial trust.

See Also

Concepts

ClickOnce Deployment and Authenticode
ClickOnce Deployment Overview