ClickOnce Changes in Microsoft Visual Studio 2005 Beta 2
Microsoft Corporation
June 2005
Applies to:
ClickOnce
Microsoft Visual Studio 2005 Beta 2
.NET Framework 2005 SDK Beta 2
Summary: This article describes changes made to ClickOnce in Microsoft Visual Studio 2005 Beta 2 and the .NET Framework 2005 SDK Beta 2 since Beta 1 shipped. It is divided into three sections: changes to features; removed features; and known issues that exist in the Beta 2 Release. (16 printed pages)
Contents
Introduction
ClickOnce Features Changed in Beta 2
ClickOnce Features Removed from Beta 2
Known Issues with ClickOnce in Beta 2
Additional Resources
Introduction
The ClickOnce Team has been hard at work since beta 1, incorporating developer feedback and fixing bugs. Functionality and code quality for Beta 2 are very good. Keeping the known issues in mind, developing and deploying ClickOnce applications using Beta 2 should be a straightforward process.
If you do find issues, you can send them directly to the ClickOnce team through the MSDN Product Feedback Center website.
ClickOnce Features Changed in Beta 2
System.Deployment Namespace Changes
ClickOnce Types/Members moved to System.Deployment.Application
All ClickOnce types and members previous found in the System.Deployment namespace have been moved to System.Deployment.Application.
Added per method progress events
New per-method progress changed events are listed here.
public event System.ComponentModel.ProgressChangedEventHandler
CheckForUpdateProgressChanged;
public event UpdateProgressChangedEventHandler UpdateProgressChanged;
public event DownloadFileGroupProgressChangedEventHandler
DownloadFileGroupProgressChanged;
Added IsFileGroupDownloaded method
The IsFileGroupDownloaded method checks whether the named file group has been downloaded to the client computer.
public bool IsFileGroupDownloaded(string groupName);
Table 1
| Type | Bool |
| Name | IsFileGroupDownloaded |
| Args | groupName—the named group of files to check for |
| Behavior | Returns true if the specified file group has already been downloaded for the current version of the application. |
| Security | |
| Exceptions | |
| Attributes | |
| Other |
Renamed DownloadFiles methods, events, delegates, etc.
The following methods, events, and delegates have been renamed.
Table 2
| Beta 1 Name | Beta 2 Name |
|---|---|
| DownloadFiles | DownloadFileGroup |
| DownloadFilesAsync | DownloadFileGroupAsync |
| DownloadFilesAsyncCancel | DownloadFileGroupAsyncCancel |
| DownloadFilesCompleted | DownloadFileGroupCompleted |
| DownloadFilesCompletedEventHandler | DownloadFileGroupCompletedEventHandler |
| DownloadFilesCompletedEventArgs | DownloadFileGroupCompletedEventArgs |
Added IsFirstRun property
The IsFirstRun property returns a Boolean indicating whether this is the first time this application has been run on the client computer since being deployed.
public bool IsFirstRun {get;}
Table 3
| Type | Bool |
| Name | IsFirstRun |
| Args | |
| Behavior | Returns true if this is the first time the application has been launched since being installed or updated. |
| Security | |
| Exceptions | |
| Attributes | |
| Other | This property is read-only. |
Removed CancellationPending Flag
The ApplicationDeployment.CancellationPending property has been removed. To detect a cancelled async operation, check the UpdateCompletedEventArgs.Cancelled property.
Tracking Numbers
Bug 320206
Accessing CheckForUpdateCompletedEventArgs may throw an exception
Accessing CheckForUpdateCompletedEventArgs including UpdateAvailable after an update failed or was cancelled may throw an exception. Always check the .Error and .Cancelled properties before accessing other event args.
Rename RunningVersion to CurrentVersion
ApplicationDeployment.RunningVersion has been renamed to ApplicationDeployment.CurrentVersion. The behavior is otherwise unchanged.
Added DataDirectory property
The DataDirectory property returns a sting containing the fully qualified path to the application's data directory in the local machine's ClickOnce cache.
public string DataDirectory {get;}
Table 4
| Type | String |
| Name | DataDirectory |
| Args | |
| Behavior | Returns a sting containing the fully qualified path to the application's data directory in the local machine's ClickOnce cache. |
| Security | Accessing this property requires Full Trust. |
| Exceptions | |
| Attributes | |
| Other | This property is read-only. |
Added Application.Deployment.ActivationUri property
The ActivationUri property is new in Beta 2. The ActivationUri property contains the fully qualified path or URL used to launch the executing application and any parameters passed on startup. ActivationUri is null unless Allow URL parameters to be passed to application is set to true.
The " Allow URL parameters to be passed to application option can be found on the Publish Options dialog box of the Publish tab of the Project Properties dialog box.
public Uri ActivationUri {get;}
Table 5
| Type | Uri |
| Name | ActivationUri |
| Args | |
| Behavior | Returns the fully qualified path or URL to the executing application including any parameters passed on startup. |
| Security | Accessing this property requires Full Trust. |
| Exceptions | |
| Attributes | |
| Other | This property is read-only. |
Publish Tab/Page Changes
"Application activation not possible" message
Clearing the Automatically run application after installing check box on the Publish Options dialog box determines whether or not the application will launch after it has been installed. Clearing this check box, or setting the disallowUrlActivation property in the deployment manifest, will result in the application installing and then prompting the user to launch the application from the Start menu. This is not an error; the dialog message text will be clarified in post-Beta 2 builds.
The Publish Options dialog box is accessed by clicking Options… on the Project Properties Publish tab.
Security Changes
Full Authenticode support
ClickOnce Beta 1 Authenticode support was limited to signing ClickOnce manifests. ClickOnce Beta 2 adds full support for Authenticode including the following capabilities:
- Validating the certificate.
- Validating the certificates usage (for example, for code signing and not SSL, and so on).
- Checking for certificate revocation.
- Validating the certificates TimeStamp.
- Trusted/Untrusted Publisher.
Trusted Publishers
Introduced in Beta 2, Trusted Publishers replace the functionality provided by Trust Licenses in previous builds. ClickOnce applications can require additional security privileges beyond those granted by the current CAS policy. To avoid prompting the user to grant these permissions, ClickOnce applications can be signed by a Trusted Publisher. Configuring a Trusted Publisher requires creating a certificate and installing it the Trusted Publishers store. Additionally, the Issuing Authority of this certificate must have its own certificate in the Trusted Root Certification Authorities store. Once the Trusted Publisher has been configured, all applications signed with this certificate will run with the necessary privileges, without prompting the user.
Note For more information, refer to Configuring ClickOnce Trusted Publishers by Brian Noyes.
Update, UpdateAsync, CheckForUpdate and CheckForUpdateAsync require Full Trust
Calling the Update, UpdateAsync, CheckForUpdate, and CheckForUpdateAsync methods now requires Full Trust. This is a change since Beta 1.
Added GenerateDeploymentManifest.TrustUrlParameters property
Setting TrustUrlParameters to true allows the application to retrieve the entire querystring used to launch the application, including parameters by means of the ActivationUri parameter. By default this parameter is set to false.
Note See the related known issue regarding the ActivationUri parameter.
public bool TrustUrlParameters {get; set;}
Table 6
| Type | Bool |
| Name | TrustUrlParameters |
| Args | |
| Behavior | |
| Security | |
| Exceptions | |
| Attributes | |
| Other |
Added DeployManifest.TrustUrlParameters property
Setting TrustUrlParameters to true allows the application to retrieve the entire querystring used to launch the application, including parameters by means of the ActivationUrl parameter. By default this parameter is set to false.
Note See the related known issue regarding the ActivationUri parameter.
public bool TrustUrlParameters {get; set;}
Table 7
| Type | Bool |
| Name | TrustUrlParameters |
| Args | |
| Behavior | |
| Security | |
| Exceptions | |
| Attributes | |
| Other |
Integration with Microsoft Internet Explorer security settings
ClickOnce now supports Internet Explorer zone-specific security settings for running .NET Framework-reliant code. Upon activating a ClickOnce application, ClickOnce checks the following setting and behaves accordingly.
On the Internet Explorer Internet Options dialog box's Security tab, under .NET Framework-Reliant Components:
- Run components not signed with Authenticode.
If this setting is set to Enabled, then we allow the activation to continue. If it's set to Disabled or Prompt, then we block the activation.
Note The Run components signed with Authenticode setting is ignored.
Limit IE activations to user-only navigation
Only a user-initiated action like clicking a button on a Web page can launch a ClickOnce app, not by means of javascript and so on. The behavior is inline with the Microsoft Windows XP SP2 security changes to Internet Explorer.
Various restrictions on number of files, size of manifest, size of application, etc.
The following limits have been implemented in Beta 2.
Table 8
| MaxNumberOfFilesInApplication | = 24 * 1024; // 24K. |
| MaxNumberOfAssembliesInApplication | = 24 * 1024; // 24K. |
| MaxNumberOfGroupsInApplication | = 48 * 1024; // 48K, |
| MaxLiveActivation | = 8; |
| MaxIdentityLength | = 2 * 1024; // 2K. |
| MaxAppIdLength | = 64 * 1024; // 64K. |
| MaxShortcutFileSize | = 64 * 1024; // 64K. |
| MaxManifestFileSize | = 16 * 1024 * 1024; |
| MaxValueForMaximumAge | = 365; // 365 days. |
Other Changes
.deploy file extension changed to .application
In beta 1, deployment manifests used the .deploy file extension. In Beta 2, the default extension is .application.
Repurposed .deploy file extension
To simplify deployment of ClickOnce applications containing various file types, Beta 2 provides an option to use a common .deploy file extension for all file types except .application and .exe.manifest. Developers then only need to create one MIME type .deploy of type application/octet-stream to allow their application files to be downloaded with IIS. This option is available through the Use .deploy file extension checkbox on the Publish Options dialog box.
Note See related topic in section 6.5.1 regarding creating MIME types on Windows Server 2003.
Added cookie support that allows ClickOnce applications to be installed from websites using forms-based authentication
ClickOnce applications can now be installed from websites which use forms-based authentication. At installation-time, ClickOnce now passes the authentication cookie along with the application and manifest.
New Bootstrapper prerequisite install options
When developing a ClickOnce application, developers can choose to have the VS-generated setup.exe install prerequisites including the .NET Framework, MDAC, and various third-party controls and components. Clicking on the Prerequisites… button on the Publish tab displays the Prerequisites dialog box. This dialog box displays packages available in the Bootstrapper cache on the developer's machine and the following three download options:
Option 1: Download prerequisites from the component vendors website
By selecting this option, the VS-generated setup.exe will be configured to install prerequisites from locations specified in the prerequisite packages themselves. An example of this would be setup.exe installing the .NET Framework from the Microsoft Download Center as opposed to publishing the dotnetfx.exe file to the application deployment site. To use this option, each file specified in the package's product.xml or package.xml file would include a HomeSite attribute containing the location of the file. For an example of this, refer to the .NET Framework 2.0 package in the Bootstrapper cache.
Option 2: Download prerequisites from the same location as my application
This option tells the VS-generated setup.exe to install prerequisites from the same install location as the application. This option reduces setup dependencies by storing all prerequisite packages with the application.
Option 3: Download prerequisites from the following location:
This option allows developers to specify a common location where the VS-generated setup.exe will install prerequisites from. An example where this might useful is an IT-controlled computing environment where specific versions components are tested and mandated across the enterprise. The developer simply enters a path or URL via the Prerequisites dialog and all selected packages will be pulled from the specified location.
For more information on the Generic Bootstrapper or creating packages, refer to the Visual Studio 2005 documentation.
ClickOnce Features Removed from Beta 2
Removed Trust Licenses
Trust Licenses have been replaced by trusted publishers. Application trust for ClickOnce applications is now based on Authenticode signatures from trusted publishers. For more information on Trusted Publishers refer to section 4.3.2.
Note See the related Authenticode section earlier in this article.
Note Trusted Publishers is not supported on Win9x.
Satellite Assembly Support Removed
In Beta 2 and newer builds, developers need to detect changes to client machine culture and use ClickOnce OnDemand APIs to download satellite assemblies.
Known Issues with ClickOnce in Beta 2
This section describes issues with ClickOnce features shipping in Beta 2. Every effort is being made to address these. Keep in mind that final functionality and behavior may change in the final product. For more information on these known issues, refer to Microsoft Visual Studio 2005 Beta 2 Known Issues.rtf.
Publish Tab/Page
Publish operation fails when invoked using the "Publish Now" or "Publish Wizard" buttons on the Publish tab of the project properties designer
After invoking publishing using either the Publish Now or Publish Wizard buttons, the publish operation will fail. The error can vary, for example: "Failed to copy file 'C:\..\setup.exe' to 'https://../setup.exe.' Unable to add 'setup.exe' to the Web. Unable to add file 'setup.exe.' The system cannot find the file specified," or "Publish failed with the following error: Could not find a part of the path 'C:\..\publish\..'"
Work Around:
- Close and reopen the project that is to be published.
- Right-click on the project in the solution explorer, and select Properties.
- In project designer, navigate to the Publish tab. Set properties there as appropriate.
- Right-click on the project in the solution explorer, and select Publish.
Note In general, avoid using the Publish Now or Publish Wizard buttons altogether. Use the Publish command in the context menu in the solution explorer or the Build top-level menu item.
System.Deployment Namespace
Calling UpdateAsync() from within the CheckForUpdateAsyncCompleted Event now works correctly
Beginning with Beta 2, it is now possible to call the UpdateAsync() method from within the CheckForUpdateAsyncCompleted event.
Security
Security tab in of the project properties designer fails after WebBrowserPermission excluded
When editing ClickOnce security settings for a partial trust application, excluding WebBrowserPermission, then saving and reopening the project properties designer causes the following error message to be displayed in the security tab: An error occurred trying to load the page. Bad Xml securityElement.
Work Around:
Save your changes and close the project.
Open the .proj file associated with the project experiencing the problem.
Search for and remove the line:
<ExcludedPermissions>System.Windows.Forms.WebBrowserPermission, System, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</ExcludedPermissions>
Re-open the project
Changing application from full-trust to partial-trust causes application to fail at execution after publishing
When a previously published application is changed from full-trust to partial-trust and published again, the application fails with a runtime error at execution. The error reads: Error: An unexpected error occurred: Failed to grant permission to execute.
Work Around:
- Right-click on the project in the solution explorer and select Properties.
- Select the Security tab on the project properties pane.
- Toggle a property on the page (for example: flip the security zone from Local Intranet to (Custom) and back).
- Publish again.
Calculating permissions on a Visual Basic or Visual J# partial trust application from the Security project designer page causes superfluous permissions to be requested
Description: When run on a Visual Basic partial trust application, the permissions calculator on the Security project designer page may return unnecessary permissions. In particular, those listed below:
- DNSPermission
- SocketPermission
- KeyContainerPermission
- UIPermission
- SecurityPermission
- ReflectionPermission
- EnvironmentPermission
When run on a Visual J# partial trust application, the permissions calculator on the Security project designer page may return superfluous permissions from the list below:
- ReflectionPermission
- SecurityPermission
- UIPermission
Work Around
The application code should be inspected and tested to verify whether these permissions returned by the permissions calculator are actually required by the application.
Importing a key file into a project containing a key file with the same name causes Visual Studio to crash
From the signing page in the project designer, importing a key from a file when the selected key file has the same name as a key file already in the root directory of the project will cause Visual Studio to crash.
Work Around
Prior to importing a key file into a project, ensure that it has a filename that is distinct from the filenames of other key files already in the root directory of the project.
Importing a key file whose password or filename contain surrogate characters into a project causes errors
If a key file has surrogate characters in its filename or a key file is protected by a password that contains surrogate characters, then importing it from the signing page in the project designer will fail. After selecting the file in the File dialog box and entering its password, an error dialog box will appear stating the password entered is invalid.
Work Around
Ensure that key files that are imported into the project through the signing page do not have surrogate characters in their filenames, and that they are not protected by passwords that contain surrogate characters.
Munged text in the bottom of the security dialog box
When installing a ClickOnce application, a security warning is displayed. Text at the bottom of this dialog box is difficult to read.
SDK Tools
Manifest Generation and Editing Tool (Mage) won't run without Visual Studio installed
Mage.exe and MageUI.exe ship in the .NET Framework SDK and are designed to run without Visual Studio 2005 being installed. Due to a setup bug, Mage will not run without Visual Studio 2005 installed.
MSBuild doesn't work w/o VS
The Microsoft Build Engine MSBuild ships in the .Net Framework SDK and is designed to run without Visual Studio 2005 being installed. Due to a setup bug, MSBuild will not run without Visual Studio 2005 installed.
Platform Specific Issues
ClickOnce MIME types on Windows 2003 Server must be manually configured
On Windows 2003 Server, IIS 6.0 has locked down support for wildcard MIME mapping. Files with out explicitly defined MIME types will not be served. To enable ClickOnce deployment on Windows 2003 Server you must manually configure MIME types for each file type you plan to deploy as follows:
Table 9
| File Extension | MIME Type |
|---|---|
| .application | "application/x-ms-application" |
| .manifest | "application/x-ms-application" |
| .deploy | "application/octet-stream" |
| all other file types | "application/octet-stream" |
For specific instructions on configuring MIME types on Windows 2003 Server, refer to Microsoft Knowledge Base article KB326965.
ClickOnce not available in Express SKUs
ClickOnce functionality is not available in Visual Basic Express, Visual C# Express, Visual C++ Express, Visual J# Express, or Visual Web Developer Express.
Auto-Generated Setup.exe
The auto-generated setup.exe for Setup projects will fail to run the Windows Installer packages when installed from the Web
When the auto-generated setup.exe for Setup projects is run from the Web, it will fail to execute the Windows Installer package after installing the application prerequisites.
If the package is signed, the error message will resemble: Setup has detected that the publisher of file 'D:\~\Temporary Internet Files\~\SetupMSI[1].msi' could not be verified.
If the package is not signed, the error message will resemble: Setup has detected that the publisher of file 'D:\~\Temporary Internet Files\~\SetupMSI[1].msi' cannot be verified.
Work Around
There is no way to avoid this failure if setup.exe is run from the Web; however, one can directly execute the Windows Installer package if setup.exe fails to run it.
The auto-generated setup.exe fails to install the ClickOnce application when executed from a UNC path
The auto-generated setup.exe will fail to install the ClickOnce application when executed from the UNC share it was published to. Executing setup.exe directly from the UNC will fail when it attempts to launch the ClickOnce application, with the error message that the application is not formatted correctly.
Work Around
If setup.exe and the ClickOnce application are published to a UNC share, have users execute setup.exe from a hyperlink embedded on a Web page. This link should point to the local relative path of setup.exe on the UNC share, for example: <HREF="setup.exe">Install</A>.
If the install machine is already exhibiting this problem, you will need to shut down dfsvc.exe or reboot the machine.
Auto-generated setup.exe fails when running from a UNC fileshare
This problem occurs when the auto-generated setup.exe is configured to install the application from a UNC file share (for example: \\server\share). Setup.exe will fail with no error message when attempting to run the application's installer.
Work Around
Take the following steps before re-running the installer:
Open a command window on the machine where setup.exe was published.
Navigate to the folder where setup.exe was published.
Run the following command to view the current install location:
>setup.exe -rl
Run the following command to change the install location to file://\\server\share
>setup.exe -url=file://\server\share
When run from the Web, the auto-generated setup.exe fails to install an application prerequisite whose installer is a Windows Installer package
When the auto-generated setup.exe is executed from the Web, it will fail after downloading a Windows Installer package for an application prerequisite. The error message returned will indicate that setup could not verify the Windows Installer package.
Work Around
Install Windows Installer version 2.0 or greater on the machine upon which installation will occur, then re-run setup.exe on that machine.
The UI of the auto-generated setup.exe for Setup projects shows text in Chinese Simplified when Chinese Traditional was specified
When both Visual Studio for Chinese Simplified and Visual Studio for Chinese Traditional are installed on the same machine, the auto-generated setup.exe for a Windows Installer package will show text in Chinese Simplified when Chinese Traditional was specified in the Localization property of the Setup project associated with the Windows Installer package.
Work Around
Uninstall Visual Studio for Chinese Simplified and rebuild the Setup project of the Windows Installer package in Visual Studio for Chinese Traditional.
Miscellaneous Known Issues
Using Isolated Storage with ClickOnce
ClickOnce applications use a new feature of the .NET Framework called Isolated Storage. Due to a bug in the Isolated Storage Application scope, applications deployed through ClickOnce should avoid using Isolated Storage.
Additional Resources
For additional information on developing and deploying applications using ClickOnce, refer to the following:
- Microsoft Visual Studio 2005 Beta 2 Readme.htm
- Microsoft Visual Studio 2005 Beta 2 Known Issues.rtf
- Microsoft Visual Studio Developer Center
- MSDN ClickOnce website
- MSDN Product Feedback Center