Come caricare documenti Word in .NET
Come caricare documenti Word in .NET
Aspose.Words FOSS per .NET legge un documento in memoria non appena si costruisce un Document oggetto — ogni percorso di caricamento nella libreria passa attraverso Document’s overload del costruttore e la LoadOptions classe. Questa guida mostra come caricare un documento da un file o da uno stream, fornire una password o impostazioni specifiche del formato, e controllare cosa accade quando il caricamento incontra una risorsa esterna o un documento che potrebbe essere malformato. Aspose.Words FOSS per .NET è costruito dal sorgente e referenziato direttamente in un progetto anziché installato da un feed di pacchetti — vedere il Guida all’installazione per i passaggi di compilazione prima di procedere con le attività qui sotto.
Guida passo-passo
Passo 1: Carica un documento da un file o da uno stream
Document ha cinque costruttori. Document() crea un nuovo documento vuoto invece di caricarne uno. Document(fileName) carica direttamente da un percorso su disco, e Document(stream) carica da qualsiasi Stream leggibile — utile quando la fonte non è un file, ad esempio contenuti già in memoria o ricevuti tramite una connessione di rete. Entrambi hanno una sovraccarica complementare che accetta un secondo argomento, Document(fileName, loadOptions) e Document(stream, loadOptions), che è il punto di ingresso per ogni altra attività in questa guida.
Passo 2: Carica un documento protetto da password
Costruisci un LoadOptions con la password prima di chiamare Document(fileName, loadOptions) (o la sovraccarico dello stream). new LoadOptions(password) imposta LoadOptions.Password direttamente; in alternativa, imposta Password su un’istanza LoadOptions() senza parametri prima di passarla. Fornisci la password in anticipo anziché caricare prima e reagire a un errore — Aspose.Words FOSS per .NET ha bisogno della password per analizzare un file protetto, quindi non esiste uno stato parzialmente caricato da recuperare.
Passo 3: Applica le opzioni specifiche del formato per le sorgenti di testo e Markdown
Le sorgenti di testo normale e Markdown accettano impostazioni che la LoadOptions base non espone. TxtLoadOptions aggiunge AutoNumberingDetection e DetectNumberingWithWhitespaces per riconoscere gli elenchi numerati nel testo normale, DetectHyperlinks per trasformare URL nudi in collegamenti ipertestuali, DocumentDirection (LeftToRight, RightToLeft o Auto) per la direzione del flusso di testo, e LeadingSpacesOptions/TrailingSpacesOptions separati (di tipo TxtLeadingSpacesOptions/TxtTrailingSpacesOptions) per la gestione degli spazi bianchi all’inizio e alla fine di ogni riga. MarkdownLoadOptions aggiunge PreserveEmptyLines, ImportUnderlineFormatting e SoftLineBreakCharacter per controllare come le convenzioni di interruzione di riga di Markdown vengono mappate su paragrafi e sequenze. Entrambe le sottoclassi derivano da LoadOptions, quindi una password o una callback di caricamento risorse impostata su una di esse si comporta allo stesso modo della classe base — passa l’istanza specifica del formato a Document(fileName, loadOptions) esattamente come faresti con un semplice LoadOptions.
Passo 4: Reindirizza o intercetta le risorse esterne durante il caricamento
Imposta LoadOptions.ResourceLoadingCallback a un’implementazione di IResourceLoadingCallback quando hai bisogno di controllare come una risorsa esterna referenziata dal documento viene risolta durante il caricamento. Il suo metodo ResourceLoading(args) riceve un ResourceLoadingArgs che descrive il ResourceType della risorsa (Image, Font, CssStyleSheet o Document) insieme a Uri e OriginalUri, e restituisce un ResourceLoadingAction — Default per caricare la risorsa normalmente, Skip per ometterla, o UserProvided per sostituire i dati forniti tramite ResourceLoadingArgs.SetData(data).
Passo 5: Imposta i valori predefiniti della lingua e il comportamento di recupero
Quando i metadati della lingua di un documento sono mancanti o inaffidabili, imposta LoadOptions.LanguagePreferences.DefaultEditingLanguage a un valore EditingLanguage prima del caricamento, e usa AddEditingLanguage(language) o AddEditingLanguages(languages) su LanguagePreferences per registrare lingue aggiuntive che il documento potrebbe contenere. Per le sorgenti che potrebbero essere malformate, imposta LoadOptions.RecoveryMode a un valore DocumentRecoveryMode — None per caricare senza alcun tentativo di recupero, o TryRecover per far sì che il caricatore aggiri alcuni problemi strutturali invece di far fallire il caricamento del tutto.
Problemi comuni e soluzioni
Caricare un documento protetto da password genera ancora un’eccezione dopo aver fornito la password. Conferma che la password sia stata impostata sull’esatto LoadOptions istanza passata a Document(fileName, loadOptions) (o la sovraccarico di stream) — tramite new LoadOptions(password) o impostando Password successivamente — e che questo è l’oggetto realmente passato al costruttore. Un LoadOptions che è stato creato ma mai consegnato a Document non ha alcun effetto sul caricamento.
Le impostazioni specifiche per Text o Markdown non sembrano applicarsi. Verifica che un TxtLoadOptions or MarkdownLoadOptions istanza — non la base LoadOptions — è stato passato al Document costruttore. Solo la sottoclasse espone le proprietà specifiche del formato; passare la classe base compila ma le elimina silenziosamente.
Le risorse esterne non vengono intercettate o reindirizzate. ResourceLoadingCallback deve essere impostato sullo stesso LoadOptions oggetto passato al Document costruttore, e deve essere assegnato prima della chiamata load. Assegnarlo dopo che il caricamento è già completato non ha alcun effetto.
Un documento malformato continua a non caricarsi dopo aver impostato RecoveryMode. DocumentRecoveryMode.TryRecover consente al caricatore di aggirare alcuni problemi strutturali in un documento, ma una corruzione più grave può comunque impedire il caricamento corretto del documento.
Un documento caricato da un Stream si comporta in modo diverso rispetto allo stesso file caricato tramite percorso. Verifica che la posizione dello stream sia all’inizio prima di passarla a Document(stream) or Document(stream, loadOptions) — uno stream interrotto a metà del suo contenuto carica solo i byte rimanenti.
Domande frequenti
Come posso caricare un documento senza alcuna opzione speciale?
Passa un percorso file o un Stream direttamente a Document(fileName) o Document(stream) — LoadOptions è necessario solo quando è richiesta una password, impostazioni specifiche del formato o un callback.
Qual è la differenza tra LoadOptions, TxtLoadOptions e MarkdownLoadOptions?
TxtLoadOptions e MarkdownLoadOptions derivano entrambi da LoadOptions e aggiungono impostazioni specifiche per sorgenti di testo semplice e Markdown rispettivamente. Ogni proprietà generale di LoadOptions — password, codifica, callback — rimane disponibile in entrambe le sottoclassi.
Posso caricare un documento direttamente da un array di byte?
Avvolgi i byte in un MemoryStream e passa quello stream a Document(stream) o Document(stream, loadOptions) — non esiste un costruttore che accetti direttamente un array di byte.
Come posso controllare cosa succede quando il loader non riesce a risolvere una risorsa esterna?
Implementa IResourceLoadingCallback e assegnalo a LoadOptions.ResourceLoadingCallback. Restituisci ResourceLoadingAction.Skip da ResourceLoading(args) per omettere la risorsa invece di far fallire il caricamento.
Impostare RecoveryMode modifica il modo in cui viene caricato un documento ben formato?
No. DocumentRecoveryMode cambia il comportamento solo quando il loader incontra realmente problemi strutturali — un documento ben formato viene caricato allo stesso modo indipendentemente dall’impostazione.
