Custom XML Support in Syncfusion® Excel Library

24 Jul 20265 minutes to read

A custom XML part is arbitrary XML data embedded in the workbook.

Essential® XlsIO supports the following Custom XML features:

  • Adding CustomXmlPart to workbook
  • Reading CustomXmlPart from workbook

Add Custom XML

A Custom XML part is added by using the Add method of the ICustomXmlPartCollection interface.

The following code snippet illustrates how to add a Custom XML part.

using (ExcelEngine excelEngine = new ExcelEngine())
{
	IApplication application = excelEngine.Excel;
	application.DefaultVersion = ExcelVersion.Xlsx;
	IWorkbook workbook = application.Workbooks.Create(1);
	IWorksheet worksheet = workbook.Worksheets[0];

	//Adding CustomXmlData to Workbook
	ICustomXmlPart customXmlPart = workbook.CustomXmlparts.Add("SD10003"); 

	//Add XmlData to CustomXmlPart
	byte[] xmlData = File.ReadAllBytes(Path.GetFullPath(@"Data/InputTemplate.xml"));
	customXmlPart.Data = xmlData;

	#region Save
	//Saving the workbook
	workbook.SaveAs(Path.GetFullPath("Output/CreateCustomXML.xlsx"));
	#endregion
}
using (ExcelEngine excelEngine = new ExcelEngine())
{
  IApplication application = excelEngine.Excel;
  application.DefaultVersion = ExcelVersion.Excel2013;
  IWorkbook workbook = application.Workbooks.Create(1);
  IWorksheet worksheet = workbook.Worksheets[0];

  //Adding CustomXmlData to Workbook
  ICustomXmlPart customXmlPart = workbook.CustomXmlparts.Add("SD10003");

  //Add XmlData to CustomXmlPart
  byte[] xmlData = File.ReadAllBytes(Path.GetFullPath("Test.xml"));
  customXmlPart.Data = xmlData;

  workbook.SaveAs("CustomXml.xlsx");
}
Using excelEngine As ExcelEngine = New ExcelEngine()
  Dim application As IApplication = excelEngine.Excel
  application.DefaultVersion = ExcelVersion.Excel2013
  Dim workbook As IWorkbook = application.Workbooks.Create(1)
  Dim worksheet As IWorksheet = workbook.Worksheets(0)

  'Adding CustomXmlData to Workbook
  Dim customXmlPart As ICustomXmlPart = workbook.CustomXmlparts.Add("SD10003")

  'Add XmlData to CustomXmlPart
  Dim xmlData() As Byte = File.ReadAllBytes(Path.GetFullPath("Test.xml"))
  customXmlPart.Data = xmlData

  workbook.SaveAs("CustomXml.xlsx")
End Using

A complete working example to add custom XML in C# is available on this GitHub page.

Read Custom XML

A Custom XML part is read by using the GetById method of the ICustomXmlPartCollection interface. The following code snippet illustrates how to read Custom XML parts from the workbook.

using (ExcelEngine excelEngine = new ExcelEngine())
{
	IApplication application = excelEngine.Excel;
	application.DefaultVersion = ExcelVersion.Xlsx;
	IWorkbook workbook = application.Workbooks.Open(Path.GetFullPath(@"Data/InputTemplate.xlsx"), ExcelOpenType.Automatic);
	IWorksheet sheet = workbook.Worksheets[0];

	//Access CustomXmlPart from Workbook
	ICustomXmlPart customXmlPart = workbook.CustomXmlparts.GetById("SD10003");

	//Access XmlData from CustomXmlPart
	byte[] xmlData = customXmlPart.Data;

	System.Text.Encoding.Default.GetString(xmlData);

	#region Save
	//Saving the workbook
	workbook.SaveAs(Path.GetFullPath("Output/ReadXml.xlsx"));
	#endregion
}
using (ExcelEngine excelEngine = new ExcelEngine())
{
  IApplication application = excelEngine.Excel;
  application.DefaultVersion = ExcelVersion.Excel2013;
  IWorkbook workbook = application.Workbooks.Open("CustomXml.xlsx");
  IWorksheet worksheet = workbook.Worksheets[0];

  //Access CustomXmlPart from Workbook
  ICustomXmlPart customXmlPart = workbook.CustomXmlparts.GetById("SD10003");

  //Access XmlData from CustomXmlPart
  byte[] xmlData = customXmlPart.Data;
  System.Text.Encoding.Default.GetString(xmlData);

  workbook.SaveAs("CustomXml.xlsx");
}
Using excelEngine As ExcelEngine = New ExcelEngine()
  Dim application As IApplication = excelEngine.Excel
  application.DefaultVersion = ExcelVersion.Excel2013
  Dim workbook As IWorkbook = application.Workbooks.Open("CustomXml.xlsx")
  Dim worksheet As IWorksheet = workbook.Worksheets(0)

  'Access CustomXmlPart from Workbook
  Dim customXmlPart As ICustomXmlPart = workbook.CustomXmlparts.GetById("SD10003")

  'Access XmlData from CustomXmlPart
  Dim xmlData As Byte() = customXmlPart.Data
  System.Text.Encoding.Default.GetString(xmlData)

  workbook.SaveAs("CustomXml.xlsx")
End Using

A complete working example to read custom XML in C# is available on this GitHub page.

Supported File Formats

NOTE

Custom XML is not supported in the Excel 97-2003 (*.xls) format.
Custom XML is supported in Excel 2007 and later versions (*.xlsx, *.xlsm, *.xltx).