documentation.help

XmlMassUpdate Class

From MSBuild

previous page next page

Performs multiple updates on an XML file


Namespace: MSBuild.Community.Tasks.Xml
Assembly: MSBuild.Community.Tasks (in MSBuild.Community.Tasks.dll)

Syntax

Visual Basic (Declaration)
Public Class XmlMassUpdate
    Inherits Task
C#
public class XmlMassUpdate : Task
C++
ref class XmlMassUpdate : Task
J#
public class XmlMassUpdate extends Task
JScript
public class XmlMassUpdate extends Task

Example

These examples will demonstrate how to make multiple updates to a XML file named web.config. It looks like:

 Copy Code 
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <appSettings>
        <add key="ItemsPerPage" value="10" />
        <add key="EnableCaching" value="true" />
        <add key="DefaultServer" value="TIGRIS" />
    </appSettings>
    <system.web>
        <compilation defaultLanguage="c#" debug="true" />
        <customErrors mode="Off" />
        <trace enabled="true" requestLimit="10" pageOutput="true" />
        <globalization requestEncoding="utf-8" responseEncoding="utf-8" />
    </system.web>
</configuration>
You can update the file using instructions from an external file (specified as the SubstitutionsFile):
 Copy Code 
<XmlMassUpdate ContentFile="web.config" SubstitutionsFile="changes.xml" ContentRoot="/configuration/system.web" SubstitutionsRoot="/system.web" />
The SubstitutionsFile is named changes.xml and contains:
 Copy Code 
<system.web>
        <compilation debug="false" />
        <customErrors mode="RemoteOnly" defaultRedirect="Error.htm">
          <error statusCode="401" redirect="AccessDenied.aspx" />
        </customErrors>
        <trace enabled="false" />
      </system.web>
You can also provide the update instructions within the MSBuild project file itself. It takes advantage of the MSBuild ProjectExtensions element which allows you to add XML to a project file that will be ignored by the MSBuild engine. This example also demonstrates how to use NamespaceDefinitions:
 Copy Code 
<ProjectExtensions>
  <system.web>
    <compilation debug="false" />
    <trace enabled="false" />
  </system.web>
</ProjectExtensions>
<Target Name="SubstituteFromProj">
  <XmlMassUpdate ContentFile="web.config" ContentRoot="/configuration/system.web"
    NamespaceDefinitions="msb=http://schemas.microsoft.com/developer/msbuild/2003"
    SubstitutionsFile="$(MSBuildProjectFullPath)"
    SubstitutionsRoot="/msb:Project/msb:ProjectExtensions/msb:system.web" />
</Target>
The following example demonstrates how to deal with "keyed" elements. When you need to update an element, and multiple elements exist with the same name, it must be be differentied by one of its attributes. You designate the differentiating attribute using the "key" attribute declared in the UpdateControlNamespace. If an element matching the keyed attribute is not found, a new element will be created (DefaultSort in the example). This example also demonstrates creating a new file with the merged changes instead of modifying the original file.
 Copy Code 
 <XmlMassUpdate ContentFile="web.config" SubstitutionsFile="changes.xml" MergedFile="web.config.keyed.xml"  />
Using a changes.xml file with the following contents:
 Copy Code 
<configuration xmlns:xmu="urn:msbuildcommunitytasks-xmlmassupdate">
  <appSettings>
        <add xmu:key="key" key="EnableCaching" value="false" />
        <add xmu:key="key" key="DefaultSort" value="LastName" />
  </appSettings>
</configuration>
Use a changes.xml file with the following contents to demonstrate how to remove an element from the updated file:
 Copy Code 
<configuration xmlns:xmu="urn:msbuildcommunitytasks-xmlmassupdate">
  <appSettings>
        <add xmu:key="key" key="ItemsPerPage" xmu:action="remove" />
        <trace xmu:action="remove" />
  </appSettings>
</configuration>
You can also specify the changes to apply from within the target document. By making use of the SubstitutionsRoot property, you can store multiple sets of changes to apply based on runtime conditions. Consider the following source web.config file:
 Copy Code 
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <system.web>
        <compilation defaultLanguage="c#" debug="true" />
        <customErrors mode="Off" />
        <trace enabled="true" requestLimit="10" pageOutput="true" />
        <globalization requestEncoding="utf-8" responseEncoding="utf-8" />
    </system.web>
    <substitutions>
      <test>
        <system.web>
          <compilation debug="false" />
          <trace enabled="true" />
        </system.web>
      </test>
      <prod>
        <system.web>
          <compilation debug="false" />
          <trace enabled="false" />
        </system.web>
      </prod>
    </substitutions>
</configuration>
You could use the following task definition, which relies on a property "TargetEnvironment" to determine which set of changes to apply:
 Copy Code 
 <XmlMassUpdate ContentFile="web.config" ContentRoot="/configuration" SubstitutionsRoot="/configuration/substitutions/$(TargetEnvironment)" />
You will need to provide a value of "test" or "prod" to the TargetEnvironment property. The property can be defined in a PropertyGroup section of the MSBuild file, or passed as a command-line parameter.
 Copy Code 
 msbuild build.proj /p:TargetEnvironment=prod

Remarks

XmlMassUpdate allows to to specify multiple changes to make to an XML file (the ContentFile. By default, the changes are applied to the ContentFile, but you can create a new file by providing the MergedFile attribute. The change instructions are specified using XML in the SubstitutionsFile. If the SubstitutionsFile does not mirror the structure of the ContentFile exactly, you can specify the ContentRoot and SubstitutionsRoot XPath expressions which determine how the files should be mapped to each other.

Any element within the SubstitutionsRoot will find the corresponding element in the ContentRoot. If it does not exist, it will be created with all of its attributes. If it does exist, the attributes will be added or updated as specified.

Any attribute declared within the UpdateControlNamespace will not be copied to the modified file. Valid attributes are key and action. The key attribute allows you to define an attribute to use as the identifying attribute when you only want to update a single element, and multiple elements with the same name exist. You can also use the action="remove" attribute to specify that an element should be deleted instead of updated.

Inheritance Hierarchy

System.Object
   Microsoft.Build.Utilities.Task
      MSBuild.Community.Tasks.Xml.XmlMassUpdate

Thread Safety

Public static (Shared in Visual Basic)staticShared members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.

See Also

Syntax based on .NET Framework version 2.0.
Documentation version 1.0.0.0.

previous page start next page