Cómo cargar documentos Word en .NET
Cómo cargar documentos Word en .NET
Aspose.Words FOSS para .NET lee un documento en memoria tan pronto como construyes un Document objeto — cada ruta de carga en la biblioteca se canaliza a través de Documentsobrecargas del constructor de ’s y la LoadOptions clase. Esta guía muestra cómo cargar un documento desde un archivo o un flujo, proporcionar una contraseña o configuraciones específicas de formato, y controlar lo que ocurre cuando la carga encuentra un recurso externo o un documento que podría estar malformado. Aspose.Words FOSS para .NET se construye a partir del código fuente y se referencia directamente en un proyecto en lugar de instalarse desde un feed de paquetes — consulta el Guía de instalación para los pasos de compilación antes de trabajar con las tareas a continuación.
Guía paso a paso
Paso 1: Cargar un documento desde un archivo o flujo
Document tiene cinco constructores. Document() crea un documento nuevo y vacío en lugar de cargar uno. Document(fileName) carga directamente desde una ruta en disco, y Document(stream) carga desde cualquier Stream legible — útil cuando la fuente no es un archivo, como contenido ya en memoria o recibido a través de una conexión de red. Ambos tienen una sobrecarga complementaria que acepta un segundo argumento, Document(fileName, loadOptions) y Document(stream, loadOptions), que es el punto de entrada para todas las demás tareas de esta guía.
Paso 2: Cargar un documento protegido con contraseña
Construya un LoadOptions con la contraseña antes de llamar a Document(fileName, loadOptions) (o a la sobrecarga de flujo). new LoadOptions(password) establece LoadOptions.Password directamente; alternativamente, establezca Password en una instancia de LoadOptions() sin parámetros antes de pasarla. Proporcione la contraseña de antemano en lugar de cargar primero y reaccionar a un error — Aspose.Words FOSS para .NET necesita la contraseña para analizar un archivo protegido en absoluto, por lo que no hay un estado parcialmente cargado del que recuperarse.
Paso 3: Aplicar opciones específicas de formato para fuentes de texto y Markdown
Las fuentes de texto sin formato y Markdown aceptan configuraciones que la LoadOptions base no expone. TxtLoadOptions agrega AutoNumberingDetection y DetectNumberingWithWhitespaces para reconocer listas numeradas en texto sin formato, DetectHyperlinks para convertir URLs sin formato en hipervínculos, DocumentDirection (LeftToRight, RightToLeft o Auto) para la dirección del flujo de texto, y LeadingSpacesOptions/TrailingSpacesOptions separados (de tipo TxtLeadingSpacesOptions/TxtTrailingSpacesOptions) para el manejo de espacios en blanco al inicio y al final de cada línea. MarkdownLoadOptions agrega PreserveEmptyLines, ImportUnderlineFormatting y SoftLineBreakCharacter para controlar cómo las convenciones de salto de línea de Markdown se asignan a párrafos y ejecuciones. Ambas subclases derivan de LoadOptions, por lo que una contraseña o devolución de llamada de carga de recursos establecida en cualquiera de ellas se comporta igual que en la clase base — pase la instancia específica del formato a Document(fileName, loadOptions) exactamente como lo haría con un LoadOptions plano.
Paso 4: Redirigir o interceptar recursos externos durante la carga
Establezca LoadOptions.ResourceLoadingCallback a una implementación de IResourceLoadingCallback cuando necesite controlar cómo se resuelve un recurso externo referenciado por el documento durante la carga. Su método ResourceLoading(args) recibe un ResourceLoadingArgs que describe el ResourceType del recurso (Image, Font, CssStyleSheet o Document) junto con Uri y OriginalUri, y devuelve un ResourceLoadingAction — Default para cargar el recurso normalmente, Skip para omitirlo, o UserProvided para sustituir datos suministrados a través de ResourceLoadingArgs.SetData(data).
Paso 5: Establecer valores predeterminados de idioma y comportamiento de recuperación
Cuando los metadatos de idioma de un documento faltan o son poco fiables, establezca LoadOptions.LanguagePreferences.DefaultEditingLanguage a un valor EditingLanguage antes de cargar, y use AddEditingLanguage(language) o AddEditingLanguages(languages) en LanguagePreferences para registrar idiomas adicionales que el documento pueda contener. Para fuentes que podrían estar mal formadas, establezca LoadOptions.RecoveryMode a un valor DocumentRecoveryMode — None para cargar sin ningún intento de recuperación, o TryRecover para que el cargador solucione algunos problemas estructurales en lugar de fallar la carga por completo.
Problemas comunes y soluciones
Cargar un documento protegido con contraseña todavía genera una excepción después de proporcionar la contraseña. Confirma que la contraseña se estableció en el exact LoadOptions instancia pasada a Document(fileName, loadOptions) (o la sobrecarga de flujo) — vía new LoadOptions(password) o mediante la configuración de Password después — y que este es el objeto realmente pasado al constructor. Un LoadOptions que se creó pero nunca se entregó a Document no tiene ningún efecto en la carga.
Parece que los ajustes específicos de Texto o Markdown no se aplican. Verifique que un TxtLoadOptions or MarkdownLoadOptions instancia — no la base LoadOptions — se pasó al Document constructor. Sólo la subclase expone las propiedades específicas del formato; pasar la clase base compila pero las elimina silenciosamente.
Los recursos externos no están siendo interceptados ni redirigidos. ResourceLoadingCallback debe establecerse en el mismo LoadOptions objeto pasado al Document constructor, y debe asignarse antes de la llamada a load. Asignarlo después de que la carga ya se haya completado no tiene efecto.
Un documento malformado sigue sin cargarse después de establecer RecoveryMode. DocumentRecoveryMode.TryRecover permite que el cargador eluda algunos problemas estructurales en un documento, pero una corrupción más grave aún puede impedir que el documento se cargue correctamente.
Un documento cargado desde un Stream se comporta de manera diferente al mismo archivo cargado por ruta. Verifique que la posición del flujo esté al inicio antes de pasarlo a Document(stream) or Document(stream, loadOptions) — un flujo que se deja a mitad de su contenido solo carga los bytes restantes.
Preguntas frecuentes
¿Cómo puedo cargar un documento sin ninguna opción especial?
Pasa una ruta de archivo o un Stream directamente a Document(fileName) o Document(stream) — LoadOptions solo se requiere cuando se necesita una contraseña, configuraciones específicas del formato o una devolución de llamada.
¿Cuál es la diferencia entre LoadOptions, TxtLoadOptions y MarkdownLoadOptions?
TxtLoadOptions y MarkdownLoadOptions derivan ambos de LoadOptions y añaden configuraciones específicas para fuentes de texto plano y Markdown respectivamente. Cada propiedad general de LoadOptions — contraseña, codificación, devoluciones de llamada — sigue estando disponible en cualquiera de las subclases.
¿Puedo cargar un documento directamente desde un arreglo de bytes?
Envuelve los bytes en un MemoryStream y pasa ese flujo a Document(stream) o Document(stream, loadOptions) — no existe un constructor que acepte un arreglo de bytes directamente.
¿Cómo controlo qué ocurre cuando el cargador no puede resolver un recurso externo?
Implementa IResourceLoadingCallback y asígnalo a LoadOptions.ResourceLoadingCallback. Devuelve ResourceLoadingAction.Skip desde ResourceLoading(args) para omitir el recurso en lugar de permitir que la carga falle.
¿Establecer RecoveryMode cambia la forma en que se carga un documento bien formado?
No. DocumentRecoveryMode solo cambia el comportamiento cuando el cargador realmente encuentra problemas estructurales — un documento bien formado se carga de la misma manera independientemente de la configuración.
