Managing Document Properties

Possible Usage Scenario

Aspose.Cells allows you to work with built-in and custom document properties. Here is the Microsoft Excel interface for opening these document properties. Just click on Advanced Properties as shown in this screenshot to view them.

Managing Document Properties

The following sample code loads the sample Excel file and reads the built-in document properties, e.g., Title and Subject, and then changes them. It also reads the custom document property, i.e., MyCustom1, and then adds a new custom document property, i.e., MyCustom5, and writes the output Excel file. The following screenshot shows the effect of the sample code on the sample Excel file.

Sample Code

Console Output

This is the console output of the above sample code when executed with the provided sample Excel file.

Title: Aspose Team

Subject: Aspose.Cells for C++

MyCustom1: This is my custom one.

How to Access 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.

• To access built-in document properties, use WorksheetCollection::GetBuiltInDocumentProperties().
• To access custom document properties, use WorksheetCollection::GetCustomDocumentProperties().

Both the WorksheetCollection::GetBuiltInDocumentProperties() and WorksheetCollection::GetCustomDocumentProperties() return an 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 you to retrieve the name, value, and type of the document property:

• To get the property name, use DocumentProperty::GetName().
• To get the property value, use DocumentProperty::GetValue(). DocumentProperty::GetValue() returns the value as an object.
• To get the property type, use DocumentProperty::GetType(). This returns one of the PropertyType enumeration values. After you get the property type, use one of the DocumentProperty.ToXXX methods to obtain the value of the appropriate type instead of using DocumentProperty::GetValue(). The DocumentProperty.ToXXX methods are described in the table below.

The DocumentProperty class also provides a set of methods that return the values of other data types.

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	ToDateTime
Float	The property data type is Double	ToDouble
Number	The property data type is Int32	ToInt
String	The property data type is String	ToString

How to Add or Remove Custom Document Properties

As we described earlier, developers can’t add or remove built-in properties because these properties are system-defined, but it is possible to add or remove custom properties because these are user‑defined.

How to Add Custom Properties

Aspose.Cells APIs expose 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.

How to Configure “Link to content” Custom Property

To create a custom property linked to the content of a given range, call the CustomDocumentPropertyCollection::AddLinkToContent method and pass the 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 DocumentProperty::GetSource() 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.

How to Remove 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.