Come lavorare con i documenti in .NET
Questa guida mostra come lavorare con il modello object Document in Aspose.Words FOSS per .NET: creare un documento vuoto, caricare in modo sicuro uno esistente, percorrere la sua struttura sezione/corpo, combinare documenti e applicare una restrizione di modifica. Aspose.Words FOSS per .NET è disponibile tramite NuGet o compilando dal sorgente.
Guida passo passo
Passo 1: Ottieni la libreria
Clona il repository e compila Aspose.Words.sln in configurazione Release, quindi aggiungi un riferimento al progetto a Aspose.Words.csproj dal tuo progetto .NET. I comandi completi per clonare e compilare sono nella Guida di installazione. Una volta referenziato, aggiungi using Aspose.Words; all’inizio di qualsiasi file che lavora con i documenti.
Passo 2: Crea o carica un documento
Chiama new Document() per ottenere un documento vuoto, oppure passa un percorso file o Stream al costruttore Document(fileName) / Document(stream) per aprirne uno esistente. Una overload che accetta un argomento LoadOptions ti consente di fornire una password per un file crittografato. Prima di caricare un file il cui formato non conosci già, chiama FileFormatUtil.DetectFileFormat(fileName) — restituisce un FileFormatInfo che segnala il LoadFormat rilevato e se il file è IsEncrypted, HasDigitalSignature o HasMacros, così puoi rifiutare input inaspettati prima che Document tenti di analizzarlo.
Passo 3: Autore del contenuto con DocumentBuilder
DocumentBuilder avvolge un Document con un cursore che sposti attraverso l’albero mentre inserisci contenuto. Write(text) e Writeln(text) inseriscono testo al cursore, e InsertParagraph() avvia un nuovo paragrafo. La formattazione impostata sulle proprietà Font, ParagraphFormat, ListFormat e PageSetup del builder si applica a tutto ciò che scrivi dopo. Riposiziona il cursore con MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName) o MoveToParagraph(paragraphIndex, characterIndex), e leggi CurrentNode / CurrentParagraph / CurrentSection per confermare dove è posizionato il builder.
Passo 4: Ispeziona la sezione e la struttura del corpo
Un Document espone un SectionCollection tramite Document.Sections (più FirstSection / LastSection). Ogni Section ha esattamente un Body, il cui contenuto principale è raggiungibile tramite Body.Paragraphs (un ParagraphCollection) e Body.Tables. Per leggere o cercare testo senza percorrere manualmente i nodi, usa il Range disponibile su Document, Section, Paragraph e altri nodi — Range.Text restituisce il suo testo semplice, e Range.Replace(pattern, replacement) esegue una ricerca e sostituzione limitata a quel range.
Passo 5: Combina due documenti
Per copiare un intero documento, chiama Document.Clone(). Per trasferire contenuti specifici da un’istanza Document a un’altra, chiama ImportNode(srcNode, isImportChildren) sul documento di destinazione, oppure chiama Document.AppendDocument(srcDoc, importFormatMode) per aggiungere ogni sezione di un documento sorgente alla fine di quello corrente. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) fa lo stesso ma inserisce al cursore del builder anziché alla fine. In tutti e tre i casi, scegli deliberatamente il valore ImportFormatMode — KeepSourceFormatting, UseDestinationStyles o KeepDifferentStyles — poiché decide quale stile del documento prevale dove i due si scontrano.
Passo 6: Applica una restrizione di modifica
Chiama Document.Protect(type, password) con un valore ProtectionType — ReadOnly, AllowOnlyComments, AllowOnlyRevisions o AllowOnlyFormFields — per limitare quali modifiche Word accetta per il documento. Unprotect() (con o senza la password corrispondente) rimuove la restrizione. Questo influisce solo sulla modifica all’interno di Word; non cifra il file salvato. Per richiedere una password solo per aprire il file, imposta OoxmlSaveOptions.Password al momento del salvataggio.
Problemi comuni e soluzioni
Document(fileName) lancia un’eccezione per un file che si apre correttamente in Word. Il formato del file non è supportato dai loader di questa edizione. Chiama FileFormatUtil.DetectFileFormat(fileName) prima e controlla il valore restituito LoadFormat prima di tentare di caricare.
Il contenuto copiato tra documenti prende i font o gli stili sbagliati. Il ImportFormatMode passato a AppendDocument or InsertDocument non corrisponde a quello che ti aspettavi. Passa KeepSourceFormatting or UseDestinationStyles esplicitamente invece di fare affidamento su un valore predefinito.
Unprotect() sembra non avere alcun effetto. Oppure il documento non era protetto da una password (chiama Unprotect() senza argomenti), oppure la password fornita non corrisponde a quella Protect() con cui è stata chiamata.
Formattazione applicata tramite DocumentBuilder non appare dove previsto. Formattazione a livello di Builder (Font, ParagraphFormat) si applica solo al contenuto scritto after è impostata. Sposta il cursore e imposta la formattazione prima di chiamare Write/Writeln, non dopo.
Domande frequenti
Come creo un nuovo documento Word vuoto?
Chiama new Document(). Avvolgilo con un DocumentBuilder per iniziare a inserire contenuti immediatamente.
Qual è la differenza tra Document.Clone() e ImportNode?
Clone() copia un intero documento in una nuova istanza di Document. ImportNode(srcNode, isImportChildren) porta un singolo nodo — e facoltativamente i suoi figli — dall’albero di un documento a un altro, ed è ciò che usi per combinare contenuti specifici anziché documenti interi.
Come posso verificare in modo sicuro il formato di un file prima di caricarlo?
Chiama FileFormatUtil.DetectFileFormat(fileName) (o la versione sovraccaricata Stream) e ispeziona le proprietà LoadFormat, IsEncrypted, HasDigitalSignature e HasMacros dell’FileFormatInfo restituito prima di passare il file a Document.
Come leggo solo i paragrafi all’interno del corpo di un documento?
Usa la collezione Body.Paragraphs sul Body della sezione, o Body.GetChildNodes(nodeType, isDeep) per altri tipi di nodo.
Il Document.Protect cifra il file salvato?
No — è una restrizione di modifica che Word applica quando il file viene aperto. Per richiedere una password per aprire il file stesso, impostare OoxmlSaveOptions.Password quando si chiama Document.Save.
