Using Web Deployment Projects with Visual Studio 2005
Abstract
Download URL:
http://download.microsoft.com/download/c/c/b/ccb4877f-55f7-4478-8f16-e41886607a0e/WebDeploymentSetup.msi
Visual Studio 2005 provides deployment support though its
Copy Web Site and Publish Web Site features. While these are ideal for many
scenarios, there are other, more advanced scenarios where developers need the
following capabilities:
More control over assembly naming and output.
Custom pre-processing and post-processing for the build.
The ability to exclude, add, and transform files and directories during builds.
The ability to modify the Web.config file to change database connection strings, application settings, or the URLs for Web references, depending on the build configuration. (For example, it might be necessary to use different values for development, test, staging, and release settings).
This white paper describes a solution to these advanced scenarios and introduces a new feature called Web Deployment Projects for Visual Studio 2005.
Web Deployment Projects
Web Deployment Projects is an add-in package to Visual Studio 2005. It does not change the behavior of any feature in Visual Studio 2005; it simply adds additional functionality specific to Web site deployment.
A Web Deployment project is an MSBuild project file for a Web site. It fully integrates into the Visual Studio 2005 build configuration manager and supports configuration options for compilation and deployment, such as Debug and Release. A Web Deployment project is extensible, enabling you to create pre-build and post-build actions.
Web Deployment projects do not change the way Visual Studio 2005 Web site projects build. Instead, they take an existing Web site project as input and generate a precompiled Web site as output. A Web Deployment project does not change the files in the source Web site project in any way.
Feature Summary
A Web Deployment project provides the following features for building and deploying ASP.NET 2.0 Web sites:
ASP.NET 2.0 precompilation as part of the build process.
More flexible options for generating compiled assemblies from a Web project, including these alternatives:
A single assembly for the entire Web site.
One assembly per content folder.
A single assembly for all UI components.
An assembly for each compiled file in the Web site.
Assembly signing options.
The ability to define custom pre-build and post-build actions.
The ability to exclude folders from the build.
The ability to modify settings in the Web.config file, such as the <connectionString> element, based on the Visual Studio build configuration.
Support for creating .msi files with setup projects.
The extensibility of Web Deployment projects enables you to tailor the build and deploy process to suit your needs. This is done without sacrificing the optimized workflow improvements achieved with Visual Studio 2005 Web site projects.
Installing Web Deployment Projects
Installing Web Deployment projects installs both a Visual Studio 2005 add-in package and the new ASP.NET merge utility (aspnet_merge.exe).
By default, the installation process installs files into the locations listed in the following table.
|
Location |
Files |
|
C:\Program Files\MSBuild\Microsoft\WebDeployment\v8.0 |
aspnet_merge.exe Microsoft.WebDeployment.targets Microsoft.WebDeployment.Tasks.dll |
|
C:\Program Files\Microsoft Visual Studio 8\Common7\Packages |
MsWebDeployProj.dll WebDeploy.wdproj |
|
C:\Program Files\Microsoft Visual Studio 8\Common7\Packages\1033 |
MsWebDeployProjUi.dll |
You can install Web Deployment projects on a computer that does not have Visual Studio 2005 installed. This is useful if you want to use MSBuild features on a dedicated build computer. MSBuild is part of the Microsoft .NET Framework version 2.0 and does not require installation of Visual Studio 2005.
New Menu Commands
Installing Web Deployment Projects adds the Add Web Deployment Project command to the Build menu and to the shortcut menu for the selected Web project in Solution Explorer. The new command is supported only for local IIS Web sites and for file system Web sites. Web Deployment Projects do not support remote FrontPage or FTP Web sites.
Note The Add Web Deployment Project command is the only way to add a Web Deployment project to the solution. This new project type is not available in the New Project dialog box.
When you create a Web Deployment project, the new Web Deployment project is associated with the Web site you created it for. Generally there is a one-to-one relationship between the Web site and the Web Deployment project. Each Web site in a solution can have its own Web Deployment project. You can also optionally create multiple Web Deployment projects for the same site.
Advanced scenarios merging multiple Web sites into a single Web site can be achieved through custom build actions as described in the section Customizing Web Deployment Projects later in this paper.
Adding a Web Deployment Project
To add a Web Deployment project to a Web site, follow these steps.
1. In Solution Explorer, select the name of the Web site to work with.
2. In the Build menu, choose Add Web Deployment Project.
The Add Web Deployment Project dialog box is displayed:
3. Specify a name and location for the project.
By default, the project name is the same as the Web site with _deploy appended to the name. The default location is in the same folder as the solution.
In the example shown here, the Web site path is C:\MyProjects\MyWeb. The project file will be named MyWeb_deploy.webdeployproj, and the project folder path will be C:\MyProjects\MyWeb_deploy\.
4. Click OK.
A new project is added to the solution and automatically associated with the Web site. The new Web Deployment project is now part of the build process.
Tip When creating a new Web site project that you will add other projects to (such as a class library project or a Web Deployment project), start by creating an empty solution in the location of your choice. Then add the new Web site to that solution. This ensures that Visual Studio puts all of the project files in the same set of directories and subdirectories.
The new Web Deployment project does not contain any files or child nodes in the solution hierarchy. Instead, it is an MSBuild project file that enables you to customize the build rules for the associated Web site.
You can view properties for the current Web Deployment project in the Properties window. (These properties are distinct from the settings for build configurations, which you edit using the Property Pages dialog box, as discussed in the next section.)
Web Deployment Project Property Pages
You can create and edit individual configurations for the current Web Deployment project using the Property Pages dialog box. (This dialog box is available by right-clicking the project in Solution Explorer and then selecting Property Pages). The Property Pages dialog box for a Web Deployment project displays four property pages:
Compilation
Output Assemblies
Signing
Deployment
The properties on each of these property pages can have unique values for each build configuration. Visual Studio 2005 provides two default configurations: Debug and Release. You can use these predefined configurations or define new configurations (such as Staging or Production), depending on your needs. All the settings you make in the Property Pages dialog box apply to the selected configuration.
Compilation Page
The Compilation page of the Web Deployment project抯 property pages dialog box looks like the following:
The following table describes the properties you can set in the Compilation page.
|
Setting |
Description |
|
Output folder |
Specifies the folder to contain the precompiled image of the Web site. The default is to create a subfolder with the same name as the configuration in the folder where the Web Deployment project file is stored. |
|
Generate debug information |
Generates .pdb files when compiling. This setting will also update the value of the <compilation debug="true"/> element in the configuration file of the precompiled Web site. |
|
Use IIS Metabase path for source input |
Specifies the full IIS metabase path of the source Web site application. This setting corresponds to the 杕 option of the aspnet_compiler.exe command. For example, a metabase path might be /LM/W3SVC/1/ROOT/MyWeb/, where MyWeb is the virtual directory. This setting is useful if your Web site contains one or more sub-Web sites. During compilation, the compiler processes all 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. To compile the sub-Web sites, you must add a separate Web Deployment project for each of the sub-Web sites. |
|
Allow this precompiled site to be updatable |
Enables ASP.NET Web pages and user controls (.aspx and .ascx files) to be updated after compilation; only the code-behind files are compiled. If this option is not checked, the HTML markup for pages and controls is removed and compiled into the assembly output. |
Output Assemblies Page
The Output Assemblies page of the Web Deployment project抯 property pages dialog box looks like the following:
The following table describes the properties you can set in the Output Assemblies page.
|
Setting |
Description |
|
Merge all outputs to a single assembly |
Merges all the output assemblies from the compiler into a single assembly. This setting is equivalent to the -o assemblyname option of the aspnet_merge.exe command. This results in the same behavior that Visual Studio .NET 2003 supports , where one assembly is generated for each Web project. |
|
Treat as library component |
Removes the App_code.compiled file. This enables the project's App_Code.dll assembly to be added to the Bin folder of another Web site without conflicting with the App_Code.dll assembly in the other Web site. This setting is equivalent to the -r option of the aspnet_merge.exe command. This option is useful for building a library of .ascx controls. |
|
Merge each folder output to its own assembly |
Creates a separate output assembly for each folder. This enables you to update your Web site at the folder level rather than updating the entire application. This setting is equivalent to the -prefix prefixname option of the aspnet_merge.exe command. You can optionally specify a prefix that will be pre-pended to all generated assembly names. For example, if you specify the prefix MyCompany, the name becomes MyCompany.SubfolderName. |
|
Merge all pages and controls to a single assembly |
Merges the output assemblies for all pages and user controls in the Web site into a single assembly. This enables you to update UI elements separately from updating other code. Special folders such as App_Code, App_WebReferences, and so on are each compiled into a separate assembly. This setting is equivalent to the 杦 assemblyname option of the aspnet_merge.exe command. |
|
Create a separate assembly for each page and control |
Compiles each page and user control into a separate assembly. This setting does not run aspnet_merge.exe. Instead, it uses the -fixednames option of the aspnet_compiler.exe command. Note Compiling with the -fixednames option disables the compiler's batch optimizations and can result in longer compile times for large Web sites. This option is useful for granular updates of your deployed Web site. |
|
Version Output Assemblies Assembly Version File Version |
Sets the assembly version and/or the file version attribute of merged assemblies. The format is 0.0.0.0. This setting overrides the assembly attributes defined in the AssemblyInfo.vb or AssemblyInfo.cs file in the App_Code directory. This setting is equivalent to the -copyattrs assemblyfile option of the aspnet_merge.exe command. |
Signing Page
The Signing page of the Web Deployment project抯 property pages dialog box looks like the following:
The following table describes the properties you can set in the Signing page.
|
Setting |
Description |
|
Key file location |
Specifies the path to the keyfile used to sign the assemblies. Keyfiles are produced with the Sn.exe utility included with the .NET Framework SDK. |
|
Delay signing |
Compiles the assemblies with delay signing. This enables the assemblies to be signed as part of a post-build process. |
|
Mark assemblies with AllowPartiallyTrustedCallers attribute (APTCA). |
Specifies that types in strongly named assemblies can be called by partially trusted code only when the assemblies have been marked with the AllowPartiallyTrustedCallers attribute (APTCA). This attribute removes the implicit link demand for the Full trust permission set that is otherwise automatically enforced on each publicly accessible method in each type. |
Deployment Page
The Deployment page of the Web Deployment project抯 property pages dialog box looks like the following:
The following table describes the properties you can set in the Deployment page.
|
Setting |
Description |
|
Enable Web.config file section replacement |
Enables the replacement of any section in the root Web.config file with the content of a matching section in a separate (external) .config file. The external file can contain only the section being replaced. This option enables you to define elements that are written to the root Web.config file at deployment time, which in turn provides a way to create deployment-specific configuration sections. |
|
Enforce matching section replacements |
Requires that the specified section in the Web.config file have the same number of elements as the replacement section in the external .config file. A build error occurs if there is a mismatch in the number of elements. This option helps you detect when changes have been made to the Web.config file but are not reflected in external .config files. |
|
Use external configuration source file |
Updates the Web.config file by replacing existing sections with elements that reference a .config file, using the configSource attribute: <appSettings ?configSource="appSettings.config" /> If this option is not selected, the section is replaced entirely with the elements in the .config file. This option is useful for changing the database connection strings or Web reference URLs for each build configuration. |
|
Create an IIS virtual directory for the output folder |
Creates an IIS virtual directory pointing to the output folder for this build configuration, using the name you specify. This is useful for immediate testing of the precompiled Web application. To avoid conflict with other configurations, include the configuration name as part of the virtual directory name. For example, use virtual directory names such as MyWeb_Staging and MyWeb_Release. |
|
Replace the existing virtual directory |
If the virtual directory already exists and is pointing to a different folder, updates the metabase to point to the output folder for this configuration . If this option is not selected, an error occurs if the virtual directory path does not match the output folder. |
|
Remove the App_Data folder |
Removes the App_Data folder from the precompiled image of the Web site. This is useful if you are changing connection strings to access a SQL Server database and no longer require a SQL Server Express or Access database in the App_Data folder. |
Managing Custom Build Configurations
Using Visual Studio build configurations, you can define the specific build processes that are necessary for producing a staging or release build of your Web application. There are three build configurations commonly used for building Web site applications:
Debug build configuration This is the default build configuration used at design time. In team development scenarios, it is often desirable to isolate developers so that they do not overwrite one another's changes while editing and debugging. In those cases, developers typically use either a local IIS Web site (and a locally installed instance of IIS) or a file system Web site and the built-in ASP.NET development server. Similarly, each developer will typically use a local SQL Server, SQL Server Express, or Access database. Developers can even implement Web services locally and consume them using a Web reference that points to http://localhost/.
Staging build configuration Once developers have a version of the Web site ready for testing, they can produce a build configured for a testing or staging environment. The staging environment is often a replica of the production or release environment. For example, a staging environment will likely use a shared SQL Server database containing test data. Web services may also be distributed across other computers in the staging environment.
Release build configuration When the Web site is ready for a production release, database connections and Web references must be changed to reflect the production environment. For optimal performance, it is also recommend that the Debug compilation mode be set to False in the application's Web.config file.
Web Deployment projects enable you to customize the build process and tailor the Web site application to the environment in which it will be deployed.
All property values for a Web deployment project apply to a specific build configuration. By changing the selected configuration, you can change the settings for a specific configuration. Alternatively, by selecting All Configurations, you can apply a change globally across all configurations.
To create a new configuration, in the project Property Pages dialog box, click the Configuration Manager button:
This displays the Configuration Manager dialog box. The configuration manager enables you to create new configurations and to specify which projects to build as part of that configuration.
Visual Studio exposes two levels of build configurations: solution configurations and project configurations. For more information about build configurations, see Build Configurations on the MSDN Web site.
The configuration manager shows the active solution configuration and the build configuration setting for each project for that solution configuration. After you add a Web Deployment project to the solution, the configuration manager lists both the Web site project and the Web Deployment project. By default, both projects are configured to build whenever the solution is built:
You should disable building the Web Deployment project in the Debug configuration. Building a Web Deployment project unnecessarily increases the time it takes to build a solution or start a debug session when you press F5. You should enable building the Web Deployment project only in solution configurations intended for deployment builds.
Using the Configuration Manager dialog box, you can create a new Staging configuration. You can also specify which projects should build when a specific solution configuration is built. For more information about the configuration manager, see Configuration Manager Dialog Box on the MSDN Web site.
The builds for Web site projects are optimized for developer productivity and do not run the ASP.NET 2.0 compiler to precompile the site. The build for the Web Deployment projects invoke the ASP.NET 2.0 compiler to precompile the site and take advantage of the new assembly merge utility (aspnet_merge.exe). When you create your solution configurations, you should build either the Web site project or the Web Deployment project, but not both. The following table presents a matrix suggesting the project build settings for different solution configurations.
|
Solution configuration |
|||
|
Build strategy |
Debug |
Staging |
Release |
|
Build Web site project |
True |
False |
False |
|
Build Web Deployment project |
False |
True |
True |
To specify the solution configuration to use when you build, select the configuration name from the Solution Configurations list on the toolbar:
Note Some Visual Studio Development Settings, such as the Web Development Settings and Visual Basic Development Settings, do not include the Solution Configurations command on the toolbar. To add the command, from the Tools menu, choose Customize. Click the Commands tab, select the Build category, and then from the commands list drag the Solution Configurations command to the toolbar.
Building a Web Deployment Project
When you have your build configurations established, you can initiate a build for any configuration. There are two ways to build a Web Deployment project ?from within Visual Studio 2005 or from the command line using MSBuild.
Building Within Visual Studio 2005
To build within Visual Studio 2005, in the toolbar, select Release from the Solution Configurations list in the toolbar. This makes Release the current solution configuration. Then from the Build menu, choose Build Solution.
The output for the build is displayed in the Output window. An example of the output from a build is shown in the following listing. Notice that in this example, the Web site project was skipped, and instead the Web Deployment project was built.
------ Skipped Build: Project: c:\...\MyWeb\, Configuration: Debug .NET ------
Project not selected to build for this solution configuration
------ Build started: Project: MyWeb_deploy, Configuration: Release Any CPU ------
Build started 11/7/2005 9:40:09 AM.
Target AspNetCompiler:
