Comment travailler avec les propriétés du document dans .NET
Comment travailler avec les propriétés de document dans .NET
Chaque document Word contient deux catégories de métadonnées — les champs standard que Word suit pour chaque fichier, et les valeurs définies par l’application qu’un programme a ajoutées. Ce guide montre comment lire et définir les deux avec Aspose.Words FOSS pour .NET, en utilisant Document.BuiltInDocumentProperties et Document.CustomDocumentProperties, qui sont tous deux finalement construits sur la même représentation DocumentProperty.
Guide étape par étape
Étape 1 : lire et définir les propriétés de document intégrées
Document.BuiltInDocumentProperties renvoie une collection BuiltInDocumentProperties. Comme il s’agit d’un ensemble fixe et connu de propriétés, les valeurs sont lues et écrites comme des membres ordinaires plutôt que recherchées par nom — par exemple BuiltInDocumentProperties.Author, .Title, .Subject, .Manager, .Company, .Category, .Keywords et .Comments pour les champs descriptifs, ou .CreatedTime, .LastSavedTime, .LastPrinted et .LastSavedBy pour les horodatages. Des statistiques telles que .Characters, .CharactersWithSpaces, .Lines et .Bytes sont également exposées de cette manière, ainsi que .Template et .HyperlinkBase.
Étape 2 : ajouter une propriété de document personnalisée
Document.CustomDocumentProperties renvoie une collection CustomDocumentProperties pour les métadonnées définies par l’application qui ne font pas partie de l’ensemble intégré de Word. Appelez l’une des surcharges Add(name, value) avec un nom et une valeur typée — chaîne, nombre, booléen ou date, selon la surcharge correspondant au type de la valeur — pour créer une nouvelle propriété.
Étape 3 : Lier une propriété personnalisée au contenu du document
Au lieu d’une valeur statique, une propriété personnalisée peut suivre une plage de contenu marquée par un signet afin que sa valeur reste synchronisée avec ce contenu. Appelez CustomDocumentProperties.AddLinkToContent(name, linkSource), en transmettant le nom du signet comme linkSource, plutôt que de resynchroniser manuellement une propriété statique chaque fois que le contenu lié change.
Étape 4 : Rechercher, vérifier et supprimer des propriétés
Les BuiltInDocumentProperties et CustomDocumentProperties proviennent de l’abstrait DocumentPropertyCollection, ils sont donc inspectés de la même manière : l’indexation par nom (par ex. properties[name]) récupère une propriété, Contains(name) vérifie son existence, IndexOf(name) renvoie sa position, et Count indique le nombre de propriétés contenues dans la collection. Appelez Contains(name) avant d’indexer par nom lorsqu’une propriété personnalisée peut ne pas exister, afin d’éviter de traiter une propriété manquante comme un chemin d’exception. Supprimez une propriété avec Remove(name) ou RemoveAt(index), ou effacez toutes les propriétés de la collection avec Clear().
Étape 5 : Lire la valeur d’une propriété personnalisée sans connaître son type à l’avance
Un DocumentProperty possède un Name, un Value non typé, et un Type — une valeur d’énumération PropertyType : Boolean, DateTime, Double, Number, String, StringArray, ObjectArray, ByteArray ou Other. Parce que Value n’est pas typé, utilisez l’accesseur typé correspondant au lieu de caster directement : ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray() ou ToString(). Vérifiez IsLinkToContent et LinkSource pour savoir si une propriété est liée au contenu du document (voir Étape 3) plutôt que de contenir une valeur statique.
Étape 6 : Vérifier l’état de protection d’un document
BuiltInDocumentProperties.Security signale une valeur DocumentSecurity décrivant les métadonnées de protection stockées du document : None, PasswordProtected, ReadOnlyRecommended, ReadOnlyEnforced ou ReadOnlyExceptAnnotations. Lisez cette propriété avant de décider si un traitement supplémentaire lié à la protection est nécessaire sur un document chargé.
Problèmes courants et correctifs
Indexation d’un CustomDocumentProperties la collection par son nom ne renvoie rien d’utile. La propriété n’existe pas dans ce document. Appelez Contains(name) d’abord, ou ajoutez la propriété avec le approprié Add(name, value) surcharge.
Lire la valeur d’une propriété personnalisée renvoie le mauvais type. DocumentProperty.Value est non typé object; l’appelant a supposé un type qui ne correspond pas Type. Utilisez l’accesseur typé correspondant (ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray()) basé sur DocumentProperty.Type.
La valeur d’une propriété personnalisée liée semble obsolète. La propriété est liée via AddLinkToContent, et le contenu marqué a changé. Confirmez le linkSource signet marque toujours la plage qui doit alimenter la valeur de la propriété.
Les statistiques de mots telles que Characters or Lines ne correspondent pas au contenu actuel réel du document. Les statistiques intégrées reflètent les métadonnées stockées, pas un recomptage en temps réel. Recalculez et mettez à jour les valeurs pertinentes BuiltInDocumentProperties valeurs si un comptage à jour est requis.
Questions fréquemment posées
Comment lire ou définir l’auteur et le titre du document?
Utilisez Document.BuiltInDocumentProperties.Author et .Title directement — ce sont des propriétés de chaîne ordinaires sur la collection BuiltInDocumentProperties accessible depuis Document.BuiltInDocumentProperties.
Comment ajouter des métadonnées spécifiques à l’application qui ne sont pas une propriété Word standard?
Utilisez Document.CustomDocumentProperties.Add(name, value) avec le nom et la valeur de la propriété; la surcharge correspondante de Add est sélectionnée en fonction du type de la valeur.
Quelle est la différence entre BuiltInDocumentProperties et CustomDocumentProperties?
BuiltInDocumentProperties est l’ensemble fixe de champs de métadonnées standard de Word, accessibles en tant que membres nommés. CustomDocumentProperties est une collection nommée ouverte de valeurs DocumentProperty pour les métadonnées définies par l’application, accessibles par nom via l’indexeur (par ex. properties[name]) et Contains.
Comment faire en sorte qu’une propriété personnalisée suive une partie du contenu du document au lieu d’une valeur statique?
Utilisez CustomDocumentProperties.AddLinkToContent(name, linkSource), en passant un nom de signet comme linkSource; la valeur de la propriété reflète alors ce contenu signeté.
Comment vérifier si un document est protégé par mot de passe ?
Lisez Document.BuiltInDocumentProperties.Security, une valeur DocumentSecurity ; PasswordProtected indique que les métadonnées stockées du document déclarent une protection par mot de passe.
