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

  • Article

This is the third in a series of walkthroughs that illustrate how to deploy a Web application project by using a Web deployment package. For more information about the series, see Walkthrough: Deploying a Web Application Project Using a Web Deployment Package (Part 1 of 4).

In this walkthrough you create a deployment package that will be used to deploy the Web application project to a staging environment. The package is created by using parameters that enable you to change some configuration values at installation time. This lets you use the same package also for deployment to a production server. This walkthrough illustrates the following tasks:

  • Creating a package for Release build configuration.

  • Transforming Web.config file settings for the destination environment.

  • Including custom SQL scripts during deployment.

  • Deploying the default ASP.NET membership database, but excluding account information that was 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.

Prerequisites

For a list of prerequisites, see Walkthrough: Deploying a Web Application Project Using a Web Deployment Package (Part 1 of 4).

Creating a Destination Database

As you did for the Debug build configuration in the first two walkthroughs, you will deploy the contents of both databases that are in the App_Data folder into a single database.

If someone else is setting up the destination environment for you, whoever is doing that must provide the connection string for the destination database. If you are creating the destination database yourself, you can perform the following procedure, which is like what you did in the first walkthrough.

Note

You can perform the following procedure on the destination server or on any other computer, as long as the database can be made accessible from the destination server. If you create the database on a computer that is not the destination server, you must make sure that the database can be accessed through a remote connection. Describing how to do that is outside of the scope of this walkthrough. For more information, see SQL Server Books Online.

To create a destination database

  1. 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.

  2. In the Server name box, enter localhost\SQLExpress.

  3. In the New database name box, enter AdventureWorksStaging.

  4. Click OK.

Setting the Active Build Configuration

In the earlier walkthroughs in this series, you configured deployment settings for the Debug build configuration. However, some deployment settings should be different for deploying to a staging server and to a production server. For example, you typically do not want to deploy .pdb files to a staging or production server, because .pdb files are used only for debugging. Therefore, you must create new deployment settings for the Release build configuration. The first step of that process is to make sure that the Release build configuration is selected.

To set the active build configuration

  1. In the Build menu, click Configuration Manager.

    The Configuration Manager dialog box is displayed.

  2. In the Active solution configuration drop-down list, select Release.

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

  3. Close Configuration Manager.

Specifying Deployment Packaging Settings

The next step is to specify which files and IIS settings should be deployed for the Release configuration and how the package should be created. In the following procedure, you do this by using the Package/Publish Web tab of the project's Properties page.

To specify deployment packaging settings for the Release configuration

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

  2. Select the Package/Publish Web tab.

  3. In the Configuration drop-down list, make sure that Active (Release) is selected.

  4. In the Items to deploy (applies to all deployment methods) drop-down list, make sure that Only files needed to run this application is selected.

  5. Select the Exclude generated debug symbols check box.

    You do not plan to enable debugging in staging or production. Therefore, you do not want to deploy .pdf files.

  6. Select the Exclude files from the App_Data folder check box.

  7. Make sure that the Include all databases configured in Package/Publish SQL tab check box is selected.

  8. Make sure that the Create deployment package as a zip file check box is selected.

  9. 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\Release\Package\AdventureWorks.zip

  10. In the IIS Web site/application name to use on the destination server box, enter Default Web Site/AdventureWorks.

  11. Save the changes to the Package/Publish Web tab.

Creating a Custom Script for the Membership Database

Database deployment settings for deploying to staging servers and production servers are like the settings that you entered for the Debug build configuration. The difference is that you do not want to deploy the test user accounts that you entered into the ASP.NET membership system. However, you cannot just specify Schema Only database deployment for the ASP.NET membership database. This is because one of the tables in the database contains configuration data that is required for the ASP.NET membership system. Therefore, you will create a custom script to add the configuration data.

You will specify that two scripts will run at deployment time. The first script is the one that is generated automatically for the Schema Only setting. The second script is your custom script.

In the following procedure, you create a custom script that inserts configuration data into the deployed aspnet_SchemaVersions table.

To create a custom script to insert data into the deployed aspnet_SchemaVersions table

  1. At a command-line prompt, enter the following Web Deploy command:

    "C:\Program Files\IIS\Microsoft Web Deploy\msdeploy.exe" -verb:sync -source:dbfullsql="data source=.\SQLEXPRESS;Integrated Security=SSPI;AttachDBFilename=[full path to aspnetdb.mdf]\aspnetdb.mdf;User Instance=true" -dest:dbfullsql="c:\temp\aspnet_SchemaVersions.sql

    This Web Deploy command creates a database script named aspnet_SchemaVersions.sql and saves the script in the C:\Temp folder. The script creates the membership database.

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

    Replace [full path to aspnetdb.mdf] with the actual path of the aspnetdb.mdf file. If the Program Files folder is on a different drive, substitute the appropriate drive letter. You can find the path of the aspnetmdb.mdf file in the Full Path property in the Properties window when you select aspnetmdb.mdf in Solution Explorer.

  2. Open aspnet_SchemaVersions.sql in a text editor such as Notepad and delete everything except Insert statements for the aspnet_SchemaVersions table.

    The aspnet_SchemaVersions.sql file now resembles the following example:

    INSERT [dbo].[aspnet_SchemaVersions] ([Feature], [CompatibleSchemaVersion], [IsCurrentVersion]) VALUES (N'common', N'1', 1)
GO
INSERT [dbo].[aspnet_SchemaVersions] ([Feature], [CompatibleSchemaVersion], [IsCurrentVersion]) VALUES (N'health monitoring', N'1', 1)
GO
INSERT [dbo].[aspnet_SchemaVersions] ([Feature], [CompatibleSchemaVersion], [IsCurrentVersion]) VALUES (N'membership', N'1', 1)
GO
INSERT [dbo].[aspnet_SchemaVersions] ([Feature], [CompatibleSchemaVersion], [IsCurrentVersion]) VALUES (N'personalization', N'1', 1)
GO
INSERT [dbo].[aspnet_SchemaVersions] ([Feature], [CompatibleSchemaVersion], [IsCurrentVersion]) VALUES (N'profile', N'1', 1)
GO
INSERT [dbo].[aspnet_SchemaVersions] ([Feature], [CompatibleSchemaVersion], [IsCurrentVersion]) VALUES (N'role manager', N'1', 1)
GO

  3. Save and close aspnet_SchemaVersions.sql.

Specifying Database Deployment Settings

In the following procedure, you specify which databases to deploy and how to deploy them. You also add the custom script that you created in the previous procedure.

To specify SQL Server scripts that will run during deployment

  1. Click the Package/Publish SQL tab.

  2. Click Import from Web.config.

  3. Make sure that the ApplicationServices-Deployment row in the Database Entries grid is selected.

  4. In the Connection string for destination database box, enter the connection string for the destination database. If you are deploying to the database that you created in a previous step, you can do this by following these steps:

    1. In Server Explorer, expand the Data Connections folder and select the AdventureWorksStaging database.

    2. In the Properties window, select the value of the Connection String property and copy it to the Windows Clipboard.

    3. In the Connection string for destination database box, paste the connection string.

    4. In the connection string, change localhost to the name of your computer.

      This is required because you will be deploying to a remote computer. When the deployment scripts run on that computer, or when the application runs there, localhost will no longer refer to your computer.

  5. Make sure that the Pull data and/or schema from an existing database check box is selected.

  6. Set the Database scripting options list to Schema Only.

  7. Add the aspnet_SchemaVersions.sql script that you created earlier by following these steps:

    1. Click the Add Script button.

    2. In the Select File dialog box, browse to C:\Temp\aspnet_SchemaVersions.sql, and then click the Open button. (If you saved the script in a different folder earlier in this walkthrough, use that folder name.)

      The aspnet_SchemaVersions.sql filescript is added to the Database Scripts grid.

  8. In the Database Entries table, select the AWLTConnectionString-Deployment row.

  9. In the Connection string for destination database box, enter the same connection string that you entered for the ApplicationServices database.

  10. Make sure that the Pull data and/or schema from an existing database check box is selected.

  11. Set the Database scripting options list to Schema and Data.

  12. Add a script that grants database read permission to the IIS application pool by following these steps:

    1. If you are deploying to the database that you created, modify the AdventureWorksGrant.sql script that you created in the first walkthrough in this series. Remove the CREATE LOGIN SQL command. If you are deploying to a database that someone else creates for you, that person should provide a script.

      The CREATE LOGIN command must be removed because the login is created for the server, not for a database.

    2. Click the Add Script button.

    3. In the Select File dialog box, browse to the script that you want to use and click the Open button.

      The script is added to the Database Scripts grid.

      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.

  13. Save the changes to the Package/Publish SQL tab.

Specifying Transacted Mode for the Custom Scripts

In the first walkthrough in the series, you edited the project file to specify that the AdventureWorksGrant.sql script should run in a transaction. This configured the deployment process so that all scripts would run in the same transaction mode. Because you have created new settings for the Release build configuration, you must make the same change for the Release build configuration. You must also make the same change for the new custom script that you added in this walkthrough (aspnet_SchemaVersions.sql).

In the following procedure, you make both of these changes in the project file.

To specify that the custom scripts should run in a transaction

  1. Open the AdventureWorks.csproj or AdventureWorks.vbproj file in a text editor such as Notepad.

    To browser to the project directory, right-click the project in Solution Explorer and then click Open Folder in Windows Explorer.

  2. 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)' == 'Release|AnyCPU' ">

  3. Find the PublishDatabaseSettings element within the PropertyGroup element.

  4. In the PublishDatabaseSettings element, find the ObjectGroup element that is named ApplicationServices-Deployment.

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

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

  6. 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.

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

  8. Save the changes and close the project file.

  9. When Visual Studio asks if you want to reload the project, click the Reload button.

  10. In the Build menu, click Clean AdventureWorks.

Configuring Web.config File Transformations

As you did for the Debug build configuration in the first walkthrough in this series, you must make sure that connection strings in the deployed Web.config file point to the appropriate database. In addition, before you deploy to a staging server, you want to make the following changes in the deployed Web.config file:

  • Disable debugging.

  • Increase the minimum password length to 8.

  • Set a machineKey value so that the site can run in a Web-farm environment. The machineKey value is typically different in the staging environment in the and production environment. Therefore, in order to use the same package in both environments, you must make sure that you can configure this value at installation time.

In the following procedure, you create a transform file for the Release build configuration that disables debugging and increases the password length.

To configure transformations for the deployed Web.config file

  1. In Solution Explorer, expand the Web.config file node.

  2. Open the Web.Debug.config file.

  3. Copy the complete connectionStrings element to the Windows Clipboard.

  4. Close Web.Debug.config.

  5. Open the Web.Release.config file.

    Notice that you do not have to do anything in order to disable debugging. The default Web.Release.config file already contains markup that does this, as shown in the following example:

    <system.web>
  <compilation xdt:Transform="RemoveAttributes(debug)" />
  ...
</system.web>

  6. Delete the block of comments that contains a connectionStrings element, and paste the contents of the Clipboard in its place.

  7. Immediately after the compilation element, add the following markup:

    <machineKey 
   validationKey="staging" 
   decryptionKey="staging" 
   xdt:Transform="Insert" />

  8. Save and close the Web.Release.config file.

Creating a Deployment Parameter

In the following procedure, you create a deployment parameter that you can use to change the machineKey value when you install the package on the production server.

To create a deployment parameter for the machineKey value

  1. In Solution Explorer, right-click the project and then click Add New Item.

  2. In the Installed Templates panel, select C# or Visual Basic and then select the XML File template.

  3. In the Name box, enter Parameters.xml and then click Add.

  4. Delete <?xml version="1.0 encoding="utf-8" ?> and then add the following markup:

    <parameters>
  <parameter name="machineKey" 
    description="Please provide the machineKey value."
    defaultValue="staging"
    tags="">
    <parameterEntry kind="XmlFile"
      scope="obj\\Release\\Package\\PackageTmp\\Web\.config$"
      match="//machineKey[@validationKey]" />
    <parameterEntry kind="XmlFile"
      scope="obj\\Release\\Package\\PackageTmp\\Web\.config$"
      match="//machineKey[@decryptionKey]" />
  </parameter>
</parameters>

    This markup creates a parameter that is named machineKey. If you use IIS Manager to install the package that you create, the description attribute value is displayed as the label for the box where you can enter the machineKey value.

    The parameterEntry elements specify where the value of this parameter is used. The kind attribute specifies that the value will be inserted in an XML file. The scope attribute uses a regular expression to specify which XML file to update. (The path reflects the path of the Web.config file when the package was created, not the path as it will be in the deployed Web application.) The match attribute uses an XPath expression to select the attributes to be updated, which are the validationKey and decryptionKey attributes of the machineKey element.

Creating the Package

In the following procedure, you create a package that can be used to deploy to both a staging server and to a production server.

To create a package

  • In the Project menu, click Build Deployment Package.

    Visual Studio builds the project and then creates the deployment package, displaying a log in the Output window. In the final walkthrough of this series you will install this package on a remote server.

Next Steps

In the first two walkthroughs in this series you deployed a file-system Web application project to an IIS Web application in order to test it on the development computer. In this walkthrough you created a package that you can deploy to a remote computer by using the deploy.cmd file that Visual Studio generates when it creates the package.

The next and last walkthrough in the series is Walkthrough: Deploying a Web Application Project Using a Web Deployment Package (Part 4 of 4). In that walkthrough, you will actually deploy the package.

See Also

Concepts

ASP.NET Deployment Content Map