Web Deployment FAQ for Visual Studio and ASP.NET

Article
04/06/2014

This topic answers frequently asked questions about how to deploy Visual Studio web projects.

Note

This topic applies to Visual Studio 2012 and Visual Studio Express 2012 for Web. The topic covers features that are included in the latest Visual Studio Web Publish Update available as of June, 2013. Most of these features are also available in Visual Studio 2010 and Visual Web Developer 2010 Express when you install the Web Publish Update.

Many of the answers instruct you to change deployment settings by editing the publish profile (.pubxml) file or the wpp.targets file. For information about how to do this, see How to: Edit Deployment Settings in Publish Profile (.pubxml) Files and the .wpp.targets File in Visual Studio Web Projects.

This topic contains the following sections:

Can I exclude specific files or folders from deployment?
Why don't all of the files in my project folder get deployed?
Can I include specific files or folders from outside of my project folder?
How do I disable Web.config transformation?
When should I use Web Deploy parameters instead of Web.config transformations?
How do I deploy an Entity Framework database that uses DbContext without using Migrations?
How to make Web Deploy use file checksums instead of dates to determine which files were changed?
How to encrypt the Web.config file during deployment?
How to automatically take an app offline during deployment?
How can I debug the deployment packaging or publishing process?
Can I use Remote Agent service over HTTPS with one-click publish?
Can I use the Web Deploy tempAgent provider setting with one-click publish?
Can one-click publish create a package for archival purposes?
Can I specify that a package should be created every time I build a solution?
How do I keep my application domain from restarting multiple times during a long deployment process?
Why do I get an error that says ASP.NET 4 is required when ASP.NET 4 is already installed?
Why does deployment fail when it attempts to execute CREATE USER or CREATE ROLE database commands?
Can I create a single package and use it to deploy to both IIS 6 and IIS 7?
Why does remote deployment fail for large files, although local deployment succeeds?

Can I exclude specific files or folders from deployment?

You can limit the files that are deployed by selecting the Only files needed to run this application or All files in this project options on the Package/Publish Web tab. If you select the All files in this project option, you can right-click a file in Solution Explorer and select Exclude From Project to keep it from being deployed. For more information about what files are excluded when you use the Only files needed to run this application or All files in this project options, see Why don't all of the files in my project folder get deployed?.

If these options are not flexible enough for you, another option is to edit the .pubxml or the .wpp.targets file and add an ExcludeFilesFromDeployment element or an ExcludeFoldersFromDeployment element (or both) in the PropertyGroup element. In each element, you can specify a single name, or you can specify multiple names delimited by semicolons (;), as shown in the following example:

<PropertyGroup">
  <ExcludeFilesFromDeployment>
    File1.aspx;File2.aspx
  </ExcludeFilesFromDeployment>
  <ExcludeFoldersFromDeployment>
    Folder1;Folder2
  </ExcludeFoldersFromDeployment>
</PropertyGroup>

Another option is to use the PublishIgnore NuGet package. This option is explained in Web Publishing a simpler way to exclude files/folders from being published on the .NET Web Development and Tools blog.

For more information, see the following posts on Sayed Hashimi's blog:

Why don't all of the files in my project folder get deployed?

From the Project menu select Package/Publish Settings to open the Package/Publish Web tab of the Project Properties window. A drop-down list in the section labeled Items to deploy (applies to all deployment methods) offers three options:

Only files needed to run this application. This is the default value. Visual Studio tries to determine which files are required for the application to run successfully. For example, this includes assemblies in the bin folder, files generated during the build, and files marked as Content. To see if a file is marked as Content, select the file in Solution Explorer, and check the file's Build Action property in the Properties window. You can change the Build Action value to Content to cause the file to be deployed, or change it to something else, such as None, to prevent the file from being deployed. Some file types that are automatically set to Content include .master, .svc, .ashx, .asax, .skin, .browser, .config, .and sitemap. A file must be included in the project in order to have a Build Action property.
All files in this project. Visual Studio deploys all files that are included in the project, regardless of their Build Action property values.
All files in the project folder. Visual Studio deploys all files that are in the project folder and subfolders, regardless of whether they are included in the project or their Build Action property values.

If you are familiar with MSBuild syntax, you can find details about how these three options work in the following files:

Microsoft.Web.Publishing.OnlyFilesToRunTheApp.targets
Microsoft.Web.Publishing.AllFilesInTheProject.targets
Microsoft.Web.Publishing.AllFilesInProjectFolder.targets

These files can be found at the following location in a computer that has Visual Studio installed:

C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\v10.0\Web\

Can I include specific files or folders from outside my project folder?

Yes. For information about how to do this, see Build Package including extra files or excluding specific files on Sayed Hashimi's blog.

How do I disable Web.config transformation?

You have several options:

Comment out specific transforms in the Web.config transform file.
Rename the transform file to a name that does not correspond to a defined build configuration or a Publish profile. For example, you might change Web.Debug.config to Web.Debugx.config. (You might have to rename the file outside of Visual Studio.)
Delete the transform file. If you have customized the file, the customizations will be lost.
Edit the .pubxml file or .wpp.targets file by adding a TransformWebConfigEnabled element to the PropertyGroup element and setting its value to False.

When should I use Web Deploy parameters instead of Web.config transformation?

Web Deploy parameters are more complex to set up than Visual Studio Web.config transformations but are very flexible. Web Deploy parameters are complex to set up because they can automate many other deployment tasks, such as updating database scripts and IIS settings. Web Deploy parameters are useful for Web.config transformation when you are creating a deployment package and when you are creating the package you don't know the values that need to go into the deployed Web.config file. Web Deploy parameters let you specify values for the parameters when the package is installed, not just when it is created. This is especially useful in enterprise environments, where it's common for different people to be responsible for creating and installing deployment packages. For example, the developer who creates a package might not know certain passwords that need to be in the Web.config file. The IT administrator who installs the package can enter those values when the package is installed. For more information, see Parameterization vs. Web.config Transformation on Vishal Joshi's blog and How to: Use Web Deploy Parameters in a Web Deployment Package.

How do I deploy a Code First database without Migrations?

When you implement an Entity Framework Code First context class to access a database, the Settings tab of the Publish Web wizard displays a check box that lets you use Code First Migrations to automate deployment for that database. But if you are only accessing the database by using the Code First API, and Code First is not being used to create the database, you can't use Migrations to deploy it. In this scenario, what you want is the Update database check box that lets you deploy a SQL Server database that you don't use a Code First context for.

How do I deploy an Entity Framework database that uses DbContext without using Migrations?

In Visual Studio, if you have the Publish Web wizard open, close it.
In the application Web.config file, create an additional connection string element for the database. Give this new connection string element a name that does not match either the context class name or the fully qualified class name.
Build the project, and then open the Publish Web wizard and select the profile you want to work with.
Select the Settings tab.

You now see two entries for the database in the Databases section of the tab, one for the context class (with the Execute Code First Migrations check box) and one for the new connection string in the Web.config file.
In the entry for the context class, enter the connection string that you want the application to use at run time, and clear the Execute Code First Migrations check box.
In the entry for the new Web.config file connection string, enter the connection string that should be used to make schema changes during deployment, and select Update database.

For more information about how to enter database deployment settings, see How to: Deploy a Web Project Using One-Click Publish in Visual Studio.

How to make Web Deploy use file checksums instead of dates to determine which files were changed?

By default, Web Deploy determines which files need to be copied to the server by comparing the dates that the local files were last changed against the dates that the server files were last changed. If you use a source control system that changes file dates when you check out files, it appears that they have all changed, and Web Deploy copies them all to the server when you publish.

An alternative for this scenario is to configure Web Deploy to use file checksums to determine which files have changed. Use checksums only if file dates are unreliable indicators of what has changed, because comparing checksums takes more CPU processing time than comparing dates.

To configure Web Deploy to use checksums instead of dates to determine which files need to be copied to the server, add the following element to the .pubxml file:

<MSDeployUseChecksum>true</MSDeployUseChecksum>

Insert this element in the PropertyGroup element, as shown below:

<Project ToolsVersion="4.0" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <MSDeployUseChecksum>true</MSDeployUseChecksum>
    <!— other settings omitted to keep the example short -->
    <PublishDatabaseSettings>
      <!— this section omitted to keep the example short -->
    </PublishDatabaseSettings>
  </PropertyGroup>
</Project>

How to encrypt the Web.config file during deployment?

You can configure Web Deploy to automatically encrypt the Web.config file on the destination server by adding the following element to the .pubxml file:

<MSDeployEnableWebConfigEncryptRule>true</MSDeployEnableWebConfigEncryptRule>

Insert this element in the PropertyGroup element, as shown below:

<Project ToolsVersion="4.0" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <MSDeployEnableWebConfigEncryptRule>true</MSDeployEnableWebConfigEncryptRule>
    <!— other settings omitted to keep the example short -->
    <PublishDatabaseSettings>
      <!— this section omitted to keep the example short -->
    </PublishDatabaseSettings>
  </PropertyGroup>
</Project>

This feature only works with Web Deploy 3.5 and later versions, and it does not work in Windows Azure Web Sites. Windows Azure has other options for securely storing sensitive data. For more information, see Windows Azure Web Sites: How Application Strings and Connection Strings Work.

How to automatically take an app offline during deployment?

You can configure Web Deploy to automatically put a default app_offline.htm file on the server at the start of deployment and remove it when deployment is finished by adding the following element to the .pubxml file:

<EnableMSDeployAppOffline>true</EnableMSDeployAppOffline>

Insert this element in the PropertyGroup element, as shown below:

<Project ToolsVersion="4.0" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <EnableMSDeployAppOffline>true</EnableMSDeployAppOffline>
    <!— other settings omitted to keep the example short -->
    <PublishDatabaseSettings>
      <!— this section omitted to keep the example short -->
    </PublishDatabaseSettings>
  </PropertyGroup>
</Project>

For information about how to use a custom app_offline.htm file, see Making sure an application is off-line during deployment in the ASP.NET Deployment Content Map.

How can I debug the deployment packaging or publishing process?

The packaging and publishing verbosity level is controlled by the same Visual Studio setting that determines MSBuild verbosity. From the main menu, select Tools and then Options. In the Options dialog box, expand Projects and Solutions, and then select Build and Run. You will then see the MSBuild project build output verbosity drop-down list, and you can select one of the following options from that list:

Quiet
Minimal
Normal
Detailed
Diagnostic

These options correspond to what you can set by using the /verbosity or /v flag when you run MSBuild from the command line. For more information about MSBuild command-line flags, see MSBuild Command-Line Reference.

Can I use Remote Agent service over HTTPS with one-click publish?

No. When you enter an HTTPS URL in the Service URL text box of the Publish Web dialog box, Visual Studio automatically uses the Windows Management service. If you want to use HTTPS, we recommend that you use Windows Management service.

Can I use the Web Deploy tempAgent provider setting with one-click publish?

No. If you want to use the tempAgent provider setting, you must use the Web Deploy command line or the deploy.cmd file that Visual Studio generates when it creates a deployment package.

Can one-click publish create a package for archival purposes?

You can create two publish profiles, one to publish the project and one to create the backup package. Then after publishing the project you just have to switch to the publish profile that creates the package and click Publish again. For information about how to create a publish profile that creates a package, see How to: Create a Web Deployment Package in Visual Studio.

Can I specify that a package should be created every time I build a solution?

Yes. Edit the project file and add a DeployOnBuild element in the appropriate PropertyGroup element. (For information about how to edit the project file, see How to: Edit Deployment Settings in the Project File.) The following example shows a PropertyGroup element for the Release build configuration:

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
  <DeployOnBuild>True</DeployOnBuild>
  <!-- Additional settings -->
</PropertyGroup>

If you make this change in the project file, make sure that the PropertyGroup element that you update is located before the Import statements in the project file. (The DeployOnBuild property must be set before the Import for Microsoft.Web.Publishing.targets.)

The DeployDefaultTarget element must also be set to Package. However, it is optional, because that is the default value.

This is all you have to do to make package creation automatic when you build the solution from the command line. To make automatic package creation work also when you build the solution from Visual Studio, add the following code to the project file after the Import for Microsoft.CSharp.targets or Microsoft.VisualBasic.targets:

<PropertyGroup> 
  <BuildDependsOn> 
    $(BuildDependsOn); 
    Package 
  </BuildDependsOn> 
</PropertyGroup>

Can I configure delegation rules so that developers can deploy to staging servers but not change IIS settings?

This is possible in IIS 7 and later versions. For information about delegating deployment permissions, see the following topics:

Delegate Site and Application Management (IIS 7) on the Microsoft TechNet Web site.
Delegating Administration on the IIS.NET Web site.
Configuring the Web Deployment Handler.

How do I keep my application domain from restarting multiple times during a long deployment process?

If you need to execute multiple copy commands to deploy your application and there is a significant time interval between them, the application domain might restart between copy commands. To prevent a restart, Add an httpRuntime Element (ASP.NET Settings Schema) element to the Web.config file and set the waitChangeNotification attribute to the number of seconds to wait to ensure that the application domain does not restart between copy commands. For example, if you want to specify a five-second wait time, the httpRuntime element might look like the following example.

<configuration>
  <system.web>
        <compilation debug="false" targetFramework="4.0" />
    <httpRuntime 
      waitChangeNotification="5" />
  </system.web>
</configuration>

If you want to ensure that the application domain restarts within a certain interval after the first copy command executes, add a maxWaitChangeNotification attribute to the httpRuntime element and set it to the maximum number of seconds to wait. For example, a Web.config file that has the httpRuntime element with both attributes might look like the following example.

<configuration>
  <system.web>
    <httpRuntime 
      waitChangeNotification="5"
      maxWaitChangeNotification="10" />
  </system.web>
</configuration>

Why do I get an error that says ASP.NET 4 is required when ASP.NET 4 is already installed?

In order to deploy an ASP.NET 4 web application, ASP.NET 4 must be registered with IIS on the destination server. In addition, the application pool of the IIS Web site that you are deploying to must be assigned to the .NET Framework 4. If either of these conditions is not true, you might see one of the following errors when you attempt to deploy:

The default .NET 4.0 application pool does not exist or the application could not be added. Please verify that ASP.NET 4.0 is installed on this machine.
The application pool that you are trying to use has the 'managedRuntimeVersion' property set to 'v2.0'. This application requires 'v4.0'.

ASP.NET 4 is installed when you install Visual Studio. However, the installation process does not automatically register ASP.NET 4 with IIS, and existing IIS Web sites are not automatically assigned to.NET 4 application pools. To fix this, register ASP.NET with IIS and set the application pool of the destination IIS Web site to the .NET Framework version that is required by the package. For information about how to register IIS, see ASP.NET IIS Registration Tool (Aspnet_regiis.exe).

Can I create a single package and use it to deploy to both IIS 6 and IIS 7?

If either of the following conditions is true, you can use the same package to deploy to IIS 6 and IIS 7:

You do not select the Include all IIS Settings as configured in IIS Manager option on the Package/Publish Web tab.
You select the Include all IIS Settings as configured in IIS Manager option and create the package on IIS 6.

You cannot deploy a package to IIS 6 that is created on IIS 7 if you select the Include all IIS Settings as configured in IIS Manager option.

Why does remote deployment fail for large files, although local deployment succeeds?

Typically when you deploy to production servers you are deploying across a firewall. If you get end-of-stream errors on large files, check the settings on the firewall. If this is the cause of the deployment failure, you might see error messages such as the following example on the source computer:

Warning: Retrying the sync because a socket error (10054) occurred.

Retrying operation 'Serialization' on object MSDeploy.contentPath (sourcePath).

On the destination server, you might see error messages such as the following example:

System.Net.HttpListenerException: An operation was attempted on a nonexistent network connection

Share via

Web Deployment FAQ for Visual Studio and ASP.NET

Can I exclude specific files or folders from deployment?

Why don't all of the files in my project folder get deployed?

Can I include specific files or folders from outside my project folder?

How do I disable Web.config transformation?

When should I use Web Deploy parameters instead of Web.config transformation?

How do I deploy a Code First database without Migrations?

How do I deploy an Entity Framework database that uses DbContext without using Migrations?

How to make Web Deploy use file checksums instead of dates to determine which files were changed?

How to encrypt the Web.config file during deployment?

How to automatically take an app offline during deployment?

How can I debug the deployment packaging or publishing process?

Can I use Remote Agent service over HTTPS with one-click publish?

Can I use the Web Deploy tempAgent provider setting with one-click publish?

Can one-click publish create a package for archival purposes?

Can I specify that a package should be created every time I build a solution?

Can I configure delegation rules so that developers can deploy to staging servers but not change IIS settings?

How do I keep my application domain from restarting multiple times during a long deployment process?

Why do I get an error that says ASP.NET 4 is required when ASP.NET 4 is already installed?

Can I create a single package and use it to deploy to both IIS 6 and IIS 7?

Why does remote deployment fail for large files, although local deployment succeeds?

See Also

Concepts

Other Resources

Additional resources