Managing Document Properties


Microsoft Excel provides the ability to add properties to spreadsheet files. These document properties provide useful information and are divided into 2 categories as detailed below.

  • System-defined (built-in) properties: Built-in properties contain general information about the document like document title, author name, document statistics and so on.
  • User-defined (custom) properties: Custom properties defined by the end user in the form of name-value pair.

Managing Document Properties Using Microsoft Excel

Microsoft Excel allows you to manage the document properties of the Excel files in a WYSIWYG manner. Please follow the below steps to open the Properties dialog in Excel 2016.

  1. From the File menu, select Info.
Selecting Info Menu
  1. Click on Properties heading and select “Advanced Properties”.
Clicking Advanced Properties Selection
  1. Manage the file’s document properties.
Properties Dialog
In the Properties dialog, there are different tabs, like General, Summary, Statistics, Contents, and Customs. Each tab helps configure different kinds of information related to the file. The Custom tab is used to manage custom properties.

Working with Document Properties Using Aspose.Cells

Developers can dynamically manage the document properties using the Aspose.Cells APIs. This feature helps the developers to store useful information along with the file, such as when the file was received, processed, time-stamped and so on.

Accessing Document Properties

Aspose.Cells APIs support both types of document properties, built-in and custom. Aspose.Cells’ Workbook class represents an Excel file and, like an Excel file, the Workbook class can contain multiple worksheets, each represented by the Worksheet class whereas the collection of worksheets is represented by the WorksheetCollection class.

Use the WorksheetCollection to access the file’s document properties as described below.

Both the WorksheetCollection.BuiltInDocumentProperties and WorksheetCollection.CustomDocumentProperties return the instance of Aspose.Cells.Properties.DocumentPropertyCollection. This collection contains Aspose.Cells.Properties.DocumentProperty objects, each of which represents a single built-in or custom document property.

It is up to the application requirement how to access a property, that is; by using the index or name of the property from the DocumentPropertyCollection as demonstrated in the example below.

The Aspose.Cells.Properties.DocumentProperty class allows to retrieve the name, value, and type of the document property:

Member Name Description ToXXX Method
Boolean The property data type is Boolean ToBool
Date The property data type is DateTime. Note that Microsoft Excel stores only
the date portion, no time can be stored in a custom property of this type
Float The property data type is Double ToDouble
Number The property data type is Int32 ToInt
String The property data type is String ToString

Adding or Removing Custom Document Properties

As we have described earlier at the beginning of this topic, developers can’t add or remove built-in properties because these properties are system-defined but it’s possible to add or remove custom properties because these are user-defined.

Adding Custom Properties

Aspose.Cells APIs have exposed the Add method for the CustomDocumentPropertyCollection class in order to add custom properties to the collection. The Add method adds the property to the Excel file and returns a reference for the new document property as an Aspose.Cells.Properties.DocumentProperty object.

To create a custom property linked to the content of a given range, call the CustomDocumentPropertyCollection.AddLinkToContent method and pass property name and source. You can check whether a property is configured as linked to content using the DocumentProperty.IsLinkedToContent property. Moreover, it is also possible to get the source range using the Source property of the DocumentProperty class.

We use a simple template Microsoft Excel file in the example. The workbook has a defined named range labeled MyRange which refers to a cell value.

Removing Custom Properties

To remove custom properties using Aspose.Cells, call the DocumentPropertyCollection.Remove method and pass the name of the document property to be removed.