Server and Client Configuration Issues in ClickOnce Deployments
Important This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here. ArchiveDisclaimer

Server and Client Configuration Issues in ClickOnce Deployments 

If you use Internet Information Services (IIS) on Windows Server 2003, and your deployment contains a file type that Windows does not recognize, such as a Microsoft Word file, IIS will refuse to transmit that file, and your deployment will not succeed.

Additionally, some Web servers and Web application software, such as ASP.NET, contain a list of files and file types that you cannot download. For example, ASP.NET prevents the download of all Web.config files. These files may contain sensitive information such as user names and passwords.

Although this restriction should cause no problems for downloading core ClickOnce files such as manifests and assemblies, this restriction may prevent you from downloading data files included as part of your ClickOnce application. In ASP.NET, you can resolve this error by removing the handler that prohibits downloading of such files from the IIS configuration manager. See the IIS server documentation for additional details.

Some Web servers might block files with extensions such as .dll, .config, and .mdf. Windows-based applications typically include files with some of these extensions. If a user attempts to run a ClickOnce application that accesses a blocked file on a Web server, an error will result. Rather than unblocking all file extensions, ClickOnce publishes every application file with a ".deploy" file extension by default. Therefore, the administrator only needs to configure the Web server to unblock the following three file extensions:

  • .application

  • .manifest

  • .deploy

However, you can disable this option by clearing the Use ".deploy" file extension option on the Publish Options Dialog Box, in which case you must configure the Web server to unblock all file extensions used in the application.

You will have to configure .manifest, .application, and .deploy, for example, if you are using IIS where you have not installed the .NET Framework, or if you are using another Web server (for example, Apache).

ClickOnce and Secure Sockets Layer (SSL)

A ClickOnce application will work fine over SSL, except when Internet Explorer raises a prompt about the SSL certificate. The prompt can be raised when there is something wrong with the certificate, such as when the site names do not match or the certificate has expired. To make ClickOnce work over an SSL connection, make sure that the certificate is up-to-date, and that the certificate data matches the site data.

ClickOnce and Proxy Authentication

For ClickOnce to work with default proxy authentication in a corporate setting, the defaultProxy element in the machine.config file on all client computers must be set to allow System.Net to use default security credentials. Alternatively, you can configure defaultProxy on client computers to use a specific proxy server.

For more information, see <defaultProxy> Element (Network Settings).

ClickOnce and Web Browser Compatibility

Currently, ClickOnce installations will launch only if the URL to the deployment manifest is opened using Internet Explorer. A deployment whose URL is launched from another application, such as Microsoft Office Outlook, will launch successfully only if Internet Explorer is set as the default Web browser.

Activating ClickOnce Applications Through Browser Scripting

If you have developed a custom Web page that launches a ClickOnce application using Active Scripting, you may find that the application will not launch on some machines. Internet Explorer contains a setting called Automatic prompting for file downloads, which affects this behavior. This setting is available by clicking Custom level... on the Security Tab in Internet Explorer's Options menu; it is listed underneath the Downloads category. The property is set to Enable by default for intranet Web pages, and to Disable by default for Internet Web pages. When this setting is set to Disable, any attempt to activate a ClickOnce application programmatically (for example, by assigning its URL to the document.location property) will be blocked. Under this circumstance, users can launch applications only through a user-initiated download, for example, by clicking a hyperlink set to the application's URL.

Additional Server Configuration Issues

Administrator Permissions Required

You must have Administrator permissions on the target server if you are publishing with HTTP. IIS requires this permissions level. If you are not publishing using HTTP, you only need write permission on the target path.

Server Authentication Issues

When you publish to a remote server that has "Anonymous Access" turned off, you will receive the following warning:

"The files could not be downloaded from http://<remoteserver>/<myapplication>/.  The remote server returned an error: (401) Unauthorized."

You can make NTLM (NT challenge-response) authentication work if the site prompts for credentials other than your default credentials, and, in the security dialog box, you click OK when you are prompted if you want to save the supplied credentials for future sessions. However, this workaround will not work for basic authentication.

Using Third-Party Web Servers

If you are deploying a ClickOnce application from a Web server other than IIS, you may experience a problem if the server is returning the incorrect content type for key ClickOnce files, such as the deployment manifest and application manifest. To resolve this problem, see your Web server's Help documentation about how to add new content types to the server, and make sure that all the file name extension mappings listed in the following table are in place.

File name extension Content type







FTP Protocol Not Supported

ClickOnce supports installing applications from any HTTP 1.1 Web server or file server. FTP, the File Transfer Protocol, is not supported. You can use an ftp:// URL to publish applications, but you must perform installations using an http://, https://, or file:// URL.

Windows XP SP2: Windows Firewall

By default, Windows XP SP2 enables the Windows Firewall. If you are developing your application on a computer that has Windows XP installed, you are still able to publish and run ClickOnce applications from the local server that is running IIS. However, you cannot access that server that is running IIS from another computer unless you open the Windows Firewall. See Windows Help for instructions on managing the Windows Firewall.

Windows Server 2003: Enable FrontPage server extensions

FrontPage 2002 Server Extensions from Microsoft is required for publishing applications to a Windows Web server that uses HTTP.

By default, Windows Server 2003 does not have FrontPage 2002 Server Extensions installed. If you want to use Visual Studio to publish to a Windows Server 2003 Web server that uses HTTP with FrontPage 2002 Server Extensions, you must install FrontPage 2002 Server Extensions first. You can perform the installation by using the Manage Your Server administration tool in Windows Server 2003.

Windows Server 2003: Locked-Down Content Types

IIS on Windows Server 2003 locks down all file types except for certain known content types (for example, .htm, .html, .txt, and so on). To enable deployment of ClickOnce applications using this server, you need to change the IIS settings to allow downloading files of type .application, .manifest, and any other custom file types used by your application.

If you deploy using an IIS server, run inetmgr.exe and add new File Types for the default Web page:

  • For the .application and .manifest extensions, the MIME type should be "application/x-ms-application." For other file types, the MIME type should be "application/octet-stream."

  • If you create a MIME type with extension "*" and the MIME type "application/octet-stream," it will allow files of unblocked file type to be downloaded. (However, blocked file types such as .aspx and .asmx cannot be downloaded.)

For specific instructions on configuring MIME types on Windows 2003 Server, refer to Microsoft Knowledge Base article KB326965, "IIS 6.0 Does Not Serve Unknown MIME Types" at;en-us;326965.

Content Type Mappings

When publishing over HTTP, the content type (also known as MIME type) for the .application file should be "application/x-ms-application." If you have .NET Framework 2.0 installed on the server, this will be set for you automatically. If this is not installed, then you need to create a MIME type association for the ClickOnce application vroot (or entire server).

If you deploy using an IIS server, run inetmgr.exe and add a new content type of "application/x-ms-application" for the .application extension.

HTTP Compression Issues

With ClickOnce, you can perform downloads that use HTTP compression, a Web server technology that uses the GZIP algorithm to compress a data stream before sending the stream to the client. The client—in this case, ClickOnce—decompresses the stream before reading the files.

If you are using IIS, you can easily enable HTTP compression. However, when you enable HTTP compression, it is only enabled for certain file types—namely, HTML and text files. To enable compression for assemblies (.dll), XML (.xml), deployment manifests (.application), and application manifests (.manifest), you must add these file types to the list of types for IIS to compress. Until you add the file types to your deployment, only text and HTML files will be compressed.

For detailed instructions for IIS, see the article "How to Specify Additional Document Types for HTTP Compression" in the MSDN Online Knowledge Base (from the Knowledge Base Search page, search for "234497").

See Also

© 2016 Microsoft