Working with Document Properties

Working with Document Properties

This guide shows how to read and manage a Word document’s metadata — the properties visible in Word’s Info/Properties panel, plus any application-defined custom values. Document.BuiltInDocumentProperties and Document.CustomDocumentProperties expose these two categories, both ultimately built on the same underlying DocumentProperty representation.

Built-in Document Properties

Document.BuiltInDocumentProperties returns a BuiltInDocumentProperties collection covering the standard metadata Word tracks for every document: descriptive fields such as Title, Subject, Author, Manager, Company, Category, Keywords, and Comments; timestamps such as CreatedTime, LastSavedTime, and LastPrinted, along with LastSavedBy and RevisionNumber; and statistics such as Words, Characters, CharactersWithSpaces, Lines, Paragraphs, and Pages. Security reports the document’s protection state as a DocumentSecurity value, and Template, NameOfApplication, and TotalEditingTime describe the authoring environment. Because BuiltInDocumentProperties is a fixed, known set of properties, individual values are read and written as ordinary properties (BuiltInDocumentProperties.Author = "...") rather than looked up by name.

Custom Document Properties

Document.CustomDocumentProperties returns a CustomDocumentProperties collection for application-defined metadata that isn’t part of Word’s built-in set. Several Add(name, value) overloads create a new property from a name and a typed value (string, number, boolean, or date, depending on overload), and AddLinkToContent(name, linkSource) creates a property whose value is linked to and tracks a bookmarked range of content in the document rather than holding a static value. Indexing by name (e.g. properties[name]) and Contains(name) look a property up, IndexOf(name) returns its position, and Remove(name)/RemoveAt(index) delete one.

The DocumentProperty Object and Shared Collection Base

Both BuiltInDocumentProperties and CustomDocumentProperties derive from the abstract DocumentPropertyCollection, which defines an indexer by name, GetEnumerator(), Contains(name), IndexOf(name), and Count — so the two collections are inspected the same way even though built-in properties are fixed and custom properties are open-ended. Individually, a DocumentProperty has a Name, an untyped Value, and a Type (a PropertyType enum value: Boolean, DateTime, Double, Number, String, StringArray, ObjectArray, ByteArray, or Other). IsLinkToContent and LinkSource report whether the property is linked to document content rather than holding a static value (see AddLinkToContent above). Because Value is untyped, DocumentProperty provides typed accessors — ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray(), and ToString() — to read it as a specific type without an explicit cast.

Document Security

BuiltInDocumentProperties.Security reports a DocumentSecurity value describing the document’s protection state: None, PasswordProtected, ReadOnlyRecommended, ReadOnlyEnforced, or ReadOnlyExceptAnnotations. This reflects the document’s stored protection metadata as read from the file’s properties.

Tips and Best Practices

• Use the typed accessors (ToInt(), ToDouble(), ToDateTime(), ToBool()) on DocumentProperty.Value rather than casting the untyped object value directly, since the underlying storage type can vary by PropertyType.
• Check Contains(name) before indexing into either property collection by name (e.g. properties[name]) when a property may not exist, to avoid handling a missing-property case as an exception path.
• Use CustomDocumentProperties.AddLinkToContent(name, linkSource) when a custom property’s value should always reflect a bookmarked part of the document, instead of manually re-syncing a static custom property whenever that content changes.
• Treat BuiltInDocumentProperties statistics (Words, Characters, Pages, and similar) as the values stored in the file’s metadata rather than always-live computed counts — refresh them explicitly if the document has changed since they were last written.
• Read BuiltInDocumentProperties.Security to check a document’s declared protection state before deciding whether further protection-related processing is needed.

Common Issues

FAQ

How do I read or set the document’s author and title?

Use Document.BuiltInDocumentProperties.Author and .Title directly — they’re ordinary string properties on the BuiltInDocumentProperties collection reached from Document.BuiltInDocumentProperties.

How do I add application-specific metadata that isn’t a standard Word property?

Use Document.CustomDocumentProperties.Add(name, value) with the property’s name and value; the appropriate Add overload is selected based on the value’s type.

What’s the difference between BuiltInDocumentProperties and CustomDocumentProperties?

BuiltInDocumentProperties is Word’s fixed set of standard metadata fields (author, title, statistics, and so on), accessed as named properties. CustomDocumentProperties is an open-ended, named collection of DocumentProperty values for application-defined metadata, accessed by name via the indexer (e.g. properties[name]) and Contains.

How do I read a custom property without knowing its exact stored type in advance?

Retrieve the DocumentProperty by indexing the collection (e.g. properties[name]), check its Type (a PropertyType value), and use the matching typed accessor such as ToInt(), ToDouble(), ToDateTime(), or ToBool() on its Value.

How do I make a custom property track a piece of document content?

Use CustomDocumentProperties.AddLinkToContent(name, linkSource), passing a bookmark name as linkSource; the property’s value then reflects that bookmarked content rather than a static value.

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation