Como carregar documentos Word em .NET
Como carregar documentos Word em .NET
Aspose.Words FOSS para .NET lê um documento na memória assim que você constrói um Document objeto — todo caminho de carregamento na biblioteca passa por Documentsobrecargas do construtor e a LoadOptions classe. Este guia mostra como carregar um documento a partir de um arquivo ou de um fluxo, fornecer uma senha ou configurações específicas de formato, e controlar o que acontece quando o carregamento encontra um recurso externo ou um documento que pode estar malformado. Aspose.Words FOSS para .NET é compilado a partir do código-fonte e referenciado diretamente em um projeto ao invés de ser instalado a partir de um feed de pacotes — veja o Guia de Instalação para etapas de compilação antes de prosseguir com as tarefas abaixo.
Guia passo a passo
Etapa 1: Carregar um documento de um arquivo ou stream
Document tem cinco construtores. Document() cria um novo documento vazio ao invés de carregar um. Document(fileName) carrega diretamente a partir de um caminho no disco, e Document(stream) carrega de qualquer Stream legível — útil quando a origem não é um arquivo, como conteúdo já em memória ou recebido por uma conexão de rede. Ambos têm uma sobrecarga complementar que aceita um segundo argumento, Document(fileName, loadOptions) e Document(stream, loadOptions), que é o ponto de entrada para todas as outras tarefas neste guia.
Etapa 2: Carregar um documento protegido por senha
Construa um LoadOptions com a senha antes de chamar Document(fileName, loadOptions) (ou a sobrecarga de stream). new LoadOptions(password) define LoadOptions.Password diretamente; alternativamente, defina Password em uma instância LoadOptions() sem parâmetros antes de passá-la. Forneça a senha antecipadamente em vez de carregar primeiro e reagir a uma falha — Aspose.Words FOSS para .NET precisa da senha para analisar um arquivo protegido, portanto não há estado parcialmente carregado do qual se recuperar.
Etapa 3: Aplicar opções específicas de formato para fontes de Texto e Markdown
Fontes de texto puro e Markdown aceitam configurações que o LoadOptions base não expõe. TxtLoadOptions adiciona AutoNumberingDetection e DetectNumberingWithWhitespaces para reconhecer listas numeradas em texto puro, DetectHyperlinks para transformar URLs nuas em hyperlinks, DocumentDirection (LeftToRight, RightToLeft ou Auto) para a direção do fluxo de texto, e LeadingSpacesOptions/TrailingSpacesOptions separados (do tipo TxtLeadingSpacesOptions/TxtTrailingSpacesOptions) para o tratamento de espaços em branco no início e no fim de cada linha. MarkdownLoadOptions adiciona PreserveEmptyLines, ImportUnderlineFormatting e SoftLineBreakCharacter para controlar como as convenções de quebra de linha do Markdown são mapeadas para parágrafos e trechos. Ambas as subclasses derivam de LoadOptions, de modo que uma senha ou callback de carregamento de recurso definido em qualquer uma se comporta da mesma forma que na classe base — passe a instância específica de formato para Document(fileName, loadOptions) exatamente como faria com um LoadOptions simples.
Etapa 4: Redirecionar ou interceptar recursos externos durante o carregamento
Defina LoadOptions.ResourceLoadingCallback para uma implementação de IResourceLoadingCallback quando precisar controlar como um recurso externo referenciado pelo documento é resolvido durante o carregamento. Seu método ResourceLoading(args) recebe um ResourceLoadingArgs descrevendo o ResourceType do recurso (Image, Font, CssStyleSheet ou Document) junto com Uri e OriginalUri, e retorna um ResourceLoadingAction — Default para carregar o recurso normalmente, Skip para omiti-lo, ou UserProvided para substituir os dados fornecidos via ResourceLoadingArgs.SetData(data).
Etapa 5: Definir padrões de idioma e comportamento de recuperação
Quando os metadados de idioma de um documento estiverem ausentes ou não forem confiáveis, defina LoadOptions.LanguagePreferences.DefaultEditingLanguage para um valor EditingLanguage antes do carregamento e use AddEditingLanguage(language) ou AddEditingLanguages(languages) em LanguagePreferences para registrar idiomas adicionais que o documento pode conter. Para fontes que podem estar malformadas, defina LoadOptions.RecoveryMode para um valor DocumentRecoveryMode — None para carregar sem qualquer tentativa de recuperação, ou TryRecover para que o carregador contorne alguns problemas estruturais em vez de falhar o carregamento totalmente.
Problemas Comuns e Soluções
Carregar um documento protegido por senha ainda gera uma exceção após fornecer a senha. Confirme se a senha foi definida no exato LoadOptions instância passada para Document(fileName, loadOptions) (ou a sobrecarga de stream) — via new LoadOptions(password) ou definindo Password posteriormente — e que este é o objeto realmente passado ao construtor. Um LoadOptions que foi criado mas nunca entregue a Document não tem efeito sobre o carregamento.
Configurações específicas de Texto ou Markdown não parecem ser aplicadas. Verifique se um TxtLoadOptions or MarkdownLoadOptions instância — não a base LoadOptions — foi passado para o Document construtor. Apenas a subclasse expõe as propriedades específicas do formato; passar a classe base compila, mas silenciosamente as descarta.
Recursos externos não estão sendo interceptados ou redirecionados. ResourceLoadingCallback deve ser definido no mesmo LoadOptions objeto passado para o Document construtor, e deve ser atribuído antes da chamada de load. Atribuí-lo depois que o carregamento já foi concluído não tem efeito.
Um documento malformado ainda falha ao carregar após definir RecoveryMode. DocumentRecoveryMode.TryRecover permite que o carregador contorne alguns problemas estruturais em um documento, mas corrupções mais graves ainda podem impedir que o documento seja carregado com sucesso.
Um documento carregado de um Stream se comporta de forma diferente do mesmo arquivo carregado por caminho. Verifique se a posição do stream está no início antes de passá-lo para Document(stream) or Document(stream, loadOptions) — um stream deixado no meio de seu conteúdo carrega apenas os bytes restantes.
Perguntas Frequentes
Como posso carregar um documento sem nenhuma opção especial?
Passe um caminho de arquivo ou um Stream diretamente para Document(fileName) ou Document(stream) — LoadOptions só é necessário quando uma senha, configurações específicas de formato ou um callback são necessários.
Qual é a diferença entre LoadOptions, TxtLoadOptions e MarkdownLoadOptions?
TxtLoadOptions e MarkdownLoadOptions derivam ambos de LoadOptions e adicionam configurações específicas para fontes de texto simples e Markdown, respectivamente. Cada propriedade geral de LoadOptions — senha, codificação, callbacks — permanece disponível em ambas as subclasses.
Posso carregar um documento diretamente de um array de bytes?
Envolva os bytes em um MemoryStream e passe esse stream para Document(stream) ou Document(stream, loadOptions) — não existe um construtor que aceite um array de bytes diretamente.
Como controlo o que acontece quando o carregador não consegue resolver um recurso externo?
Implemente IResourceLoadingCallback e atribua-o a LoadOptions.ResourceLoadingCallback. Retorne ResourceLoadingAction.Skip de ResourceLoading(args) para omitir o recurso em vez de deixar o carregamento falhar.
Definir RecoveryMode altera como um documento bem formado é carregado?
Não. DocumentRecoveryMode só altera o comportamento quando o carregador realmente encontra problemas estruturais — um documento bem-formado é carregado da mesma forma, independentemente da configuração.
