How to Work with Document Properties in .NET
How to Work with Document Properties in .NET
Every Word document carries two categories of metadata — the standard fields Word tracks for every file, and any application-defined values a program has added. This guide shows how to read and set both with Aspose.Words FOSS for .NET, using Document.BuiltInDocumentProperties and Document.CustomDocumentProperties, both of which are ultimately built on the same DocumentProperty representation.
Step-by-Step Guide
Step 1: Read and Set Built-in Document Properties
Document.BuiltInDocumentProperties returns a BuiltInDocumentProperties collection. Because it’s a fixed, known set of properties, values are read and written as ordinary members rather than looked up by name — for example BuiltInDocumentProperties.Author, .Title, .Subject, .Manager, .Company, .Category, .Keywords, and .Comments for descriptive fields, or .CreatedTime, .LastSavedTime, .LastPrinted, and .LastSavedBy for timestamps. Statistics such as .Characters, .CharactersWithSpaces, .Lines, and .Bytes are also exposed this way, alongside .Template and .HyperlinkBase.
Step 2: Add a Custom Document Property
Document.CustomDocumentProperties returns a CustomDocumentProperties collection for application-defined metadata that isn’t part of Word’s built-in set. Call one of the Add(name, value) overloads with a name and a typed value — string, number, boolean, or date, depending on which overload matches the value’s type — to create a new property.
Step 3: Link a Custom Property to Document Content
Instead of a static value, a custom property can track a bookmarked range of content so its value stays in sync with that content. Call CustomDocumentProperties.AddLinkToContent(name, linkSource), passing a bookmark name as linkSource, rather than manually re-syncing a static property whenever the linked content changes.
Step 4: Look Up, Check, and Remove Properties
Both BuiltInDocumentProperties and CustomDocumentProperties derive from the abstract DocumentPropertyCollection, so they’re inspected the same way: indexing by name (e.g. properties[name]) retrieves a property, Contains(name) checks whether it exists, IndexOf(name) returns its position, and Count reports how many properties the collection holds. Call Contains(name) before indexing by name when a custom property may not exist, to avoid handling a missing property as an exception path. Remove a property with Remove(name) or RemoveAt(index), or clear every property in the collection with Clear().
Step 5: Read a Custom Property’s Value Without Knowing Its Type in Advance
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. Because Value is untyped, use the matching typed accessor instead of casting directly: ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray(), or ToString(). Check IsLinkToContent and LinkSource to find out whether a property is linked to document content (see Step 3) rather than holding a static value.
Step 6: Check a Document’s Protection State
BuiltInDocumentProperties.Security reports a DocumentSecurity value describing the document’s stored protection metadata: None, PasswordProtected, ReadOnlyRecommended, ReadOnlyEnforced, or ReadOnlyExceptAnnotations. Read this property before deciding whether further protection-related processing is needed on a loaded document.
Common Issues and Fixes
Indexing a CustomDocumentProperties collection by name returns nothing usable.
The property doesn’t exist in this document. Call Contains(name) first, or add the property with the appropriate Add(name, value) overload.
Reading a custom property’s value gives the wrong type.
DocumentProperty.Value is untyped object; the caller assumed a type that doesn’t match Type. Use the corresponding typed accessor (ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray()) based on DocumentProperty.Type.
A linked custom property’s value looks stale.
The property is linked via AddLinkToContent, and the bookmarked content changed. Confirm the linkSource bookmark still marks the range that should feed the property’s value.
Word statistics such as Characters or Lines don’t match the document’s actual current content.
Built-in statistics reflect stored metadata, not a live recount. Recompute and update the relevant BuiltInDocumentProperties values if an up-to-date count is required.
Frequently Asked Questions
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 matching 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, accessed as named members. 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 make a custom property track a piece of document content instead of a static value?
Use CustomDocumentProperties.AddLinkToContent(name, linkSource), passing a bookmark name as linkSource; the property’s value then reflects that bookmarked content.
How do I check whether a document is password protected?
Read Document.BuiltInDocumentProperties.Security, a DocumentSecurity value; PasswordProtected indicates the document’s stored metadata declares password protection.