Lavorare con le proprietà del documento

Lavorare con le proprietà del documento

Questa guida mostra come leggere e gestire i metadati di un documento Word — le proprietà visibili nel pannello Info/Proprietà di Word, oltre a eventuali valori personalizzati definiti dall’applicazione. Document.BuiltInDocumentProperties e Document.CustomDocumentProperties espongono queste due categorie, entrambe alla fine basate sulla stessa rappresentazione DocumentProperty sottostante.

Proprietà del documento integrate

Document.BuiltInDocumentProperties restituisce una collezione BuiltInDocumentProperties che copre i metadati standard che Word registra per ogni documento: campi descrittivi come Title, Subject, Author, Manager, Company, Category, Keywords e Comments; timestamp come CreatedTime, LastSavedTime e LastPrinted, insieme a LastSavedBy e RevisionNumber; e statistiche come Words, Characters, CharactersWithSpaces, Lines, Paragraphs e Pages. Security segnala lo stato di protezione del documento come valore DocumentSecurity, e Template, NameOfApplication e TotalEditingTime descrivono l’ambiente di creazione. Poiché BuiltInDocumentProperties è un insieme fisso e noto di proprietà, i singoli valori vengono letti e scritti come proprietà ordinarie (BuiltInDocumentProperties.Author = "...") anziché cercati per nome.

Proprietà del documento personalizzate

Document.CustomDocumentProperties restituisce una collezione CustomDocumentProperties per i metadati definiti dall’applicazione che non fanno parte del set integrato di Word. Diverse sovraccariche di Add(name, value) creano una nuova proprietà a partire da un nome e da un valore tipizzato (stringa, numero, booleano o data, a seconda della sovraccarica), e AddLinkToContent(name, linkSource) genera una proprietà il cui valore è collegato e traccia un intervallo di contenuto contrassegnato da segnalibro nel documento invece di contenere un valore statico. L’indicizzazione per nome (ad es. properties[name]) e Contains(name) consentono di cercare una proprietà, IndexOf(name) restituisce la sua posizione, e Remove(name)/RemoveAt(index) la eliminano.

L’oggetto DocumentProperty e la Base della Collezione Condivisa

Sia BuiltInDocumentProperties che CustomDocumentProperties derivano dall’astratta DocumentPropertyCollection, che definisce un indicizzatore per nome, GetEnumerator(), Contains(name), IndexOf(name) e Count — così le due raccolte vengono ispezionate allo stesso modo anche se le proprietà predefinite sono fisse e le proprietà personalizzate sono aperte. Singolarmente, un DocumentProperty possiede un Name, un Value non tipizzato e un Type (un valore enum PropertyType: Boolean, DateTime, Double, Number, String, StringArray, ObjectArray, ByteArray o Other). IsLinkToContent e LinkSource indicano se la proprietà è collegata al contenuto del documento anziché contenere un valore statico (vedi AddLinkToContent sopra). Poiché Value non è tipizzato, DocumentProperty fornisce accessor tipizzati — ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray() e ToString() — per leggerlo come un tipo specifico senza un cast esplicito.

Sicurezza del documento

BuiltInDocumentProperties.Security restituisce un valore DocumentSecurity che descrive lo stato di protezione del documento: None, PasswordProtected, ReadOnlyRecommended, ReadOnlyEnforced o ReadOnlyExceptAnnotations. Ciò riflette i metadati di protezione memorizzati nel documento, letti dalle proprietà del file.

Consigli e buone pratiche

• Utilizza gli accessor tipizzati (ToInt(), ToDouble(), ToDateTime(), ToBool()) su DocumentProperty.Value invece di eseguire un cast diretto del valore object non tipizzato, poiché il tipo di archiviazione sottostante può variare a seconda di PropertyType.
• Verifica Contains(name) prima di indicizzare in una delle raccolte di proprietà per nome (ad esempio properties[name]) quando una proprietà potrebbe non esistere, per evitare di gestire il caso di proprietà mancante come un percorso di eccezione.
• Utilizza CustomDocumentProperties.AddLinkToContent(name, linkSource) quando il valore di una proprietà personalizzata deve sempre riflettere una parte contrassegnata del documento, invece di sincronizzare manualmente una proprietà definita dall’utente statica ogni volta che quel contenuto cambia.
• Considera le statistiche di BuiltInDocumentProperties (Words, Characters, Pages e simili) come i valori memorizzati nei metadati del file anziché conteggi calcolati in tempo reale — aggiornali esplicitamente se il documento è stato modificato da quando sono stati scritti l’ultima volta.
• Leggi BuiltInDocumentProperties.Security per verificare lo stato di protezione dichiarato del documento prima di decidere se è necessario eseguire ulteriori elaborazioni correlate alla protezione.

Problemi comuni

FAQ

Come leggo o imposto l’autore e il titolo del documento?

Usa Document.BuiltInDocumentProperties.Author e .Title direttamente — sono proprietà stringa ordinarie nella raccolta BuiltInDocumentProperties raggiunta da Document.BuiltInDocumentProperties.

Come aggiungo metadati specifici dell’applicazione che non sono una proprietà standard di Word?

Utilizza Document.CustomDocumentProperties.Add(name, value) con il nome e il valore della proprietà; viene selezionata la sovraccarico Add appropriata in base al tipo del valore.

Qual è la differenza tra BuiltInDocumentProperties e CustomDocumentProperties?

BuiltInDocumentProperties è l’insieme fisso di campi di metadati standard di Word (autore, titolo, statistiche, ecc.), accessibili come proprietà denominate. CustomDocumentProperties è una raccolta aperta, nominata, di valori DocumentProperty per metadati definiti dall’applicazione, accessibile per nome tramite l’indicizzatore (ad es. properties[name]) e Contains.

Come leggere una proprietà personalizzata senza conoscere in anticipo il tipo memorizzato esatto?

Recupera il DocumentProperty indicizzando la raccolta (ad es. properties[name]), verifica il suo Type (un valore PropertyType), e utilizza l’accessor tipizzato corrispondente come ToInt(), ToDouble(), ToDateTime() o ToBool() sul suo Value.

Come fare in modo che un campo personalizzato segua un segmento di contenuto del documento?

Usa CustomDocumentProperties.AddLinkToContent(name, linkSource), passando il nome di un segnalibro come linkSource; il valore della proprietà rifletterà quindi quel contenuto contrassegnato anziché un valore statico.

API Reference Riepilogo

Vedi anche

• Aspose.Words for .NET — Enterprise Documentation