ASP.NET Deployment Overview

Article
10/22/2014

After developing a Web site, you can deploy it to a Web server for testing (a staging server) or to a server where users can work with the site (a production server). You have several options for deploying a Web site, which includes precompiling it.

This topic contains:

Scenarios
Deployment Features
Background
Code Examples

Scenarios

After developing a Web site in Visual Studio, you can select one of these deployment methods:

Copy the files in the Web site to the target server by using tools in Visual Studio.
Precompile the site and copy the output to a location that you specify, such as a production server.

Features

Visual Studio provides the following options for deploying a Web site:

The Copy Web Site tool, which copies the current Web site to the target server.
The Publish Web Site utility, which compiles a Web site into a set of executable files. You can then copy the files to the target server by using any method that you want.

Note

The Publish Web Site utility is not available in Microsoft Visual Web Developer Express.

Background

Visual Studio provides the Copy Web Site tool, which copies files of the current Web site to the target server. It also provides the Publish Web Site utility, which compiles a Web site into a set of executable files. You then copy the files to the target server by using any method that you want.

Note

You can also create Web sites by using a Web application project. In a Web application project, all class files are compiled into a single assembly. For more information, see Web Application Projects Overview.

In addition to creating a Web site and then deploying it to a target server, you can also create a File Transfer Protocol (FTP) Web site. In that case, you create and edit the files directly on the target server. This is a convenient way to work with a Web site on a hosted server.

The Copy Web Site Tool

The Copy Web Site tool is like an FTP utility. You can open a folder on a target server, and then upload and download files between the current Web site and the target Web site. The Copy Web Site tool supports a synchronization feature that examines the files in both Web sites and automatically makes sure that both sites have up-to-date versions of the files.

Note

If the target server is an FTP server, you can open and edit the files on the server by creating an FTP Web site. For more information, see FTP-Deployed Web Sites.

The Copy Web Site tool supports the following features:

You can copy source files, including the .aspx files and class files, to the target server. In this scenario, the Web pages are compiled dynamically when they are requested.
You can open and copy files from any kind of Web site that is supported in Visual Studio. This includes local Internet Information Services (IIS), Remote IIS, and FTP Web sites. The target server does not require FrontPage Server Extensions.
The synchronization feature examines the files in both Web sites and automatically makes sure that both sites have up-to-date versions of the files.
Before you copy application files, the Copy Web Site tool puts a file that is named App_offline.htm into the root directory of the target Web site. While the App_offline.htm file exists, any requests to the Web site are redirected to this file. The file displays a friendly message that tells clients that the Web site is being updated. When all Web site files have been copied, the Copy Web Site tool deletes the App_offline.htm file from the target Web site.

The Publish Web Site Utility

The Publish Web Site utility precompiles the content of the Web site, including Web pages (.aspx files) and code. It then copies the output to a directory or server location that you specify. You can publish directly as part of the precompilation process. Alternatively, you can precompile locally and then copy the files yourself. The Publish Web Site utility compiles the Web site and strips the source code out of the files, leaving only stub files for the pages and compiled assemblies. When users request pages, ASP.NET fulfills the request from the precompiled assemblies.

Note

The Publish Web Site utility is not available in Microsoft Visual Web Developer Express.

Web Application Projects

As an alternative to using the Publish Web Site utility, you can create Web sites by using a Web application project. In a Web application project, all class files are compiled into a single assembly. Only that assembly has to be deployed, together with the .aspx and .ascx files and other static content files. (This Web application project model resembles the model used in Visual Studio .NET 2003.) In this model, .aspx files are not compiled until they are run in the browser. For more information about Web application projects, see Web Application Projects Overview.

Choosing a Deployment Tool

Whether you select the Copy Web Site tool or the Publish Web Site utility depends on how you intend to use and maintain your site.

Choosing the Copy Web Site Tool

Advantages of using Copy Web Site tool are as follows:

Deployment is a simple matter of copying files from the Web site to the target computer.
You can deploy to a target computer by using any connection protocol that is supported by Visual Studio. You can copy to a shared folder on another computer on your network. You can use FTP to copy to a server, or use HTTP protocol to copy to a server that supports FrontPage Server Extensions.
You can make changes or fix errors in the pages directly on the server.
If you are working with a project where files are stored in a central server, you can use the synchronize feature to make sure that the local and remote versions of files are synchronized.

Disadvantage of using the Copy Web Site tool are as follows:

The site is copied as-is. Therefore, if any files contain a compilation error, the error will not be discovered until someone (perhaps a user) runs the page that raises the error.

Choosing the Publish Web Site Utility

Advantages of using Publish Web Site utility are as follows:

The precompilation process helps you find compile-time errors and potential errors in the Web.config file and in other non-code files.
The source code is removed from the Web site, optionally including the markup in ASP.NET Web files and user controls. This gives you a measure of protection for your intellectual property and makes it more difficult for others to access the source code of the site.
Because the pages in the site are already compiled, they do not have to be dynamically compiled when they are first requested. This can reduce the initial response time for a page. (When pages are dynamically compiled, the output is cached for subsequent requests.)

Disadvantages of using the Publish Web Site utility are as follows:

Depending on what publish options that you specify, you might have to recompile the site if you change it. Therefore, it might not be practical to use the Publish Web Site utility when you are developing a site and changing pages frequently.
The Publish Web Site utility cannot deploy the compiled site to a remote server. It can copy only to the local computer or to another computer on the local area network.

Note

The Publish Web Site utility overwrites files in the target folder and any subfolders. Make sure that you publish to a location where it is safe to delete the existing contents.

Using the Copy Web Site Tool

You can use the Copy Web Site tool to move files from the local computer to a staging server or to a production server. The Copy Web Site tool is especially useful when you cannot open files from the remote site to edit them. You can use the Copy Web Site tool to copy the files to the local computer, edit them, and then copy them back to the remote site. You can also use the tool to copy files from a staging server to the production server when you have finished your development.

Note

If you copy an application that contains a reference to a custom component that is registered in the GAC, the component will not be copied with the application. For more information, see How to: Add a Reference to a .NET or COM Component in a Web Site.

Source and Remote Sites

The Copy Web Site tool copies files between a source site and a remote site. These terms are used distinguish the two sites that the tool is working with. The terms are used with these meanings:

Source site The source site is the site that you currently have open in Visual Studio.
Remote site The remote site is the site to which you want to copy files. A remote site can be a location on another computer that you can access by using FrontPage Server Extensions or FTP. In these cases, the site is actually remote. However, the remote site can also be another site on your own computer. For example, you can publish from a file-system Web site on your computer to a local IIS Web site that is also on your computer. In this case, although the site is local to your computer, it is the remote site when you use the Copy Web Site tool.

Note that the source site is not necessarily the source for copying. You can copy from the remote site to the source site.

Synchronizing Sites

Synchronizing examines the files on the local and remote sites and makes sure that all files on both sites are up to date. For example, if a file on the remote site is more current than the version of the same file on the source site, synchronizing the files copies the file on the remote site to the source site.

The Copy Web Site tool does not merge files that have the same name but different content. In that case, synchronization lets you specify which version of a file that you want to keep.

Synchronization makes the tool useful for a multi-developer environment where developers keep copies of the Web site on their local computers. Individual developers can copy their latest changes to a shared remote server. At the same time, they can update their local computer with changed files from other developers. New developers on a project can also quickly get copies of all the files for a Web site. To do so, they can create a local Web site on the local computer and then synchronize with the site on the shared server.

File Status

To synchronize files, the Copy Web Site tool needs information about the state of the files on both sites. Therefore, the tool maintains information that consists of the files' timestamps plus additional information that is required to perform synchronization. For example, the tool maintains a list of when the files were last checked, which enables the tool to determine information such as whether a file has been deleted.

When you connect to a site (or refresh), the tool compares the timestamps of the files on both sites and the information it has stored for both sites. It then reports the state of each file. The following table shows the status of the files.

Status	Description
Unchanged	The file has not changed since the last time the file was copied.
Changed	The file has a timestamp that is newer than the timestamp taken when the file was last copied.
New	The file has been added since the last time the site was copied.
Deleted	The file has been removed since the last time the site was copied. If you select Show Deleted Files in the Copy Web Site tool, an entry for the file is displayed in the window.

Using the Publish Web Site Utility

The Publish Web Site Utility enables you to publish your Web sites. This compiles the site and copies the output to a location that you specify, such as a production server.

Note

The Publish Web Site utility is not available in Visual Web Developer Express.

Publishing accomplishes the following tasks:

Precompiles pages, source code in the App_Code folder, and so on, into executable output.
Writes the executable output to a target folder.

Note

If you publish an application that contains a reference to a custom component that is registered in the GAC, the component will not be published with the application. For more information, see How to: Add a Reference to a .NET or COM Component in a Web Site.

For more information, see ASP.NET Precompilation Overview.

Precompilation

The first step in publishing is to precompile the Web site. Precompilation performs the same compilation process that ordinarily occurs when a page is compiled dynamically when it is first requested in a browser. The precompilation process produces assemblies from the pages, which includes both the markup and the code. It also compiles files in the App_Code, App_GlobalResources, App_LocalResources, and App_Themes folders.

You can compile both single-file ASP.NET pages and code-behind pages. For information about these two models, see ASP.NET Web Page Code Model.

The precompilation step in publishing differs from the compilation that occurs when you build a Web site in Visual Studio while testing it. Building compiles the site, or the current page and any dependent files, and then runs it. The build process is a form of testing and does not produce output that you can deploy. In contrast, precompilation during publishing creates output in a specified folder that you can deploy to a production server.

Writing Precompiled Output

When the precompilation process is finished, the output is written to a folder that you specify. You can write the output to any folder that is available to you in the file system, by using File Transfer Protocol (FTP), or by using HTTP. You must have appropriate permissions to be able to write to the target site.

Note

The publishing process deploys only the files in the Web site folders and subfolders. It does not deploy the Machine.config file. Therefore, the configuration of the target Web server might differ from the configuration on your computer. This might affect the behavior of the application.

You can specify a target folder on a staging server or production server, or you can write the output to a folder on the local computer. If you specify a folder on a production server, you can precompile and deploy in a single step. If you write the output to a folder that is not part of a Web site, you can copy the output to the server in a separate step.

Note

If you open a precompiled Web site using Visual Studio, you will not be able to build the Web site. Build options will be turned off. To change a published Web site, edit the files in the original Web site, recompile the site, and publish it again.

The output of the compilation process includes the compiled assemblies for any code or pages. If you select the option to enable the precompiled site to be updated, any code-behind classes for your .aspx, .asmx, and .ashx files are compiled into assemblies. However, the .aspx, .asmx, and .ashx files themselves are copied as-is to the target folder so that you can change their layout after you deploy the site. For precompiled sites that can be updated, the code in single-file pages is not compiled into an assembly. Instead, it is deployed as source code.

Static files are not compiled. Instead, they are copied as-is to the output folder. Static files include graphics, .htm or .html files, text files, and so on.

If an error occurs during precompilation, it is reported in the Output window and in the Error List window. Errors during precompilation prevent the site from being compiled and published.