Running Comparisons Between Documents, Fragments, or Nodes

The XmlDiff class can compare two document, two fragments, or two nodes that are stored in files. The XmlDiff class can also compare two XmlReader objects or two XmlNode objects.

For output, the tool returns a true/false answer; responding true when both inputs are the same, false if they are not the same. To enhance the true/false flag, the tool can also output an XDL Diffgram detailing what the differences are between the documents, fragments, or nodes.

There are two constructors for the XmlDiff class. One constructor initializes the class using the default option values. The other constructor enables you to customize the options applied when the documents are compared, using the XmlDiffOptions. The following code sample shows how to create the XmlDiff class with default options:

[Visual Basic]
Dim xmlDiff as New XmlDiff()
[C#]
XmlDiff xmlDiff = new XmlDiff();

To create the XmlDiff class with customized options, set the property value, then create the class with the options as parameters with an or keyword between each option:

[Visual Basic]
Dim xmlDiff As New XmlDiff(XmlDiffOptions.IgnoreComments Or XmlDiffOptions.IgnorePI)
[C#]
XmlDiff xmlDiff = new XmlDiff(XmlDiffOptions.IgnoreComments | XmlDiffOptions.IgnorePI);

For more information on the XmlDiffOptions, see Setting Options that Affect the Comparison.

There are several overloaded versions of the Compare method that allow you to compare documents of different input type.

The following illustration shows the comparison done with two files. The fragment flag, when true, indicates that the data is a fragment. The fragment flag has no default value, it must always be specified. If the overloaded Compare method that takes an XmlWriter as a last parameter is used, then it will additionally output an XDL Diffgram to the specified XmlWriter.

The following Compare methods are used to implement the preceding illustration:

[C#]
public bool Compare(string sourceFile, string changedFile, bool bFragments);
[Visual Basic]

Public Function Compare(sourceFile As String, changedFile As String, bFragments As Boolean) As Boolean

This method compares two XML documents or fragments stored in files, and returns true if they are identical; otherwise returns false. The following overloaded method is used to additionally output the XDL Diffgram.

[C#]
public bool Compare(string sourceFile, string changedFile, bool bFragments, XmlWriter diffgramWriter);
[Visual Basic]
Public Function Compare(sourceFile As String, changedFile As String, bFragments As Boolean, diffgramWriter As XmlWriter) As Boolean

The following illustration shows the comparison done with XmlReader objects as input. One of the overloaded Compare methods takes an XmlWriter as a last parameter. When this method is used, the Compare method additionally outputs an XDL Diffgram to the specified XmlWriter.

The following Compare methods are used to implement the preceding illustration:

[C#]
public bool Compare(XmlReader sourceReader, XmlReader changedReader);
[Visual Basic]
Public Function Compare(sourceReader As XmlReader, changedReader As XmlReader) As Boolean

This method compares two XML documents or fragments parsed by the XmlReader objects and returns true if they are identical; otherwise returns false. The following overloaded method is used to additionally output the XDL Diffgram.

[C#]
public bool Compare(XmlReader sourceReader, XmlReader changedReader, XmlWriter diffgramWriter);
[Visual Basic]
Public Function Compare(sourceReader As XmlReader, changedReader As XmlReader, diffgramWriter as XmlWriter) As Boolean

The following illustration shows the comparison done with XmlNode objects as input. One of the overloaded Compare methods takes an XmlWriter as a last parameter. When this method is used, the Compare method additionally outputs an XDL Diffgram to the specified XmlWriter.

These are the Compare methods used to implement the preceding illustration:

[C#]
public bool Compare(XmlNode sourceNode, XmlNode changedNode);
[Visual Basic]
Public Function Compare(sourceNode As XmlNode, changedNode As XmlNode) As Boolean

This method compares two XmlNode objects and returns true if they are identical; otherwise returns false. The types of nodes that can be passed into the Compare method are any combination of the following:

• XmlDocument
• XmlElement
• XmlText
• XmlCDataSection
• XmlEntityReference
• XmlComment
• XmlDocumentType
• XmlProcessingInstruction

The Compare method cannot be used to compare XmlAttribute, XmlEntity, or XmlNotation node types. The following Compare overloaded method is used to additionally output the XDL Diffgram.

[C#]
public bool Compare(XmlNode sourceNode, XmlNode changedNode, XmlWriter diffgramWriter);
[Visual Basic]
Public Function Compare(sourceNode As XmlNode, changedNode As XmlNode, diffgramWriter As XmlWriter) As Boolean

When using the Compare method, the results may differ when comparing documents loaded in an XmlDocument object, and documents passed in through files or as XmlReader objects, if the XML data contains entity references that get expanded by the XmlDocument. The Patch method in the XmlPatch class will reject a DOM document loaded into XmlDocument. That is, if it contains expanded entity references and if the XDL Diffgram supplied for patching has been generated by a Compare method that takes document files or XmlReaders as input parameters.

See Also

XML Diff Functionality | Selecting the Algorithm for the Comparison | Setting Options that Affect the Comparison | XML Diff Language (Diffgram) | Extended Operations | Example of a Diffgram | XmlDiff Class

© 2002 Microsoft Corporation. All rights reserved.