Información del documento

Esta guía muestra cómo leer y escribir metadatos de documentos con Aspose.Words FOSS para .NET. Cada Document cargado o recién creado lleva dos tipos de metadatos junto a su contenido: un conjunto fijo de propiedades incorporadas (autor, título, recuento de palabras y similares) y un conjunto abierto de propiedades personalizadas que usted define. Aspose.Words FOSS para .NET también implementa los campos de Word que exponen estos metadatos dentro del cuerpo del documento — AUTHOR, COMMENTS y DOCPROPERTY — de modo que los valores de las propiedades pueden aparecer como texto en vivo y actualizable.

Propiedades de documento incorporadas

Document.BuiltInDocumentProperties devuelve una colección BuiltInDocumentProperties con una propiedad para cada campo estándar de metadatos de Word: Author, Title, Subject, Comments, Category, Company, Manager, Keywords, CreatedTime, LastSavedTime, LastSavedBy, LastPrinted, RevisionNumber, TotalEditingTime, y estadísticas como Pages, Words, Characters, CharactersWithSpaces, Paragraphs y Lines. Debido a que BuiltInDocumentProperties deriva de DocumentPropertyCollection, también admite la búsqueda por nombre a través de su indexador, Contains(), IndexOf(), y la enumeración mediante GetEnumerator(). La misma colección se expone en PlainTextDocument.BuiltInDocumentProperties al trabajar con entrada de texto plano.

Propiedades de documento personalizadas

Document.CustomDocumentProperties devuelve una colección CustomDocumentProperties para propiedades que una aplicación define por sí misma — pares arbitrarios nombre/valor que Word almacena junto al conjunto incorporado. Añada una propiedad con Add(name, value), que está sobrecargado en CustomDocumentProperties para los tipos de valor que una propiedad puede contener; recupérela por nombre con el indexador, p.ej. properties[name]; y elimine entradas con Remove(name), RemoveAt(index) o Clear(). AddLinkToContent(name, linkSource) crea una propiedad cuyo valor está vinculado a un marcador o rango dentro del documento en lugar de almacenarse como un valor fijo.

Cada entrada en cualquiera de las colecciones — incorporada o personalizada — es un DocumentProperty, que expone Name, Value y Type (un valor PropertyType: String, Number, Double, Boolean, DateTime, StringArray, ObjectArray, ByteArray o Other), además de IsLinkToContent y LinkSource para propiedades vinculadas. DocumentProperty proporciona ayudantes de conversión como ToString(), ToInt(), ToDouble(), ToDateTime(), ToBool() y ToByteArray() para obtener el valor subyacente en el tipo .NET deseado.

Campos de Información del Documento

Tres subclases de Field exponen los metadatos del documento como campos dentro del propio cuerpo del documento: FieldAuthor (el campo AUTHOR, con una propiedad AuthorName), FieldComments (el campo COMMENTS, con una propiedad Text), y FieldDocProperty (el campo DOCPROPERTY, que lee una propiedad de documento nombrada — incorporada o personalizada — dentro del documento). Como cualquier Field, estas tres comparten el ciclo de vida base de Field: GetFieldCode() para leer el código subyacente del campo, Result / DisplayResult para leer el último valor calculado, Update() para recalcular el valor, Unlink() para reemplazar el campo con su resultado estático, y Remove() para eliminarlo. Inserte un campo de información del documento con DocumentBuilder.InsertField(fieldCode) — por ejemplo un código de campo de AUTHOR o DOCPROPERTY "Company" — o con la sobrecarga InsertField(fieldType, updateField) usando un valor FieldType como FieldType.FieldAuthor, FieldType.FieldComments, o FieldType.FieldDocProperty.

Porque FieldDocProperty lee cualquier propiedad del documento a la que esté vinculado, cambiar el valor subyacente de BuiltInDocumentProperties o CustomDocumentProperties y luego llamar a Update() — o a Document.UpdateFields() para actualizar todos los campos del documento a la vez — propaga el nuevo valor al resultado mostrado del campo.

Consejos y Mejores Prácticas

Establezca propiedades incorporadas como Title, Author y Subject antes de guardar — Word y otros consumidores leen estas de BuiltInDocumentProperties para listados de documentos y la indexación de búsqueda.
Utilice DocumentProperty.Type para comprobar el PropertyType de una propiedad antes de llamar a un asistente de conversión específico (ToInt(), ToDateTime(), etc.) para evitar una discordancia de conversión en una propiedad que no creó usted mismo.
AddLinkToContent() mantiene una propiedad personalizada sincronizada con el contenido del documento (como un rango marcado) en lugar de un valor fijo — úsela cuando la propiedad debe reflejar siempre lo que está actualmente en el documento.
Llame a Document.UpdateFields() después de cambiar las propiedades del documento para que cualquier campo FieldDocProperty, FieldAuthor o FieldComments ya presente en el cuerpo del documento adopte los nuevos valores.
BuiltInDocumentProperties y CustomDocumentProperties están ambos disponibles en PlainTextDocument así como en Document, por lo que los metadatos se conservan incluso cuando el contenido cargado es texto plano.

Problemas comunes

Problema	Causa	Solución
El indexador devuelve `null` para una propiedad personalizada	La propiedad aún no se ha añadido	Llame a `CustomDocumentProperties.Add(name, value)` primero, o verifique `Contains(name)` antes de leer
`FieldDocProperty` muestra un valor desactualizado después de cambiar una propiedad	El campo no se actualizó	Llame a `Update()` en el campo, o `Document.UpdateFields()` para actualizar todos los campos en el documento
`DocumentProperty.ToInt()` / `ToDateTime()` lanza	El `Type` real de la propiedad no coincide con la conversión solicitada	Verifique `DocumentProperty.Type` antes de elegir qué asistente de conversión llamar

FAQ

¿Cuál es la diferencia entre las propiedades de documento incorporadas y las personalizadas?

Las propiedades incorporadas (Document.BuiltInDocumentProperties) son un conjunto fijo definido por el formato OOXML — Author, Title, Pages, y similares. Las propiedades personalizadas (Document.CustomDocumentProperties) son un conjunto abierto, definido por la aplicación, de pares nombre/valor añadidos con Add().

¿Cómo hago que una propiedad personalizada rastree el contenido del documento en lugar de un valor fijo?

Utiliza CustomDocumentProperties.AddLinkToContent(name, linkSource), que vincula el valor de la propiedad a un marcador o rango en el documento en lugar de almacenar un valor estático.

¿Actualizar una propiedad del documento actualiza automáticamente los campos que la muestran?

No — llame a Update() en el campo específico o Document.UpdateFields() para recalcular cada campo en el documento, incluidos los instancias de FieldDocProperty, FieldAuthor y FieldComments.

¿Puedo leer las propiedades del documento desde un documento de texto plano?

Sí. PlainTextDocument expone las mismas propiedades BuiltInDocumentProperties y CustomDocumentProperties que Document.

API Reference Resumen

Clase / Método	Descripción
`Document.BuiltInDocumentProperties`	Colección estándar de metadatos OOXML (`Author`, `Title`, `Pages`, etc.)
`Document.CustomDocumentProperties`	Colección de propiedades nombre/valor definida por la aplicación
`CustomDocumentProperties.Add()` / indexador por nombre / `AddLinkToContent()`	Agregar, recuperar o enlazar como contenido una propiedad personalizada
`DocumentProperty`	Entrada única de propiedad; `Value`, `Type`, y `ToString()`/`ToInt()`/`ToDouble()`/`ToDateTime()`/`ToBool()`/`ToByteArray()` asistentes de conversión
`FieldAuthor` / `FieldComments` / `FieldDocProperty`	`AUTHOR`, `COMMENTS`, y `DOCPROPERTY` campos; `Update()`, `Result`, `GetFieldCode()`
`DocumentBuilder.InsertField()`	Inserta un campo mediante código de campo o `FieldType`

Ver también

Aspose.Words for .NET — Enterprise Documentation