How to: Deploy a Web Project Using One-Click Publish in Visual Studio

This topic explains how to publish (deploy) a web project by using the Visual Studio one-click publish feature.

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 October, 2013.

You can also use this topic for Visual Studio 2013 and Visual Studio 2013 Express for Web. The screens will look slightly different from what you see here and some new features are not covered, but the basic procedures for deployment are the same. For more information, see ASP.NET Web Deployment – Recommended Resources.

You can deploy to any of the following destinations:

• To a hosting provider.

• To a file folder on your network (you can manually copy from there to a folder used by IIS).

• To IIS on your development computer as a testing environment.

• To a server on your company's internal network.

To configure deployment for a web project in Visual Studio, you create one or more publish profiles using the Publish Web wizard. A publish profile specifies the server you are deploying to, the credentials needed to log on to the server, the databases to deploy, and other deployment options. When you are ready to publish, you choose the profile you want to use and click the Publish button in the wizard or in the Web One Click Publish toolbar.

Deploying a web site often requires additional preparation work besides creating a profile. This topic does not include information about other tasks that you might need to do. For example, you specify compile and merge options in the Package/Publish Web tab, not in the publish profile. For more information, see Web Deployment Overview for Visual Studio and ASP.NET.

Creating a Publish Profile

Many hosting providers provide a .publishsettings file that you can use to simplify the process of creating a publish profile. If you are going to use a .publishsettings file, make sure that you have the most current version of it before you begin. (For example, if you originally created an account without a SQL Server database and then added it later, you must download the latest version of the .publishsettings in order to make sure that it includes the connection string you need.)

Note

If you are publishing to Windows Azure Web Sites, you can download and import a .publishsettings file for a destination web site, or you can connect directly to your Windows Azure Account from Visual Studio. If you connect to your account, Visual Studio displays a list of your web sites, and you can choose one to import publish settings. When you connect to your account in Visual Studio, you can also perform web site management functions and get web site diagnostic information in Visual Studio. The screen shots in this topic don’t show all of the newer features for working with Windows Azure Web Sites. For more information, see Deploying an ASP.NET Web Application to a Windows Azure Web Site on the WindowsAzure.com web site.

To create a publish profile

1. If you are going to use a .publishsettings file to create your publish profile, start by downloading the .publishsettings file from your hosting provider. The procedure for doing this depends on your hosting provider. You don’t need to do this if you are deploying to a Windows Azure Web Site.

2. In Solution Explorer, right-click the project and select Publish (or Publish Web Site for web site projects) to open the Publish Web wizard.

   If you haven't created any profiles yet, the wizard opens on the Profile tab. Otherwise, it opens on the Preview tab. In that case, to create a new profile you must first click the Profile tab.

   

   Notice the Manage profiles button on the Profile tab. After you have created a profile, you can use this button to rename or delete it.

3. Perform one of the following procedures to create a publish profile:

   To create a profile by importing a .publishsettings file for a web site

   1. Click Import.

      The Import Publish Profile dialog box opens.

   2. Click Import from a publish profile file, and then click Browse.

      The Import Publish Settings dialog box opens.

      

   3. Select the .publishsettings file, and then click Open.

   To create a profile by importing publish settings from Windows Azure

   • For information about how to create a publish profile for a Windows Azure Web Site, see Deploying an ASP.NET Web Application to a Windows Azure Web Site on the WindowsAzure.com web site.

   To create a profile without a .publishsettings file

   • In the Select or import a publish profile drop-down list, choose <New …>, and enter a name for the profile in the New Profile dialog box.

     

     

The settings for a publish profile are stored in a .pubxml file that is located in the PublishProfiles folder. In web application projects, the PublishProfiles folder is in the Properties folder (for C#) or the My Project folder (for VB). In web site projects the PublishProfiles folder is in the App_Data folder. When you create the first publish profile in a web site project, a website.publishproj file is also created in the root folder of the web site. These files are only used for publishing; they are not deployed when you deploy the site. For more information about .pubxml files, see How to: Edit Deployment Settings in Publish Profile (.pubxml) Files and the .wpp.targets File in Visual Studio Web Projects.

Configuring the Connection Tab

The Publish Web wizard automatically advances to the Connection tab.

If you used a .publishsettings file, the fields on this tab are already filled in. In that case, skip this procedure and just validate the connection.

To configure the Connection tab

1. Select a value from the Publish method list.

   Web Deploy is the recommended publish method because it can automate the widest range of deployment tasks. However, before choosing this method, make sure that the hosting provider or server that you are deploying to supports Web Deploy.

   If you select Web Deploy and you are publishing to IIS on your own computer for testing, you must have administrative rights on your computer, and Visual Studio must be running in administrator mode. (To open Visual Studio in administrator mode, right-click the Visual Studio icon in the Windows Start menu and select Run as Administrator.)

   If you select Web Deploy and you are publishing to a server on your own network, make sure that the server is set up for the Web Deployment Agent Service (MSDepSvc, also known as Remote Agent service), and that you have administrative rights on the destination server. For information about how to set up the destination server, see Web Deploy Remote Service on the Microsoft TechNet web site.

   The screenshots and most of the steps in this topic assume that you have selected the Web Deploy publish method. However, the descriptions of UI elements that you see when you select other publish methods are also accurate for those other publish methods. For example, if you select the File System publish method, you will still see the Destination URL text box, and the only purpose of that text box is to automate opening a browser to the deployed site after successful deployment.

   If you are deploying to a hosting provider that does not support Web Deploy, you can select FTP instead. In that case, the instructions for some of the following steps are different. The Service URL and Site/application fields are replaced by a Target Location field, in which you enter the FTP or FTPS URL. If anonymous logon is allowed, you do not need to enter a user name and password. If you need passive mode, edit the publish profile (.pubxml) file and change the value of the FtpPassiveMode element to true. For information about passive mode, see FTP-Deployed Web Site Projects, and for information about how to edit the .pubxml file, see How to: Edit Deployment Settings in Publish Profile (.pubxml) Files and the .wpp.targets File in Visual Studio Web Projects.

   Besides Web Deploy and FTP, another option is to use the File System publish method. This method publishes the web application to a folder that you specify. You can then use your own FTP tool to transfer the files to a hosting provider.

   One of the Publish method options is Web Deploy Package. If you want to create a deployment package, see How to: Create a Web Deployment Package in Visual Studio.

2. In the Service URL box, enter the URL that Web Deploy can use to publish the application.

   If you are publishing to a hosting company, the company provides this value. It can be in any of the following formats:

   • HostingCompanyURL (for example, contoso.com)

   • https://HostingCompanyURL (for example, https://contoso.com)

   • https://HostingCompanyURL:8172/msdeploy.axd (for example, https://contoso.com:8172/msdeploy.axd)

   If you are publishing to IIS on your own computer for testing, enter localhost or the name of your computer.

   If you are publishing to a server on your own network, enter one of the following URLs:

   • https://ServerName

   • https://ServerName/msdeployagentservice

   If you’re publishing through a firewall, you might need to open port 8172.

3. In the Site/application box, enter the name of the IIS web site and application.

   If you are publishing to a hosting company, the company provides this value. It is typically either a domain name (for example, contoso.com) or a domain and application name (for example, contoso.com/MyApplication).

   If you are publishing to IIS on your own computer for testing, or to a server on your internal network, enter the site and application name as they appear in IIS Manager. For example, if you are publishing to the default web site in IIS and if the application name is MyApplication, enter Default Web Site/MyApplication.

4. In the User name and Password boxes, enter credentials for an account that has sufficient authority to perform deployment tasks on the destination web server.

   If you are publishing to a hosting company, the company provides these values.

5. If you do not want to be prompted for a password every time you publish, select the Save password check box.

   The password is encrypted and stored in a .pubxml.user file in the PublishProfiles folder. If you use source control, this file is excluded from source control by default.

6. If you want Visual Studio to automatically open your default browser to the URL of the deployed application after deployment is finished, enter the URL in the Destination URL box.

To validate the settings on the Connection tab

1. Click Validate Connection to validate that you can make a connection to the server using the settings you entered.

2. If you see a Certificate Error dialog box, make sure that you are publishing to the correct URL (double-check Service URL and the server name in the Certificate Error dialog box). If the settings are correct, select Save this certificate for future sessions of Visual Studio so that you do not get the same error message again, and then choose Accept Certificate. (This error means that the hosting provider has chosen to avoid the expense of purchasing an SSL certificate for the URL that you are deploying to. If you prefer to establish a secure connection by using a valid certificate, contact your hosting provider.)

   

   If Visual Studio can't make a connection, make sure that nothing is preventing the connection from your computer (such as a proxy or firewall setting), and then try again. If you still can't make a connection, contact the hosting provider or the person who maintains the destination server.

Configuring the Settings Tab

In the Connection tab, click Next to advance to the Settings tab.

To configure the Settings tab

1. If you are deploying a web application project, choose the build configuration to deploy from the Configuration drop-down list.

   You normally deploy a Release build for web application projects. A Debug build does not run efficiently and is typically selected only when you are deploying to a test environment and you need to debug in that environment.

   This setting doesn’t have any effect for web site projects. For a web site project you’ll see Debug listed as a build configuration, but that has no effect when the web site project is compiled dynamically. For more information, see Web Application Projects versus Web Site Projects in Visual Studio.

2. If you want to delete files on the destination server that have no matching files in the web project on your computer, expand File Publish Options and select the Remove additional files at destination check box.

   Warning

   If you select this option, make sure that you use the preview feature so that you see in advance which files will be deleted before you deploy. The expected behavior is that Web Deploy will delete files on the destination server that you have deleted in your project. However, the entire folder structure under the source and destination folders is compared, and in some scenarios Web Deploy might delete files you don't want to delete.

   For example, if you have a web application in a subfolder on the server when you deploy a project to the root folder, the subfolder will be deleted. You might have one project for the main site at contoso.com and another project for a blog at contoso.com/blog. The blog application is in a subfolder. If you select Remove additional files at destination when you deploy the main site, the blog application will be deleted.

   For another example, your App_Data folder might get deleted unexpectedly. Certain databases such as SQL Server Compact store database files in the App_Data folder. After the initial deployment you don't want to keep copying the database files in subsequent deployments so you select Exclude App_Data on the Package/Publish Web tab. After you do that, if you have Remove additional files at destination selected, your database files and the App_Data folder itself will be deleted the next time you publish.

3. If you want to precompile or merge assemblies when you package or publish the project, expand File Publish Options and select Precompile during publishing.

   By default, you get the following compile and merge behavior when you select this option:

   • IIS metabase path is not used for source input.

     You might need to use an IIS metabase path if your web site contains one or more sub-web sites. During compilation, the compiler processes all of the files in a directory tree. If there are sub-web sites, this will result in build errors. To avoid these errors, you can specify the IIS metabase path of the web site you are compiling, which causes the ASP.NET compiler to skip any sub-web sites defined in the IIS metabase.

   • Precompiled assemblies will not be updateable.

     By default, .aspx and .ascx files are compiled and the HTML markup for pages and controls is removed and compiled into the assembly output. Compiling these files is typically the only reason you would precompile a web application project, but you might have selected the Precompile this application before publishing check box only so that you can choose a merge option.

   • Each source file generates a separate assembly.

   If you want to change any of these default settings, click the Configure link. For more information see, Advanced Precompile Settings Dialog Box.

4. If you want to prevent files in the App_Data folder from being deployed to the destination server, expand File Publish Options and select Exclude files from the App_Data folder.

   The App_Data folder typically contains test databases during the development cycle. The contents of this folder might not be appropriate for a production environment.

Configuring Databases in the Settings Tab

The Databases section of the Settings tab is not shown for the FTP, File System, and FPSE publish methods. If you selected one of those methods, skip the following procedure and deploy your database manually. For more information, see Web Deployment Overview for Visual Studio and ASP.NET.

If you selected the Web Deploy publish method, you see one entry for each database that the project uses. The illustration shows a project that uses two databases.

If a database that your project uses is missing, make sure that you have a connection string for it in the Web.config file. The Settings tab lists databases that are identified by a connection string in the Web.config file or by an Entity Framework Code First context class.

Note

If the Include all databases configured in Package/Publish SQL tab check box is cleared, database deployment settings entered here have no effect. See Package/Publish Web Tab, Project Properties.

Perform the following procedure for each database that is shown in this list.

To configure Databases in the Settings tab

1. In the connection string box, choose or enter a connection string that points to the destination database.

   The combo box contains connection strings from the .publishsettings file (if you used one to create the profile), from other publish profiles in the project, and from databases for which you have connections in Server Explorer. You can choose one of these, enter a connection string manually, or click the ellipsis to open the Destination Connection String dialog box.

   

   If the connection string is for a database that is accessed by Entity Framework Database First or Model First, do not specify the full Entity Framework version of the connection string here. Visual Studio uses the connection string you enter here to perform the deployment, then it constructs the Entity Framework connection string to put in the deployed Web.config file.

2. If you don't want the connection string you entered to be used by the application at run time, clear the Use this connection string at runtime check box.

   When the Use this connection string at runtime check box is selected, the deployment process changes the connection string for this database in the deployed Web.config file to the value that's in the combo box. In most scenarios this is the right choice, but in some scenarios you might want the application to connect to the database with restricted permissions. In that case, clear this check box and create a Web.config transformation that changes the connection string in the deployed Web.config file to what you want it to be at run time. For information about how to set up Web.config transformations, see Web.config File Transformations on the ASP.NET website.

3. If you use Entity Framework Code First to manage the database, you can use Code First Migrations to deploy the database and updates to the database schema. To do that, select Execute Code First Migrations (runs on application start).

   

   When you use Code First Migrations to deploy the database, nothing is done with the database during the actual deployment process. However, the deployment process updates the Web.config file in the destination web site so that Code First Migrations uses the MigrateDatabaseToLatestVersion initializer class. When the application accesses the database for the first time after deployment, Migrations automatically creates the database or updates the database schema to the latest version. If the application implements a Migrations Seed method, the method runs after the database is created or the schema updated.

   Note

   If your application will run in Medium Trust in the environment you are deploying to (which is true of most third-party hosting providers), make sure that you are using Entity Framework version 5 or later. EF 4.3 and prerelease versions of EF 5 require Full Trust to make database schema updates. You can use EF 5 in projects that target ASP.NET 4 and later versions.

   You can only use Code First Migrations for deployment if you have implemented a DbMigrationsConfiguration class. If an error message indicates that the DbMigrationsConfiguration class is missing, you must enable Code First Migrations before you can finish configuring database deployment. If you get this error but you don’t want to use Migrations for deployment, or you can’t because your database is not managed by Code First, see How do I deploy an Entity Framework database that uses DbContext without using Migrations?.

   If the project implements multiple DbMigrationsConfiguration classes for a context class, you can't configure deployment for this database in the publish profile. For information about how to deploy the database manually, see Code First Migrations.

   The credentials in the connection string that you enter in the connection string box must represent an administrative user account. This connection string is used to create the database the first time you deploy it and to update the database schema when you deploy database changes. If you want the application to access the database at run time with limited permissions, clear the Use this connection string at runtime check box and create a Web.config transformation that specifies the connection string you want the application to use at run time. For more information, see Reviewing the Automatic Web.config Changes for Code First Migrations on the ASP.NET site.

   If you are deploying a SQL Server Compact database, and if the connection string for the database is in the Web.config file, you have to configure a Web.config transformation to create an additional connection string. Code First will use this connection string when it updates the database schema. (If you don't do create this connection string manually, Visual Studio creates it automatically, but the automatically created connection string has the wrong providerName value.) The XML for this transformation looks like the following example:

   <connectionStrings>
     <add name="[contextclassname]_DatabasePublish" connectionString="[connectionstring]" providerName="System.Data.SqlServerCe.4.0" xdt:Transform="Insert"/>
   </connectionStrings>
   

   If you are using a DBContext class with an existing database (which means Code First doesn’t manage database updates), you can’t use Migrations for deployment. In that case, or if Code First does manage the database but you just don't want to deploy by using Migrations, see How do I deploy an Entity Framework database that uses DbContext without using Migrations?

4. If you are not using a Code First context class to access the database, and if it is a SQL Server or SQL Server Express database, and you want to deploy the database along with the application, select Update database.

   

   This option uses the dbDacFx Web Deploy provider. During initial deployment, the database schema is created. During subsequent deployments, the destination database is compared to the source database, and the destination database schema is updated to match the source database.

   Data in database tables is not automatically deployed. If you need to deploy data to the destination database, create a custom database script and configure it to run during deployment after the [Auto schema update] script runs, as described in the following step.

   By default, the dbDacFx provider won't automatically make schema changes that cause data loss, such as dropping a column or a table. If the provider detects a schema change that would cause data loss, deployment fails and the reason is displayed in the Visual Studio Output window. If that happens, create a custom script to perform the required schema updates, and configure it to run before the [Auto schema update] script runs, as described in the following step. As an alternative to running a script during deployment, you can connect to the destination database in SQL Server Object Explorer and update the database interactively before you publish the project.

   If you are deploying to a hosting company, make sure that the hosting company has Web Deploy 3.0 and the dbDacFx provider installed on its servers. If you are deploying to a web server on your company's network, use the following link to install Web Deploy 3.0 and the dbDacFx provider on the web server.

   • Web Deploy 3.0 and the dbDacFx provider

   This software is required only on the destination web server, not on the destination database server. If you are deploying to IIS on your development computer you don't have to install this software because it is installed with Visual Studio 2012, Visual Studio Express 2012 for Web, or the Visual Studio Web Publish Update by default.

   The credentials in the connection string that you enter in the connection string box must represent an administrative user account. This connection string is used to create the database the first time you deploy it and to update the database schema when you deploy database changes. If you want the application to access the database at run time with limited permissions, clear the Use this connection string at runtime check box and create a Web.config transformation that specifies the connection string you want the application to use at run time. For more information, see Reviewing the Automatic Web.config Changes for Code First Migrations on the ASP.NET site.

   If you have multiple databases in your project, but you want to use only one database in the deployed application, you can typically combine multiple source databases into one destination database. You can do that by choosing Update database and entering the same destination connection string for each of the source databases. You can combine the databases as long as there are no object name collisions, such as a table name that is the same in multiple source databases.

5. If you selected Update database and you want to run custom SQL scripts during deployment, click Configure database updates.

   The Configure Database Updates dialog box opens.

   

   You use the Add SQL Script link to add scripts, the up and down arrows to change the order in which they are run, and the check boxes to specify whether a listed script will be run during deployment.

   The script labeled [Auto schema update] is automatically generated and run during the deployment process to update the schema of the destination database to match the source database. You can specify custom scripts to run before, after, or both before and after the automatic script runs. The following illustration shows the Configure Database Updates dialog box after a custom script has been added.

   

6. If the database is a SQL Server Express or SQL Server Compact database file in the App_Data folder, and if you don't want that file to be copied to the destination server, open the Package/Publish Web tab of the Project Properties window and select the Exclude files from the App_Data folder check box. Make sure that the build configuration you choose on the Package/Publish Web tab when you select this option is the same one that you specify for deployment on the Settings tab of the Publish Web wizard.

7. If the database is a SQL Server Compact database, you might also need to make sure that the database engine is deployed. For more information, see Deploying SQL Server Compact Databases on the ASP.NET web site.

Previewing Changes and Publishing the Project

When you are finished configuring all of the databases, click Next to advance to the Preview tab.

To preview changes and publish the project

1. If you want to see a preview that lists the files that will be copied to and deleted from the hosting provider, click Start Preview.

   After a short wait, the list of files appears in the tab.

   

   The first time you publish, all of the files that are required to run your application are copied to the hosting provider. When you publish updates, only changed files are copied. (Except for the Web.config file: Visual Studio can't predict what changes might result from transformations and Web Deploy parameters, so it always copies the Web.config file.) If you chose the Remove additional files at destination option, it is especially important to check the preview list before you publish.

2. If you selected Update database for a database and you want to see what will be done to that database, click the Preview database link that appears to the right of the database. (You can't preview changes that you are deploying by using Entity Framework Code First Migrations.) The Database Preview dialog box shows the script that will be run in the destination database. If the database is large, it could take a minute or more for this preview to appear.

   

3. When you are ready to deploy the project, click Publish. (Make sure that you have reviewed the information in Web Deployment Overview for Visual Studio and ASP.NET to determine if there are other deployment tasks that you need to do first.)

4. If you didn't already validate the connection when you configured the Connection tab, you might see a Certificate Error dialog box. For more information, see To validate settings on the Connection tab.

When the deployment process finishes, the Output window indicates whether deployment was successful.

If you entered a value for Destination URL on the Connection tab, your default browser opens to that URL after successful deployment.

If deployment fails, see the Error List window for error messages. For troubleshooting resources, see Web Deployment Content Map for Visual Studio and ASP.NET.

See Also

Concepts

Web Deployment Overview for Visual Studio and ASP.NET

Other Resources

ASP.NET Web Deployment – Recommended Resources