Exercise 2: Transforming a Web.Config File for Deployment
Generally, a web application goes through a chain of environments before it makes it into a Production environment. Some of these environments are Development (the developer’s local machine), Quality Assurance (QA), and User Acceptance Testing (UAT) / Staging / Pre-Production. As applications transition through these environments, various settings in the configuration files must change. In addition to database connection strings, many Enterprise scale applications also rely on configuration settings for logging destinations, file drop shares and addresses for service endpoints.
Visual Studio 2010 adds a new Web.config transformation model that you can use to automate changes to the Web.config file during the deployment of the application when you use MSDeploy to promote your code.
To complete the tasks in this exercise, you must have completed all the tasks in Exercise 1, or use the solution from the %TrainingKitInstallFolder%\Labs\WebDevelopment\Source\Ex02-TransformingWebConfig\begin\C#\HTMLLab folder.
Task 1 – Creating a Staging Configuration in Visual Studio 2010
- Open the HTMLLab Web Application completed at the end of the previous exercise.
Select Build | Configuration Manager from the menu. The Configuration Manager dialog appears:
Select <New…> from the Active solution configuration dropdown list to bring up the New Solution Configuration dialog.
New Solution Configuration
In the Name field type “Staging” and from the Copy setting from dropdown list select Release. Leave the Create new project configurations checkbox checked. Your dialog should look similar to the figure below:
New Solution Configuration for the new Staging configuration
- Click the OK button. Click the Close button to close the Configuration Manager.
In the Solution Explorer, notice that there is an expandable node next to the Web.config file. Click the node to expand the tree view. Notice that there are two files under Web.config that follow a Web.<configuration>.config naming convention.
Debug and Release configuration files
The changes between the environments are stored in these delta files. By default, all web applications start with a Debug and Release configuration file. Visual Studio can add a new transformation for new configurations that developers create.
Add a new Web.config transformation. To do this, right-click on the Web.config file and from the menu select Add Config Transforms. Notice that new Staging configuration file is automatically added:
Staging configuration added
If from the right-click menu the Add Config Transforms is disabled, do a full rebuild of the application.
Task 2 – Adding Code to Populate Text Value of EnvName from a Value in the Web.config
Before we start this task, you will need to add a label to the Default.aspx page to contain an environment variable. Here’s what the label should look like when you are done.
Current Environment: <asp:Label ID="EnvName" Text="Environment Name" runat="server" />
Label in Default.aspx
In this task, you will add functionality to take the environment name from the Web.config file and populate the text attribute of the label.
- In the HTMLLab Web Application, open the Web.config file.
Add the <appSettings > XML element with the following value:
FakePre-c25cd6bfd9b5442787bc0f44645011ca-873cb4f2d48d49fc9948b0deed406d7bFakePre-1a4d05e613f54f638556b6f91299d224-4aaacb970ba54b9fba8eb83aa822ce7d <appSettings> <add key="EnvironmentName" value="Development" /> </appSettings>FakePre-c2d43b2132a04cdea3e4a3ccbdbe41de-0e4174082b284efe908211bcc7304e52FakePre-d35e7959e83d45a48cd606ada5b6d6ab-53cce44f31ab4f8abcea0dc878d6ae1fFakePre-7febdb75dfda4ff1966984972661dd18-a8ae415d486a464aa7884ef85d3182fb
- In the Solution Explorer, right-click Default.aspx and select View Code from the menu.
Locate the Page_Load method. Add the following code to get the value for key EnvironmentName and assign it to the Text property of the EnvName Label:
protected void Page_Load(object sender, EventArgs e)
FakePre-d3cd17d3c819497a8c0903ba459fe352-9b487f5f1a3f438cb19339266dd62021FakePre-f06b1f75778b4753945f69be7f111923-86ac5b4442854ae5a9f169aa7f261109FakePre-a2c36dceca6441d6a8fa5a73feeb10fc-3fd287c1678b4109b8f9860be1c8a689 EnvName.Text = ConfigurationManager.AppSettings["EnvironmentName"];FakePre-e06c1f5177b24113a5fc1e5fe6767cdf-7c3ed9980de54e9f9d168e09634adbe4
Run the application and verify that the word Development appears as the text in the EnvName Label.
Staging configuration added
- Close the web browser.
Task 3 – Adding a Logging Database Connection String to the Web.config File
In this task, you will add a connection string to logging application messages to the database.
- In the HTMLLab Web Application, open the Web.config file.
Add the connectionStrings XML element with the following value added:
FakePre-03123f83d1eb479eb5a4b445bbd70a4d-29ab801a910d4f7c943e4436186a30e3FakePre-a0d5328739fe4425911b2f270144219c-e881ef29896846689557243a296e2a31FakePre-2003075f2ce346208be9d247b2f082cf-35f5d7e7fee84ca6b39af02c8e3e4240 <connectionStrings> <add name="LoggingConnectionString" connectionString="server=(local);database=Logger;Integrated Security=SSPI;" providerName="System.Data.SqlClient"/> </connectionStrings>FakePre-4a8cf9104d6d45dba9236c7fe4717252-22eb9bba9656488e8d248169e4e0fde6FakePre-8bf212379877492594277c97892b9002-1cf937ae27cd482bbb03a4efbc6ae6dbFakePre-54662da728b641d0b97fbcdb89b080bc-4223d846d0bc416195337703c1fe03d6
- Save Web.config file changes.
Task 4 – Writing a Transform to Change the Environment and Logging Connection Strings in the Staging Web.config
In this task, you will create a transformation to update Web.config sections when the application is deployed with MSDeploy. In the Web.config file you will update the value of the Environment to “Staging” and change the server name value in the connection string to reflect QA server.
- To display the configuration specific transformation files, expand the Web.config node and open the Web.Staging.config file.
The transform file is an XML file that you use to specify the actions (add, delete, update) which Visual Studio should perform on nodes, sections, and attributes. The file contains a reference to the XML Document Transform namespace (http://schemas.microsoft.com/XML-Document-Transform). There are two attributes in this schema: Transform and Locator. Transform will make changes to nodes and attributes, while the Locator provides methods to find the specific transformation node and attributes in the Web.config.
Check MSDN for the complete reference for the Transform and Locator attributes.
The Staging configuration transform file will already have a node indicating changes to the system.web section of the Web.config file, specifically removing the debug attribute.
<?xml version="1.0"?> <configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transfrom"> ... <system.web> <compilation xdt:Transform="RemoveAttributes(debug)" /> </system.web> </configuration>
Below the system.web node, add the following code.
<appSettings> <add key="EnvironmentName" value="Staging" xdt:Transform="SetAttributes(value)" xdt:Locator="Match(key)" /> </appSettings>
When deployed, the transform above will instruct MSBuild process to locate the EnvironmentName node in the appSettings XML node and replace the value attribute with the one defined here: “Staging.”
Transform connectionString XML in a similar matter by adding the following code:
<connectionStrings> <add name="LoggingConnectionString" connectionString="Server=QADatabaseServer;Database=Logging;Integrated Security=SSPI" providerName="System.Data.SqlClient” xdt:Transform="Replace" xdt:Locator="Match(name)" /> </connectionStrings>
In this code, connectionString is transformed from using (local) server to the QADatabaseServer for logging.
xdt:Transform=”Replace” replaces the first matched node.
xdt:Transform=”SetAttribute(attributeName)” creates or changes values of the existing attributes.
Task 5 – Generating a Transformed Web.config File from the Command Line
In this task, you will use the MSBuild command line tool to create a build and transform the Web.config file based on the Staging configuration as part of the build process.
- Navigate to Start | All Programs | Microsoft Visual Studio 2010 | Visual Studio Tools. To open the Visual Studio Command Prompt, click on Visual Studio Command Prompt (2010).
Change directory to the HTMLLab project directory. For example, if you are still using the begin solution for Exercise 1, type:
At the command prompt, invoke MSBuild by typing the following command and hitting ENTER:
MSBuild HTMLLab.csproj /t:TransformWebConfig /p:Configuration=Staging
MSBuild builds the application and transforms the Web.config file according to the Staging transform rules. The output files placed in the HTMLLab\obj\Staging\TransformWebConfig\transformed folder.
In Visual Studio, select the File | Open | File menu command and navigate to the project directory and then to obj\Staging\TransformWebConfig\transformed folder. Select the Web.config file and click Open.
Notice that in the Web.config file the value for key EnvironmentName has changed to Staging and the connection string has been updated from (local) to QADatabaseServer.
<appSettings> <add key="EnvironmentName" value="Staging" /> </appSettings> <connectionStrings> <add name="LoggingConnectionString" connectionString="Server=QADatabaseServer;Database=Logger;Integrated Security=SSPI;" providerName="System.Data.SqlClient"/> </connectionStrings>
- Close the Web.config file.
Task 6 – Generating a Transformed Web.config File from Visual Studio
In this task, you will use Visual Studio to create a build to transform the Web.config file as part of that build.
- In the Solution Explorer, right-click the HTMLLab project and select Properties.
- On the project properties page, click the Package/Publish Web tab.
At the top of the properties page, make sure that the active configuration is set to Staging:
Verify that the Staging configuration selected.
At the bottom of the properties page, uncheck the Create deployment package as a zip file checkbox.
Uncheck the deploy as a ZIP file box
If Create deployment package as a zip file checkbox is left checked, the same build will occur but in addition, Visual Studio will create a ZIP file.
Note the package location.
This is the directory where Visual Studio will create the package that contains the deployable image for the Web application, including the modified Web.config file.
- Save all the changes by pressing CTRL+SHIFT+S.
- Using Windows Explorer, navigate to the HTMLLab\obj\Staging\TransformWebConfig\transformed folder. Delete the Web.config file located there, if exists.
In Visual Studio, select the Project menu and click Build Deployment Package. Visual Studio will re-build and create a deployment package for the web application.
Build Deployment Package
Exercise 2: Verification