Trabajando con propiedades del documento

Esta guía muestra cómo leer y gestionar los metadatos de un documento de Word — las propiedades visibles en el panel Información/Propiedades de Word, además de los valores personalizados definidos por la aplicación. Document.BuiltInDocumentProperties y Document.CustomDocumentProperties exponen estas dos categorías, ambas construidas finalmente sobre la misma representación subyacente de DocumentProperty.

Propiedades de documento incorporadas

Document.BuiltInDocumentProperties devuelve una colección BuiltInDocumentProperties que cubre los metadatos estándar que Word registra para cada documento: campos descriptivos como Title, Subject, Author, Manager, Company, Category, Keywords y Comments; marcas de tiempo como CreatedTime, LastSavedTime y LastPrinted, junto con LastSavedBy y RevisionNumber; y estadísticas como Words, Characters, CharactersWithSpaces, Lines, Paragraphs y Pages. Security informa el estado de protección del documento como un valor DocumentSecurity, y Template, NameOfApplication y TotalEditingTime describen el entorno de creación. Dado que BuiltInDocumentProperties es un conjunto fijo y conocido de propiedades, los valores individuales se leen y escriben como propiedades ordinarias (BuiltInDocumentProperties.Author = "...") en lugar de buscarse por nombre.

Propiedades personalizadas del documento

Document.CustomDocumentProperties devuelve una colección CustomDocumentProperties para metadatos definidos por la aplicación que no forman parte del conjunto incorporado de Word. Varias sobrecargas de Add(name, value) crean una nueva propiedad a partir de un nombre y un valor tipado (cadena, número, booleano o fecha, según la sobrecarga), y AddLinkToContent(name, linkSource) crea una propiedad cuyo valor está vinculado y sigue a un rango de contenido marcado en el documento en lugar de contener un valor estático. El índice por nombre (p.ej., properties[name]) y Contains(name) buscan una propiedad, IndexOf(name) devuelve su posición, y Remove(name)/RemoveAt(index) la eliminan.

El objeto DocumentProperty y la base de colección compartida

Ambos BuiltInDocumentProperties y CustomDocumentProperties derivan del DocumentPropertyCollection abstracto, que define un indexador por nombre, GetEnumerator(), Contains(name), IndexOf(name) y Count, de modo que las dos colecciones se inspeccionan de la misma forma aunque las propiedades integradas sean fijas y las propiedades personalizadas sean de tipo abierto. Individualmente, un DocumentProperty posee un Name, un Value sin tipo y un Type (un valor de enumeración PropertyType: Boolean, DateTime, Double, Number, String, StringArray, ObjectArray, ByteArray o Other). IsLinkToContent y LinkSource indican si la propiedad está vinculada al contenido del documento en lugar de contener un valor estático (ver AddLinkToContent arriba). Como Value no tiene tipo, DocumentProperty ofrece accesores tipados — ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray() y ToString() — para leerla como un tipo específico sin necesidad de un casting explícito.

Seguridad del documento

BuiltInDocumentProperties.Security informa un valor DocumentSecurity que describe el estado de protección del documento: None, PasswordProtected, ReadOnlyRecommended, ReadOnlyEnforced o ReadOnlyExceptAnnotations. Esto refleja los metadatos de protección almacenados del documento tal como se leen desde las propiedades del archivo.

Consejos y buenas prácticas

Utilice los accesores tipados (ToInt(), ToDouble(), ToDateTime(), ToBool()) en DocumentProperty.Value en lugar de convertir directamente el valor object sin tipo, ya que el tipo de almacenamiento subyacente puede variar según PropertyType.
Verifique Contains(name) antes de indexar en cualquiera de las colecciones de propiedades por nombre (p.ej., properties[name]) cuando una propiedad pueda no existir, para evitar tratar el caso de propiedad ausente como una ruta de excepción.
Utilice CustomDocumentProperties.AddLinkToContent(name, linkSource) cuando el valor de una propiedad personalizada deba reflejar siempre una parte marcada del documento, en lugar de volver a sincronizar manualmente una propiedad estática cada vez que ese contenido cambie.
Considere las estadísticas de BuiltInDocumentProperties (Words, Characters, Pages y similares) como los valores almacenados en los metadatos del archivo en lugar de recuentos siempre calculados en tiempo real; actualícelas explícitamente si el documento ha cambiado desde la última escritura.
Lea BuiltInDocumentProperties.Security para verificar el estado de protección declarado de un documento antes de decidir si se necesita un procesamiento adicional relacionado con la protección.

Problemas comunes

Problema	Causa	Corrección
Al indexar una colección `CustomDocumentProperties` por nombre, no se obtiene nada utilizable	La propiedad no existe en este documento	Llame a `Contains(name)` primero, o añada la propiedad con la sobrecarga adecuada de `Add(name, value)`
Al leer el valor de una propiedad a medida, se obtiene un tipo incorrecto	`DocumentProperty.Value` es un `object` sin tipado; el llamador asumió un tipo que no coincide con `Type`	Utilice el accesor tipado correspondiente (`ToInt()`, `ToDouble()`, `ToDateTime()`, `ToBool()`, `ToByteArray()`) según `DocumentProperty.Type`
El valor de una propiedad personalizada vinculada parece obsoleto	La propiedad está vinculada a través de `AddLinkToContent`, y el contenido enlazado cambió sin que el documento se actualizara adecuadamente	Confirme que el rango `linkSource` marcado aún refleje el contenido previsto
Las estadísticas de palabras (`Words`, `Pages`, etc.) no coinciden con el contenido actual real del documento	Las estadísticas incorporadas reflejan los metadatos almacenados, no un recuento en tiempo real	Recalcule y actualice los valores relevantes de `BuiltInDocumentProperties` si se requiere un recuento actualizado

FAQ

¿Cómo leo o establezco el autor y el título del documento?

Utilice Document.BuiltInDocumentProperties.Author y .Title directamente — son propiedades de cadena ordinarias en la colección BuiltInDocumentProperties a la que se accede desde Document.BuiltInDocumentProperties.

¿Cómo añado metadatos específicos de la aplicación que no son una propiedad estándar de Word?

Utilice Document.CustomDocumentProperties.Add(name, value) con el nombre y el valor de la propiedad; la sobrecarga adecuada de Add se selecciona según el tipo del valor.

¿Cuál es la diferencia entre `BuiltInDocumentProperties` y `CustomDocumentProperties`?

BuiltInDocumentProperties es el conjunto fijo de campos de metadatos estándar de Word (autor, título, estadísticas, etc.), accesibles como propiedades con nombre. CustomDocumentProperties es una colección abierta y con nombre de valores DocumentProperty para metadatos definidos por la aplicación, accesible por nombre mediante el indexador (p. ej., properties[name]) y Contains.

¿Cómo puedo leer una propiedad personalizada sin conocer de antemano su tipo almacenado exacto?

Obtenga el DocumentProperty indexando la colección (p. ej., properties[name]), verifique su Type (un valor PropertyType), y utilice el accesor tipado correspondiente, como ToInt(), ToDouble(), ToDateTime() o ToBool(), sobre su Value.

¿Cómo puedo hacer que una propiedad personalizada rastree una porción del contenido del documento?

Utilice CustomDocumentProperties.AddLinkToContent(name, linkSource), pasando un nombre de marcador como linkSource; el valor de la propiedad entonces refleja ese contenido marcado en lugar de un valor estático.

API Reference Resumen

Clase/Método	Descripción
`Document.BuiltInDocumentProperties`	Campos de metadatos estándar de Word (autor, título, estadísticas, seguridad, etc.)
`Document.CustomDocumentProperties`	Propiedades de metadatos con nombre definidas por la aplicación
`CustomDocumentProperties.Add(name, value)`	Añadir una propiedad personalizada a partir de un nombre y un valor tipado
`CustomDocumentProperties.AddLinkToContent(name, linkSource)`	Añadir una propiedad personalizada vinculada al contenido del documento marcado
`DocumentPropertyCollection`	Base abstracta compartida para ambas colecciones de propiedades
`DocumentProperty`	El nombre de una única propiedad, su valor sin tipo y `PropertyType`
`DocumentProperty.ToInt()` / `ToDouble()` / `ToDateTime()` / `ToBool()`	Accesores tipados para el valor de una propiedad
`PropertyType`	Enum que describe el tipo de valor de un `DocumentProperty`
`DocumentSecurity`	Enum que describe el estado de protección de un documento, mediante `BuiltInDocumentProperties.Security`

Ver también

Aspose.Words for .NET — Enterprise Documentation

Trabajando con propiedades del documento