Document Information

Document Information

This guide shows how to read and write document metadata with Aspose.Words FOSS for .NET. Every loaded or newly created Document carries two kinds of metadata alongside its content: a fixed set of built-in properties (author, title, word count, and similar) and an open-ended set of custom properties you define yourself. Aspose.Words FOSS for .NET also implements the Word fields that surface this metadata inside the document body — AUTHOR, COMMENTS, and DOCPROPERTY — so property values can appear as live, updatable text.

Built-In Document Properties

Document.BuiltInDocumentProperties returns a BuiltInDocumentProperties collection with one property for each standard Word metadata field: Author, Title, Subject, Comments, Category, Company, Manager, Keywords, CreatedTime, LastSavedTime, LastSavedBy, LastPrinted, RevisionNumber, TotalEditingTime, and statistics such as Pages, Words, Characters, CharactersWithSpaces, Paragraphs, and Lines. Because BuiltInDocumentProperties derives from DocumentPropertyCollection, it also supports lookup by name through its indexer, Contains(), IndexOf(), and enumeration through GetEnumerator(). The same collection is exposed on PlainTextDocument.BuiltInDocumentProperties when working with plain-text input.

Custom Document Properties

Document.CustomDocumentProperties returns a CustomDocumentProperties collection for properties an application defines itself — arbitrary name/value pairs that Word stores alongside the built-in set. Add a property with Add(name, value), which is overloaded across CustomDocumentProperties for the value types a property can hold; retrieve one by name with the indexer, e.g. properties[name]; and remove entries with Remove(name), RemoveAt(index), or Clear(). AddLinkToContent(name, linkSource) creates a property whose value is linked to a bookmark or range inside the document rather than stored as a fixed value.

Every entry in either collection — built-in or custom — is a DocumentProperty, which exposes Name, Value, and Type (a PropertyType value: String, Number, Double, Boolean, DateTime, StringArray, ObjectArray, ByteArray, or Other), plus IsLinkToContent and LinkSource for linked properties. DocumentProperty provides conversion helpers such as ToString(), ToInt(), ToDouble(), ToDateTime(), ToBool(), and ToByteArray() for retrieving the underlying value in the desired .NET type.

Document-Information Fields

Three Field subclasses expose document metadata as fields inside the document body itself: FieldAuthor (the AUTHOR field, with an AuthorName property), FieldComments (the COMMENTS field, with a Text property), and FieldDocProperty (the DOCPROPERTY field, which reads a named document property — built-in or custom — into the document). Like every Field, these three share the base Field lifecycle: GetFieldCode() to read the underlying field code, Result / DisplayResult to read the last computed value, Update() to recompute the value, Unlink() to replace the field with its static result, and Remove() to delete it. Insert a document-information field with DocumentBuilder.InsertField(fieldCode) — for example a field code of AUTHOR or DOCPROPERTY "Company" — or with the InsertField(fieldType, updateField) overload using a FieldType value such as FieldType.FieldAuthor, FieldType.FieldComments, or FieldType.FieldDocProperty.

Because FieldDocProperty reads whatever document property it is bound to, changing the underlying BuiltInDocumentProperties or CustomDocumentProperties value and then calling Update() — or Document.UpdateFields() to refresh every field in the document at once — propagates the new value into the field’s displayed result.

Tips and Best Practices

• Set built-in properties such as Title, Author, and Subject before saving — Word and other consumers read these from BuiltInDocumentProperties for document listings and search indexing.
• Use DocumentProperty.Type to check a property’s PropertyType before calling a specific conversion helper (ToInt(), ToDateTime(), etc.) to avoid a conversion mismatch on a property you did not create yourself.
• AddLinkToContent() keeps a custom property synchronized with document content (such as a bookmarked range) instead of a fixed value — use it when the property should always reflect what is currently in the document.
• Call Document.UpdateFields() after changing document properties so any FieldDocProperty, FieldAuthor, or FieldComments fields already in the document body pick up the new values.
• BuiltInDocumentProperties and CustomDocumentProperties are both available on PlainTextDocument as well as Document, so metadata round-trips even when the loaded content is plain text.

Common Issues

FAQ

What is the difference between built-in and custom document properties?

Built-in properties (Document.BuiltInDocumentProperties) are a fixed set defined by the OOXML format — Author, Title, Pages, and similar. Custom properties (Document.CustomDocumentProperties) are an open-ended, application-defined set of name/value pairs added with Add().

How do I make a custom property track document content instead of a fixed value?

Use CustomDocumentProperties.AddLinkToContent(name, linkSource), which links the property’s value to a bookmark or range in the document rather than storing a static value.

Does updating a document property automatically update fields that display it?

No — call Update() on the specific field or Document.UpdateFields() to recompute every field in the document, including FieldDocProperty, FieldAuthor, and FieldComments instances.

Can I read document properties from a plain-text document?

Yes. PlainTextDocument exposes the same BuiltInDocumentProperties and CustomDocumentProperties properties as Document.

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation