Walkthrough: Deploying a Web Application Project Using a Web Deployment Package (Part 1 of 4)

Article
02/13/2013

This is the first in a series of walkthroughs that illustrate how to deploy a Web application project by using a Web deployment package. In this series you will create a file system Web application project. You will first deploy it to your local computer for local IIS testing, and then deploy it to a staging server. The deployment package that you use to deploy to the staging server will be configured so that it can be used also for deployment to a production server.

Note

Web deployment tools have been improved in Visual Studio 2012. You can install the improved tools in Visual Studio 2010 and Visual Web Developer 2010 Express by installing the Visual Studio Web Publish Update. For information about how to use the new tools, see the documentation for Visual Studio 2012. A good place to start is Web Application Project Deployment Overview for Visual Studio and ASP.NET.

The series of walkthroughs illustrates the following tasks:

Creating a package for the Debug build configuration.
Creating a package for the Release build configuration.
Transforming Web.config file settings for the destination environment.
Including custom SQL scripts during deployment.
Redeploying a database that has already been deployed.
Excluding a database that has already been deployed from deployment.
Deploying multiple development databases to a single destination database.
Deploying the default ASP.NET membership database both with and without account information that is created on your local computer.
Using custom deployment parameters for configuration values that you want to be able to change when the package is installed.
Installing a package on the local computer by using IIS Manager.
Installing a package on a remote computer by using the deploy.cmd file.

This walkthrough illustrates the following tasks:

Creating a package for Debug build configuration.
Transforming Web.config file settings for the destination environment.
Deploying multiple development databases to a single destination database.
Including custom SQL scripts during deployment.
Deploying the default ASP.NET membership database using account information that is created on your local computer.
Installing a package on the local computer by using IIS Manager.

Prerequisites

In order to complete the series of walkthroughs, you will need the following:

Visual Studio or Visual Web Developer Express.

Note

If you are using Visual Studio, the walkthrough assumes that you selected the Web Development collection of settings when you started Visual Studio the first time. For more information, see How to: Select Web Development Environment Settings.
SQL Server Express 2008 or a later version. (By default, this is installed with Visual Studio.)
The .mdf file version of the AdventureWorksLT database. This file is available for download as SQL2008.AdventureWorksLT2008_Only_Database.zip from Microsoft SQL Server: Database Product Samples on the CodePlex Web site.
IIS 7 enabled on your local computer.
ASP.NET 4 registered with IIS 7 on your local computer, and an ASP.NET 4 application pool assigned to the Default Web Site. For more information, see ASP.NET IIS Registration Tool (Aspnet_regiis.exe).
Administrative rights on your local computer.

In addition, in order to complete deployment package installation for the fourth walkthrough, you must have the following:

A second computer that you can deploy to. The second computer must also have IIS 7 enabled, ASP.NET 4 must be registered with IIS 7, and an ASP.NET 4 application pool must be assigned to the Default Web Site. If you set up this computer, you will need administrative rights on it. If someone else sets it up for you, you might need administrative rights on it, depending on the deployment method that you use. For more information, see Walkthrough: Deploying a Web Application Project Using a Web Deployment Package (Part 4 of 4), which is the walkthrough that requires the second computer.

Creating a Web Project to Deploy

In the following procedure, you create a Web application project to deploy by using the Visual Studio ASP.NET Web Application project template. You will create the ASP.NET default membership database, add the AdventureWorksLT database, and add controls to display data from the AdventureWorksLT database.

To create a Web project to deploy

In Visual Studio, in the File menu, click New Project.

Note

Make sure that you select New Project and not New Web Site. Deployment packaging works only with Web application projects.

The New Project dialog box is displayed.
In the Installed Templates window, expand Visual Basic or C# and then select Web.
Select the ASP.NET Web Application template.

The New Project dialog box resembles the following illustration:
In the Name box, enter AdventureWorks.
Click OK.

Visual Studio creates the Web application. The App_Data folder is created to contain databases for this application, but there is no database in it yet.
In Solution Explorer, expand the Account folder, right-click the Register.aspx file, and then click View in Browser.

The Create a New Account page is displayed, as shown in the following illustration:
Enter newuser for User Name, enter newuser for Password, enter an e-mail address, and then click Create User.

An ASPNETDB.MDF SQL Server database file is created in the App_Data folder, and the credentials that you have provided are entered into it. To see the .mdf file in Solution Explorer, click the Show All Files button in the Solution Explorer toolbar.
Extract the contents of the SQL2008.AdventureWorksLT2008_Only_Database.zip file into your project's App_Data folder. For information about this sample database, see Prerequisites earlier in this topic.
Open the Web.config file.

In the connectionStrings element, add a connection string for the AdventureWorksLT database, as shown in the following example:

<connectionStrings>
  <add name="ApplicationServices"
      connectionString="data source=.\SQLEXPRESS;Integrated Security=SSPI;AttachDBFilename=|DataDirectory|\aspnetdb.mdf;User Instance=true"
      providerName="System.Data.SqlClient" />
  <add name="AWLTConnectionString" 
      connectionString="data source=.\SQLEXPRESS;Integrated Security=SSPI;AttachDBFilename=|DataDirectory|\AdventureWorksLT2008_Data.mdf;User Instance=true"
      providerName="System.Data.SqlClient" />
</connectionStrings>

Save and close the Web.config file.
Open the Default.aspx file.

The file is displayed in Source view.

Delete the h2 and p elements, and then add the following markup in their place:

<h2>
  Welcome to AdventureWorks!
</h2>
<asp:SqlDataSource ID="SqlDataSource1" runat="server" 
    ConnectionString="<%$ ConnectionStrings:AWLTConnectionString %>" 
    SelectCommand="SELECT SalesLT.Product.* FROM SalesLT.Product">
</asp:SqlDataSource>
<asp:GridView ID="GridView1" runat="server" AutoGenerateColumns="False" 
    DataKeyNames="ProductID" DataSourceID="SqlDataSource1">
    <Columns>
        <asp:BoundField DataField="Name" HeaderText="Name" 
            SortExpression="Name" />
        <asp:BoundField DataField="Color" HeaderText="Color" 
            SortExpression="Color" />
        <asp:BoundField DataField="ListPrice" HeaderText="ListPrice" 
            SortExpression="ListPrice" />
        <asp:BoundField DataField="Size" HeaderText="Size" 
            SortExpression="Size" />
        <asp:BoundField DataField="Weight" HeaderText="Weight" 
            SortExpression="Weight" />
    </Columns>
</asp:GridView>

This markup changes the application title to Adventure Works and adds a GridView control that displays data from one of the AdventureWorksLT tables. This control will enable you to verify that the AdventureWorks LT data is deployed successfully.

Save and close the Default.aspx file.
Optionally, change the heading in the master page by following these steps:
1. Open the Site.master file.
2. Delete My ASP.NET Application and replace it with Adventure Works.
3. Save and close the file.
Test the site by following these steps:
1. Press CTRL-F5 to test the application.
  
  The Default.aspx page is displayed in the browser. The page shows a list of Adventure Works products, as shown in the following illustration:
2. Click the Log In hyperlink.
  
  The Log In page is displayed.
3. Enter newuser for both the User Name and Password, and then click Log In.
  
  The Default.aspx page opens and shows Welcome newuser! in the upper-right corner, as shown in the following illustration:
4. Close the browser.

Creating a Destination Database

The Web project currently has two databases. You will deploy the contents of both databases into a single database. In a production environment, it can be more cost effective to maintain and manage one database instead of two.

In the following procedure, you create the empty destination database that you will deploy to.

To create a destination database

In Server Explorer, right-click Data Connections, and then click Create New SQL Server Database.

The Create New SQL Server Database dialog box is displayed.
In the Server name box, enter localhost\SQLExpress.
In the New database name box, enter AdventureWorksTest.

When you have entered the database name, the Create New SQL Server Database dialog box resembles the following illustration:
Click OK.

The new database is created and is displayed in the Data Connections folder in the Server Explorer window, as shown in the following illustration:

Creating a Grant Script for the Destination Database

When the Web application is deployed in IIS, it will be assigned to the default ASP.NET 4 application pool, and this database will be accessed by using the application pool's credentials. Therefore, you must also create a script that grants read permission to those credentials.

In the following procedure, you create a script that you will run to grant database read permission to the application pool credentials.

To create a script that grants read permission to the application pool

Open a text editor such as Notepad.
Create a new text file and insert the following Transact-SQL statements in it:
```
CREATE LOGIN [IIS APPPOOL\ASP.NET v4.0] 
  FROM WINDOWS WITH DEFAULT_DATABASE=[master], 
  DEFAULT_LANGUAGE=[us_english]
GO
CREATE USER [AdventureWorksUser] 
  FOR LOGIN [IIS APPPOOL\ASP.NET v4.0]
GO
EXEC sp_addrolemember 'db_datareader', 'AdventureWorksUser'
GO
```
Note

This script is designed to work with the default security settings in Windows 7 and Windows Server 2008 R2. If you are using an earlier version of Windows, or if your computer has custom security settings, this script might not make your database available to the credentials that your Web site uses when it runs in IIS. For more information about SQL Server security, see SQL Server Books Online.
Name the file AdventureWorksGrant.sql and save it in a folder on your computer, such as C:\Temp.

You can save the script in any folder. Remember the location, because you will access the script later in this walkthrough.

Setting the Active Build Configuration

By default, the active build configuration for new projects is Debug. You will use this build configuration for the initial deployment to IIS on your local computer. In the following procedure, you make sure that the correct build configuration is selected.

To set the active build configuration

In the Build menu, click Configuration Manager.

The Configuration Manager dialog box is displayed.
In the Active solution configuration list, make sure that Debug is selected.

The Active solution configuration list is also typically displayed on the Standard toolbar. If it is displayed there, you can verify or change the build configuration without opening Configuration Manager.
Close Configuration Manager.

Specifying Deployment Packaging Settings

In the following procedure, you specify which files and IIS settings should be deployed, and how the package should be created.

To specify deployment packaging settings

In Solution Explorer, right-click the project and then click Properties.

The Properties page is displayed.
Select the Package/Publish Web tab.

The Package/Publish Web tab is displayed, as shown in the following illustration:

In the Configuration list, make sure that Active (Debug) is selected. By default, the active build configuration is selected. In the previous procedure you set the active build configuration to Debug.
In the Items to deploy (applies to all deployment methods) list, make sure that the Only files needed to run this application check box is selected.

For more information about how Visual Studio determines which files to deploy, see the question "Why don't all of the files in my project folder get deployed?" in ASP.NET Web Application Project Deployment FAQ.
Make sure that the Exclude generated debug symbols check box is cleared.

For this part of the walkthrough, you are configuring deployment to a computer for testing. Therefore, you want to be able to debug.

Note

The ability to run a deployed site in debug mode depends on this option and on a Web.config file setting. It does not depend on the name of the build configuration.
Select the Exclude files from the App_Data folder check box.

The project uses SQL Server Express .mdf files in the App_Data folders, but you will deploy it by running scripts in an empty destination database. Therefore, you will not deploy the .mdf files.
Make sure that the Include all databases configured in Package/Publish SQL tab check box is selected. (You will configure the Package/Publish SQL tab in the following procedure.)
Make sure that the Create deployment package as a zip file check box is selected.

Deployment tools work with packages as .zip files. If this check box is cleared, the package will be created as files in a folder structure. That is typically done to create an archival copy of the deployed site.
Make sure that the Location where package will be created box contains the following value (which is the default value if you specified AdventureWorks as the project name):

obj\Debug\Package\AdventureWorks.zip
In the IIS Web site/application name to use on the destination server box, enter Default Web Site/AdventureWorks.
Save the changes to the Package/Publish Web tab.

Specifying Database Deployment Settings

In the following procedure, you specify databases to deploy and how they will be deployed. You also specify that the AdventureWorksGrant.sql script that you created in a previous procedure should run during deployment.

To specify SQL Server scripts that will run during deployment

Click the Package/Publish SQL tab.

The Package/Publish SQL tab is displayed, as shown in the following illustration:
Click Import from Web.config.

Visual Studio reads the application Web.config file to find connection strings. For each connection string in the Web.config file, Visual Studio creates a row in the Database Entries grid. By default, the name in the Database Entries grid is the connection string name plus a -Deployment suffix.

For this walkthrough, two rows are created. One is named ApplicationServices-Deployment and one is named AWLTConnectionString-Deployment, as shown in the following illustration:
Make sure that the ApplicationServices-Deployment row in the Database Entries table is selected.

The fields underneath the Database Entries grid apply to the selected row in the Database Entries grid. If no row is selected, the fields underneath the table are disabled.
In the Connection string for destination database box, enter the connection string for the AdventureWorksTest database that you created in a previous procedure. You can do this by following these steps:
1. In the Server Explorer window, expand the Data Connections folder and select the AdventureWorksTest database.
2. In the Properties window, select the value of the Connection String property and copy it. The Properties window resembles the following illustration:
3. Paste the connection string into the Connection string for destination database box.
Make sure that the Pull data and/or schema from an existing database check box is selected.

When you clicked Import from Web.config, this option was automatically selected. The Connection string for the source database box was also automatically filled in using the connection string from the Web.config file.
Set the Database scripting options list to Schema and Data.

After deployment, the destination database will include the user account credentials that you created when you created the project.
In the Database Entries table, select the AWLTConnectionString-Deployment row.

Default values are displayed in the fields that are underneath the grid.
In the Connection string for destination database box, enter the same destination connection string that you entered for the ApplicationServices database.

You are using the same destination connection string for both databases. Therefore, during deployment the scripts that create and populate database objects will all run in the same database. The result will be that the destination database will contain all the tables and other database objects from both project databases.
Make sure that the Pull data and/or schema from an existing database check box is selected.
Set the Database scripting options list to Schema and Data.
Click Add Script.
In the Select File dialog box, browse to C:\Temp\AdventureWorksGrant.sql, and then click Open. (If you saved the script in a different folder earlier in this walkthrough, use that folder name.)

The AdventureWorksGrant.sql file is added to the Database Scripts grid, as shown in the following illustration:
Save the changes to the Package/Publish SQL tab.

Specifying Transacted Mode for the Custom Script

By default, the automatically generated scripts run in a transaction. However, custom scripts do not. If you mix transaction modes, you might get a timeout error when the scripts run during deployment.

In the following procedure, you edit the project file in order to configure the custom script that you added in the preceding procedure to run in a transaction.

To specify that the custom script should run in a transaction

Open the AdventureWorks.csproj or AdventureWorks.vbproj file that uses a text editor such as Notepad.

To browse to the project directory, right-click the project in Solution Explorer and then click Open Folder in Windows Explorer.
Find the PropertyGroup element that pertains to the Debug build configuration.

The opening tag for the element resembles the following example:

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
In the PropertyGroup element, find the PublishDatabaseSettings element.
In the PublishDatabaseSettings element, find the ObjectGroup element that is named AWLTConnectionString-Deployment.

The second Object element in this ObjectGroup element is for the AdventureWorksGrant.sql script.

In the Object element that is for the AdventureWorksGrant.sql script, change the value of the Transacted attribute of the Source element to True.

The AWLTConnectionString-Deployment ObjectGroup element now resembles the following example:

<ObjectGroup Name="AWLTConnectionString-Deployment" Order="2">
  <Destination Path="..." />
  <Object Type="dbFullSql" Enabled="True">
    <PreSource Path="..." ScriptSchema="True" ScriptData="True"
      CopyAllFullTextCatalogs="False" ScriptDropsFirst="True" />
    <Source Path="..." Transacted="True" />
  </Object>
  <Object Type="dbFullSql" Enabled="False">
    <Source Path="...\AdventureWorksGrant.sql" Transacted="True" />
  </Object>
</ObjectGroup>

Save the changes and close the project file.
When Visual Studio asks if you want to reload the project, click the Reload button.

Changing the Connection String in the Deployed Web.config File

In the following procedure, you create a transform file that causes the database connection strings in the deployed Web.config file to be set to the correct value for the destination environment.

To change the connection string in the deployed Web.config file

In Solution Explorer, expand the Web.config file.
If a file that is named Web.Debug.config is not present, right-click the Web.config file and then click Add Config Transforms.
Open the Web.Debug.config file.

Delete the block of comments that contains a connectionStrings element and replace it with the following markup. Replace [connection string] with the value that you entered in the Connection string for destination database box.

<connectionStrings>
  <add name="ApplicationServices"
       connectionString="[connection string]"
       providerName="System.Data.SqlClient" 
       xdt:Transform="SetAttributes" xdt:Locator="Match(name)" />
  <add name="AWLTConnectionString"
       connectionString="[connection string]"
       providerName="System.Data.SqlClient" 
       xdt:Transform="SetAttributes" xdt:Locator="Match(name)" />
  </connectionStrings>

Save and close the Web.Debug.config file.

Deploying the Web Application

The next step is to deploy the project by creating a package. You can then import the package into IIS by using IIS Manager.

To create a package and import it into IIS

In the Project menu, click Build Deployment Package.

Visual Studio builds the project and creates the deployment package, displaying a log in the Output window. As part of the package creation process, the Web Deploy dbFullSQL provider creates two SQL server scripts, one for each source database. There is only one destination database, and both of these scripts will run in that database when you import the package. The following example shows sections of the Output window contents.
------ Build started: Project: AdventureWorks, Configuration: Debug Any CPU ------
...

------ Publish started: Project: AdventureWorks, Configuration: Debug Any CPU ------

Transformed Web.config using Web.Debug.config into

obj\Debug\TransformWebConfig\transformed\Web.config.

...

Copying all files to temporary location below for package/publish:

obj\Debug\Package\PackageTmp.

Adding MSDeploy.dbFullSql (MSDeploy.dbFullSql).

...

Adding child sqlScript (MSDeploy.dbFullSql/

dbFullSql[@path='c:\users\username\documents\visual studio 2010\

Projects\AdventureWorks\AdventureWorksCS\obj\Debug\AutoScripts\

ApplicationServices-Deployment_SchemaAndData.sql']/sqlScript).

...

Adding declared parameter 'IIS Web Application Name'.

Adding declared parameter 'ApplicationServices-Deployment Connection String'.

Adding declared parameter 'AWLTConnectionString-Deployment Connection String'.

Package "AdventureWorks.zip" is successfully created as single file

at the following location:

file:///c:/users/username/documents/visual%20studio%202010/

Projects/AdventureWorks/AdventureWorksCS/obj/Debug/Package

...

========== Build: 1 succeeded or up-to-date, 0 failed, 0 skipped ==========

========== Publish: 1 succeeded, 0 failed, 0 skipped ==========
Copy the path of the deployment package to the Windows Clipboard by following these steps:
1. In Solution Explorer, if you do not see the obj folder, click the Show All Files button in the Solution Explorer toolbar.
2. Expand the obj folder, expand the Debug folder, and then expand the Package folder.
3. Select the AdventureWorks.zip file.
4. In the Properties window, select and copy the value of the Full Path field.
In Windows Control Panel, click Administrative Tools, and then click Internet Information Services (IIS) Manager.

IIS Manager opens and your computer is selected in the Connections panel.
In the Connections panel, expand the node for your computer, expand the Sites folder, and then select Default Web Site.

IIS Manager now resembles the following illustration:
In the Actions panel, click Import Application.

Note

This link is ordinarily present when Web Deploy is installed, and Web Deploy is installed by default when you install Visual Studio. If the link is missing, in Control Panel, open Programs and Features, right-click Web Deployment Tool, and then click Repair.

The Import Application Package wizard opens and shows the Select the Package dialog box.
In the Package path box, paste the path that you copied in an earlier step.

The Select the Package dialog box resembles the following illustration:
Click Next.

The Select the Contents of the Package dialog box is displayed as shown in the following illustration:
Click Next.

The Enter Application Package Information dialog box is displayed as shown in the following illustration:

The default values for the application path and connection strings are the values that you set in the Package/Publish Web tab.
Click Next.
If you see a dialog box that asks you to verify that ASP.NET 4 is installed on your computer (as shown in the following illustration), assign an ASP.NET 4 application pool to the Default Web Site.

To do so, follow these steps:
1. In the Enter Application Package Information dialog box, click Cancel.
2. In the Windows Start menu, right-click Command Prompt and then click Run as Administrator.
3. Browse to the appropriate folder for .NET Framework 4, such as the following:
  
  C:\Windows\Microsoft.NET\Framework\v4.0.30319
  
  If the Windows folder on your computer is on a different drive, replace C with the appropriate drive letter. For a 64-bit operating system, use Framework64 instead of Framework.
4. Enter the command aspnet_regiis -iru -enable and then press ENTER.
  
  The tool registers ASP.NET with IIS. For more information, see ASP.NET IIS Registration Tool (Aspnet_regiis.exe).
5. Close the Command Prompt window.
6. In IIS Manager, select Default Web Site and then click Basic Settings in the Action panel.
7. Change the Application Pool to the ASP.NET v4.0 application pool. (You can set this back to its original value after you finish the walkthrough.)
8. Repeat the previous steps for installing the package, starting with the Import Application hyperlink on the Actions panel of IIS Manager.
While Web Deploy installs the package, the Installation Progress and Summary dialog box is displayed. The dialog box shows a progress bar during the installation process. When the process is complete, the dialog box shows a log of what was done, as shown in the following illustration:
Click Finish.

Testing the Deployed Web Application

The final step for this walkthrough is to verify that the Web application was deployed correctly.

To test the Web application

Open a browser and enter the following URL:

https://localhost/AdventureWorks

The Default.aspx page is displayed. It looks the same as it does when you run it in Visual Studio. The table of products demonstrates that the AdventureWorksLT database was deployed successfully.
Click the Log In link.
Enter newuser for the Username and Password and then click Log In.

The Default.aspx page is displayed again, with Welcome newuser! next to the Log Out link. This demonstrates that the ASP.NET membership database was deployed successfully.

Next Steps

In this walkthrough you created a file-system Web application project that contains two databases. You deployed it to an IIS Web application that uses a single database.

The next walkthrough in the series is Walkthrough: Deploying a Web Application Project Using a Web Deployment Package (Part 2 of 4). In that walkthrough, you change the structure of one of the databases and change Web pages, and then deploy the changes.