Custom XML Parts in Word Documents

May 07, 2025
4 minutes to read

You can embed arbitrary XML data (called custom XML parts) in documents in DOCX and DOC format. Custom XML parts are included in the document structure but are not visible in the document. Use the Document.CustomXmlParts property to obtain the collection of custom XML parts in code. You can create, modify or remove custom XML parts, obtain their content and display it in a document.

Add a Custom XML Part

Method	Description
CustomXmlPartCollection.Add	Appends a new custom XML part to the collection.
CustomXmlPartCollection.Insert	Inserts a new custom XML part at the specified position in the collection.

The code snippet inserts three custom XML parts into a document:

View Example

C#
VB.NET

csharp

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
using System.Xml;
// ...

using (RichEditDocumentServer wordProcessor = new RichEditDocumentServer())
{
    Document document = wordProcessor.Document;
    document.AppendText("This document contains custom XML parts.");
    // Add an empty custom XML part.
    ICustomXmlPart xmlItem = document.CustomXmlParts.Add();
    // Populate the XML part with content.
    XmlElement elem = xmlItem.CustomXmlPartDocument.CreateElement("Employees");
    elem.InnerText = "Stephen Edwards";
    xmlItem.CustomXmlPartDocument.AppendChild(elem);

    // Use a string to specify the content for a custom XML part.
    string xmlString = @"<?xml version=""1.0"" encoding=""UTF-8""?>
                            <Employees>
                                <FirstName>Stephen</FirstName>
                                <LastName>Edwards</LastName>
                                <Address>4726 - 11th Ave. N.E.</Address>
                                <City>Seattle</City>
                                <Region>WA</Region>
                                <PostalCode>98122</PostalCode>
                                <Country>USA</Country>
                            </Employees>";
    document.CustomXmlParts.Insert(1, xmlString);

    // Add a custom XML part from a file.
    XmlDocument xmlDoc = new XmlDocument();
    xmlDoc.Load("Documents\\Employees.xml");
    document.CustomXmlParts.Add(xmlDoc);
    document.SaveDocument("Documents\\CustomXmlTestDoc.docx", DocumentFormat.Docx);
}

Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native
Imports System.Xml
' ...

Using wordProcessor As New RichEditDocumentServer()
    Dim document As Document = wordProcessor.Document
    document.AppendText("This document contains custom XML parts.")
    ' Add an empty custom XML part.
    Dim xmlItem As ICustomXmlPart = document.CustomXmlParts.Add()
    ' Populate the XML part with content.
    Dim elem As XmlElement = xmlItem.CustomXmlPartDocument.CreateElement("Employees")
    elem.InnerText = "Stephen Edwards"
    xmlItem.CustomXmlPartDocument.AppendChild(elem)

    ' Use a string to specify the content for a custom XML part.
    Dim xmlString As String = "<?xml version=""1.0"" encoding=""UTF-8""?>
                                <Employees>
                                    <FirstName>Stephen</FirstName>
                                    <LastName>Edwards</LastName>
                                    <Address>4726 - 11th Ave. N.E.</Address>
                                    <City>Seattle</City>
                                    <Region>WA</Region>
                                    <PostalCode>98122</PostalCode>
                                    <Country>USA</Country>
                                </Employees>"
    document.CustomXmlParts.Insert(1, xmlString)

    ' Add a custom XML part from a file.
    Dim xmlDoc As New XmlDocument()
    xmlDoc.Load("Documents\Employees.xml")
    document.CustomXmlParts.Add(xmlDoc)
    document.SaveDocument("Documents\CustomXmlTestDoc.docx", DocumentFormat.Docx)
End Using

Read Custom XML Parts

The collection’s Item property uses a custom XML part’s index to obtain the corresponding item (the ICustomXmlPart object) from the collection. Use the CustomXmlPartDocument property to retrieve an XML document associated with the custom XML part obtained from the collection.

The following code snippet retrieves employee names from a custom XML part and displays them in the main document.

C#
VB.NET

csharp

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;
using System.Xml;
// ...

using (RichEditDocumentServer wordProcessor = new RichEditDocumentServer())
{
    Document document = wordProcessor.Document;
    // Load a document.
    document.LoadDocument("Documents\\CustomXmlParts.docx");
    // Access a custom XML file stored in the document.
    XmlDocument xmlDoc = document.CustomXmlParts[0].CustomXmlPartDocument;
    // Retrieve employee names from the XML file and display them in the document.
    XmlNodeList nameList = xmlDoc.GetElementsByTagName("Name");
    document.AppendText("Employee list:");
    foreach (XmlNode name in nameList)
    {
        document.AppendText("\r\n \u00B7 " + name.InnerText);
    }
}

Imports DevExpress.XtraRichEdit
Imports DevExpress.XtraRichEdit.API.Native
Imports System.Xml
' ...

Using wordProcessor As New RichEditDocumentServer()
    Dim document As Document = wordProcessor.Document
    ' Load a document.
    document.LoadDocument("Documents\CustomXmlParts.docx")
    ' Access a custom XML file stored in the document.
    Dim xmlDoc As XmlDocument = document.CustomXmlParts(0).CustomXmlPartDocument
    ' Retrieve employee names from the XML file and display them in the document.
    Dim nameList As XmlNodeList = xmlDoc.GetElementsByTagName("Name")
    document.AppendText("Employee list:")
    For Each name As XmlNode In nameList
        document.AppendText(ControlChars.CrLf & " " & ChrW(&H00B7).ToString() & " " & name.InnerText)
    Next name
End Using

Remove a Custom XML Part

Method	Description
CustomXmlPartCollection.Remove	Removes a specific custom XML part from the collection.
CustomXmlPartCollection.RemoveAt	Removes a custom XML part at the specified index from the collection.
CustomXmlPartCollection.Clear	Clears the entire collection.

C#
VB.NET

csharp

using (RichEditDocumentServer wordProcessor = new RichEditDocumentServer())
{
    Document document = wordProcessor.Document;
    document.AppendText("This document contains custom XML parts.");

    // Add the first custom XML part.
    string xmlString1 = @"<?xml version=""1.0"" encoding=""UTF-8""?>
                            <Employees>
                                <FirstName>Stephen</FirstName>
                                <LastName>Edwards</LastName>
                            </Employees>";
    var xmlItem1 = document.CustomXmlParts.Add(xmlString1);

    // Add the second custom XML part.
    string xmlString2 = @"<?xml version=""1.0"" encoding=""UTF-8""?>
                            <Employees>
                                <FirstName>Andrew</FirstName>
                                <LastName>Fuller</LastName>
                            </Employees>";
    var xmlItem2 = document.CustomXmlParts.Add(xmlString2);

    // Remove the first item from the collection.
    document.CustomXmlParts.Remove(xmlItem1);
    // Use the RemoveAt method to remove an item at the specified position from the collection.
    // document.CustomXmlParts.RemoveAt(0);
    // Use the Clear method to remove all items from the collection.
    // document.CustomXmlParts.Clear();
}

Using wordProcessor As New RichEditDocumentServer()
    Dim document As Document = wordProcessor.Document
    document.AppendText("This document contains custom XML parts.")

    ' Add the first custom XML part.
    Dim xmlString1 As String = "<?xml version=""1.0"" encoding=""UTF-8""?>
                            <Employees>
                                <FirstName>Stephen</FirstName>
                                <LastName>Edwards</LastName>
                            </Employees>"
    Dim xmlItem1 = document.CustomXmlParts.Add(xmlString1)

    ' Add the second custom XML part.
    Dim xmlString2 As String = "<?xml version=""1.0"" encoding=""UTF-8""?>
                            <Employees>
                                <FirstName>Andrew</FirstName>
                                <LastName>Fuller</LastName>
                            </Employees>"
    Dim xmlItem2 = document.CustomXmlParts.Add(xmlString2)

    ' Remove the first item from the collection.
    document.CustomXmlParts.Remove(xmlItem1)
    ' Use the RemoveAt method to remove an item at the specified position from the collection.
    ' document.CustomXmlParts.RemoveAt(0)
    ' Use the Clear method to remove all items from the collection.
    ' document.CustomXmlParts.Clear()
End Using