Come lavorare con le proprietà del documento in .NET
Come lavorare con le proprietà del documento in .NET
Ogni documento Word contiene due categorie di metadati — i campi standard che Word traccia per ogni file e i valori definiti dall’applicazione che un programma ha aggiunto. Questa guida mostra come leggere e impostare entrambi con Aspose.Words FOSS per .NET, usando Document.BuiltInDocumentProperties e Document.CustomDocumentProperties, entrambi costruiti alla fine sulla stessa rappresentazione DocumentProperty.
Guida passo passo
Passo 1: Leggere e impostare le proprietà del documento integrate
Document.BuiltInDocumentProperties restituisce una collezione BuiltInDocumentProperties. Poiché si tratta di un insieme fisso e noto di proprietà, i valori vengono letti e scritti come membri ordinari piuttosto che ricercati per nome — ad esempio BuiltInDocumentProperties.Author, .Title, .Subject, .Manager, .Company, .Category, .Keywords e .Comments per i campi descrittivi, oppure .CreatedTime, .LastSavedTime, .LastPrinted e .LastSavedBy per i timestamp. Statistiche come .Characters, .CharactersWithSpaces, .Lines e .Bytes sono anch’esse esposte in questo modo, insieme a .Template e .HyperlinkBase.
Passo 2: Aggiungere una proprietà del documento personalizzata
Document.CustomDocumentProperties restituisce una collezione CustomDocumentProperties per i metadati definiti dall’applicazione che non fanno parte del set integrato di Word. Chiama una delle overload Add(name, value) con un nome e un valore tipizzato — stringa, numero, booleano o data, a seconda di quale overload corrisponde al tipo del valore — per creare una nuova proprietà.
Passo 3: Collega una proprietà personalizzata al contenuto del documento
Invece di un valore statico, una proprietà personalizzata può tenere traccia di un intervallo di contenuto contrassegnato da un segnalibro in modo che il suo valore rimanga sincronizzato con quel contenuto. Chiama CustomDocumentProperties.AddLinkToContent(name, linkSource), passando il nome del segnalibro come linkSource, anziché sincronizzare manualmente una proprietà statica ogni volta che il contenuto collegato cambia.
Passo 4: Cerca, verifica e rimuovi le proprietà
Sia BuiltInDocumentProperties sia CustomDocumentProperties derivano dall’astratta DocumentPropertyCollection, quindi vengono ispezionati allo stesso modo: indicizzare per nome (ad es. properties[name]) recupera una proprietà, Contains(name) verifica se esiste, IndexOf(name) restituisce la sua posizione e Count indica quante proprietà contiene la collezione. Chiama Contains(name) prima di indicizzare per nome quando una proprietà personalizzata potrebbe non esistere, per evitare di gestire una proprietà mancante come percorso di eccezione. Rimuovi una proprietà con Remove(name) o RemoveAt(index), oppure cancella tutte le proprietà nella collezione con Clear().
Passo 5: Leggi il valore di una proprietà personalizzata senza conoscere in anticipo il suo tipo
Un DocumentProperty ha un Name, un Value non tipizzato e un Type — un valore enum PropertyType: Boolean, DateTime, Double, Number, String, StringArray, ObjectArray, ByteArray o Other. Poiché Value non è tipizzato, usa l’accessor tipizzato corrispondente invece di eseguire un cast diretto: ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray() o ToString(). Controlla IsLinkToContent e LinkSource per scoprire se una proprietà è collegata al contenuto del documento (vedi Passo 3) anziché contenere un valore statico.
Passo 6: Verifica lo stato di protezione di un documento
BuiltInDocumentProperties.Security segnala un valore DocumentSecurity che descrive i metadati di protezione memorizzati del documento: None, PasswordProtected, ReadOnlyRecommended, ReadOnlyEnforced o ReadOnlyExceptAnnotations. Leggi questa proprietà prima di decidere se è necessario ulteriore elaborazione correlata alla protezione su un documento caricato.
Problemi comuni e soluzioni
Indicizzare un CustomDocumentProperties la collezione per nome non restituisce nulla di utilizzabile. La proprietà non esiste in questo documento. Chiama Contains(name) prima, oppure aggiungi la proprietà con l’appropriata Add(name, value) sovraccarico.
Leggere il valore di una proprietà personalizzata restituisce il tipo errato. DocumentProperty.Value è non tipizzato object; il chiamante ha assunto un tipo che non corrisponde Type. Usa l’accessore tipizzato corrispondente (ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray()) in base a DocumentProperty.Type.
Il valore di una proprietà personalizzata collegata sembra obsoleto. La proprietà è collegata tramite AddLinkToContent, e il contenuto contrassegnato è cambiato. Conferma il linkSource segnalibro segna ancora l’intervallo che dovrebbe alimentare il valore della proprietà.
Statistiche delle parole come Characters or Lines non corrispondono al contenuto attuale reale del documento. Le statistiche integrate riflettono i metadati archiviati, non un conteggio in tempo reale. Ricalcola e aggiorna i valori pertinenti BuiltInDocumentProperties valori se è necessario un conteggio aggiornato.
Domande frequenti
Come leggo o imposto l’autore e il titolo del documento?
Usa Document.BuiltInDocumentProperties.Author e .Title direttamente — sono normali proprietà stringa nella collezione BuiltInDocumentProperties raggiungibile da Document.BuiltInDocumentProperties.
Come aggiungo metadati specifici dell’applicazione che non sono una proprietà standard di Word?
Usa Document.CustomDocumentProperties.Add(name, value) con il nome e il valore della proprietà; la sovraccarica corrispondente di Add viene selezionata in base al tipo del valore.
Qual è la differenza tra BuiltInDocumentProperties e CustomDocumentProperties?
BuiltInDocumentProperties è l’insieme fisso di campi di metadati standard di Word, accessibili come membri nominati. CustomDocumentProperties è una collezione aperta e nominata di valori DocumentProperty per metadati definiti dall’applicazione, accessibile per nome tramite l’indicizzatore (ad esempio properties[name]) e Contains.
Come faccio a far sì che una proprietà personalizzata tracci una parte del contenuto del documento invece di un valore statico?
Usa CustomDocumentProperties.AddLinkToContent(name, linkSource), passando un nome di segnalibro come linkSource; il valore della proprietà rifletterà allora quel contenuto segnalato.
Come faccio a verificare se un documento è protetto da password?
Leggi Document.BuiltInDocumentProperties.Security, un valore DocumentSecurity; PasswordProtected indica che i metadati memorizzati del documento dichiarano la protezione con password.
