LoadOptions를 사용한 문서 로드

LoadOptions를 사용한 문서 로드

이 가이드는 LoadOptions 클래스를 사용하여 단순 파일 경로나 스트림을 넘어 문서 로드를 제어하는 방법을 보여줍니다. Document은 LoadOptions 인스턴스를 받아들일 수 있는 생성자 오버로드를 제공하며 — Document(fileName, loadOptions) 및 Document(stream, loadOptions) — 따라서 여기서 설명한 설정이 모두 로드 시점에 적용되어 문서 객체가 코드에 반환되기 전에 적용됩니다.

LoadOptions 클래스

LoadOptions은 Document 객체에 문서를 로드할 때 Aspose.Words FOSS가 필요로 하는 설정을 전달합니다. 생성자에는 매개변수가 없는 LoadOptions(), 비밀번호로 보호된 파일을 직접 열기 위한 LoadOptions(password), 형식을 명시적으로 지정하기 위한 LoadOptions(loadFormat, password, baseUri)가 포함됩니다. Password와 BaseUri(링크된 리소스와 같은 상대 참조를 해결하는 데 사용) 외에도, LoadOptions은 텍스트 기반 형식을 위한 Encoding, 대용량 문서 처리를 위한 TempFolder, 적용될 Word 버전의 형식 규칙을 지정하는 MswVersion, 그리고 로드 동작을 더 세밀하게 제어하는 UpdateDirtyFields, IgnoreOleData, UseSystemLcid을 노출합니다. LoadOptions.FontSettings를 사용하면 문서가 로드된 후에만 글꼴을 구성하는 대신 로드 시점에 FontSettings를 제공할 수 있습니다.

형식별 로드 옵션

일부 형식은 해당 형식에 특화된 설정을 노출하는 자체 LoadOptions 하위 클래스를 가지고 있습니다. TxtLoadOptions(일반 텍스트용)은 AutoNumberingDetection, DetectNumberingWithWhitespaces, DetectHyperlinks, DocumentDirection를 추가하고, 각 줄의 앞뒤 공백 처리를 제어하기 위해 TxtLeadingSpacesOptions/TxtTrailingSpacesOptions 타입의 별도 LeadingSpacesOptions/TrailingSpacesOptions을 제공합니다. MarkdownLoadOptions은 Markdown의 줄바꿈 규칙이 문서의 단락 및 실행(run)과 어떻게 매핑되는지를 제어하기 위해 PreserveEmptyLines, ImportUnderlineFormatting, SoftLineBreakCharacter을 추가합니다. 두 하위 클래스는 모든 일반 LoadOptions 속성을 상속하므로, TxtLoadOptions 또는 MarkdownLoadOptions 인스턴스에 설정된 비밀번호나 리소스 로딩 콜백은 기본 클래스와 동일하게 동작합니다.

리소스 로딩 콜백

LoadOptions.ResourceLoadingCallback은(는) IResourceLoadingCallback 구현을 받아들이며, 로더가 로드 중인 문서가 참조하는 외부 리소스를 해결할 때 알림을 받습니다. 콜백은 로드되는 리소스의 ResourceType을 설명하는 ResourceLoadingArgs를 받고, 로더에게 리소스를 정상적으로 로드할지, 건너뛸지, 혹은 사용자 정의 데이터를 대체할지 알려주는 ResourceLoadingAction를 반환합니다. 이것은 읽는 형식과 무관하게 로드 중 리소스 해결을 제어하거나 가로채는 확장 지점입니다.

언어, 방향 및 복구 설정

LoadOptions.LanguagePreferences은(는) LanguagePreferences 객체이며, 그 DefaultEditingLanguage( EditingLanguage 열거형 값) 는 문서가 명시적으로 언어를 지정하지 않을 때 FOSS가 가정하는 언어 Aspose.Words을 설정합니다; AddEditingLanguage(language)와 AddEditingLanguages(languages)는 문서가 사용할 수 있는 추가 언어를 등록합니다. DocumentDirection( TxtLoadOptions에서도 직접 노출됨)는 로드 시 텍스트 흐름 방향을 제어하기 위한 LeftToRight, RightToLeft, Auto 값을 갖는 열거형입니다. LoadOptions.RecoveryMode은 DocumentRecoveryMode 값을 받아들여, 로더가 손상되었거나 부분적으로 손상된 문서를 만났을 때 어떻게 대응할지를 제어합니다.

진행 및 경고 콜백

리소스 로드를 넘어서, LoadOptions.WarningCallback과 LoadOptions.ProgressCallback은 각각 로드 중 발생한 비치명적인 문제와 로드 진행 상황에 대해 알림을 받는 콜백 구현을 받아들입니다 — 이는 복구 가능한 문제를 호출 코드에 노출하거나, 폴링 없이 큰 문서의 진행 상황을 보고하는 데 유용합니다.

팁 및 모범 사례

• LoadOptions(password)을 전달하거나 (LoadOptions.Password을 설정)하고 로드 예외를 잡아 다시 시도하는 대신에 사용하십시오 — Aspose.Words FOSS는 문서를 전혀 파싱하기 전에 비밀번호가 필요합니다.
• 언어 메타데이터가 없거나 신뢰할 수 없는 문서를 로드할 때 LanguagePreferences.DefaultEditingLanguage을 설정하면, 하위 단계의 언어 의존 처리 동작이 예측 가능하게 됩니다.
• 해당 형식을 로드할 때는 기본 LoadOptions보다 형식별 옵션 클래스 (TxtLoadOptions, MarkdownLoadOptions)를 사용하는 것이 좋습니다. 구체적인 서브클래스는 기본 클래스가 제공하지 않는 형식 관련 설정을 노출하기 때문입니다.
• 문서가 메모리에 로드된 후가 아니라 로드 중에 외부 리소스 해석을 리다이렉트, 캐시 또는 차단해야 할 때 IResourceLoadingCallback를 구현하세요.
• 신뢰할 수 없거나 제3자 출처의 문서를 처리하는 파이프라인에서는 기본 복구 동작에 의존하기보다 LoadOptions.RecoveryMode를 의도적으로 설정하세요.

일반적인 문제

FAQ

비밀번호로 보호된 문서는 어떻게 로드하나요?

LoadOptions를 비밀번호와 함께 구성하십시오 — new LoadOptions(password) — 또는 LoadOptions.Password를 설정한 뒤 new Document(fileName, loadOptions) 또는 new Document(stream, loadOptions)에 전달하십시오.

형식별 LoadOptions 서브클래스가 필요합니까, 아니면 기본 클래스만으로 충분합니까?

기본 LoadOptions 클래스는 모든 형식에 공통적인 설정(비밀번호, 인코딩, 콜백)을 포함합니다. 텍스트 파일의 공백 처리나 Markdown의 줄바꿈 규칙과 같이 해당 형식에 특화된 설정이 필요할 때는 TxtLoadOptions 또는 MarkdownLoadOptions와 같은 형식별 서브클래스를 사용하십시오.

문서를 로드하는 동안 문서가 참조하는 리소스를 어떻게 가로채거나 리다이렉트할 수 있나요?

IResourceLoadingCallback을 구현하고 로드하기 전에 LoadOptions.ResourceLoadingCallback에 할당하십시오. 콜백은 리소스마다 ResourceLoadingArgs를 받고, 로더가 어떻게 진행할지 결정하는 ResourceLoadingAction를 반환합니다.

로드된 문서에 대해 Aspose.Words FOSS가 어떤 언어를 가정하도록 제어하려면 어떻게 해야 하나요?

로드하기 전에 LoadOptions.LanguagePreferences.DefaultEditingLanguage를 EditingLanguage 값으로 설정하고, AddEditingLanguage/AddEditingLanguages을 사용하여 문서가 포함할 수 있는 추가 언어를 등록하십시오.

로드기가 손상된 문서를 만나면 어떻게 되나요?

동작은 LoadOptions.RecoveryMode에 의해 제어되며, 이는 DocumentRecoveryMode 값으로서 로드기가 원본 문서의 구조적 문제에 어떻게 대응할지를 결정합니다.

API Reference 요약

참조

• Aspose.Words for .NET — Enterprise Documentation