렌더링 파이프라인

OpenDocumentAsync와 브라우저에 도달하는 PNG 사이에는 두 개의 구별되는 단계가 있습니다: viewer resolution(문서를 로드하는 엔진, 열 때 한 번 결정)과 page processing(각 요청마다 각 페이지 이미지에 대해 수행되는 작업). 두 단계를 모두 알면 형식이 어떻게 렌더링되는지, 그리고 DefaultRender가 실제로 무엇을 전환하는지 이해할 수 있습니다.

단계 1 — 형식 뷰어 해결

팩토리는 파일 확장자를 형식 카탈로그를 통해 뷰어에 매핑하며, 우선순위는 세 단계로 나뉩니다:

1. 사용자 지정 뷰어 우선. DoconutOptions.RegisterViewer(extension, factory, defaultConfig?) 로 등록한 모든 항목은 모든 내장 뷰어보다 우선합니다.
2. 내장 패밀리 뷰어. 카탈로그는 각 보기 가능한 확장자를 뷰어 패밀리(Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn)와 매핑하며, 각각 고유한 엔진 어댑터를 가집니다. 동일한 확장자에 대해 라이선스 플러그인이 뷰어를 제공하면 플러그인 뷰어가 내장 뷰어를 대체합니다. AddDoconut() 은 시작 시 등록된 플러그인 권한을 검증하고, 팩토리의 내장 뷰어로의 폴백은 방어적인 런타임 규칙입니다.
3. 플러그인 전용 형식. 일부 확장자는 내장 뷰어가 전혀 없습니다 — DICOM(.dcm)은 DICOM 플러그인을 통해서만 존재합니다. 필요한 기능 없이 열면 다음과 같은 예외가 발생합니다:

LicenseException: This document type requires the 'Dicom' plugin license.

뷰어가 없는 확장자를 요청하면 다음과 같은 예외가 발생합니다:

FormatNotSupportedException: Document format '<extension>' is not supported.

해결이 완료되면 구성은 확정됩니다: 전달한 경우 명시적인 구성 객체가 사용되고, 그렇지 않으면 카탈로그에 정의된 형식의 기본 구성이 사용됩니다. DocOptions.Password는 보호된 문서의 구성에 복사됩니다.

단계 1b — 리다이렉트 모드 (DefaultRender = false)

대부분의 형식별 구성은 DefaultRender 플래그를 제공합니다. 이 플래그는 근본적으로 다른 두 경로 중 하나를 선택합니다:

• DefaultRender = true — 문서는 네이티브하게 렌더링되어 바로 페이지 이미지가 됩니다.
• DefaultRender = false — 문서는 먼저 메모리 내에서 PDF로 변환되고, 원본 엔진은 해제되며 PDF 뷰어가 이어서 동작합니다. 생성된 PDF에는 실제 텍스트가 포함되어 전체 텍스트 검색이 픽셀 정확도의 네이티브 하이라이트를 제공합니다; 변환이 사용자에게 보이지 않으므로 파이프라인은 리다이렉트된 PDF에 대해 AllowSearch와 AllowCopy를 강제로 활성화합니다.

XPS와 카탈로그의 기본 MHT는 리다이렉트 경로를 사용합니다. PDF 프로젝션은 HTML 및 Microsoft Project와 같은 형식에 네이티브 검색을 제공할 수 있습니다. 결과 PDF에 텍스트 레이어가 없는 이미지가 포함되어 있으면 표준 뷰어는 해당 픽셀을 검색할 수 없습니다.

문서가 열릴 때 사전 변환 비용이 발생하지만 텍스트가 포함된 PDF 프로젝션이 필요할 경우 리다이렉트 모드를 사용하십시오.

단계 2 — 페이지 이미지 파이프라인

렌더링된 페이지는 요청당 고정된 순서대로 처리됩니다:

raw page PNG → watermark → rotate/flip → scale → annotation burn → PNG to the response

• Watermark — 라이선스 상태(라이선스 누락, 임시 또는 구독 만료, 도메인 불일치, 버전 오류)와 DocOptions.Watermark에 지정한 사용자 정의 텍스트에 따라 적용됩니다. 적절한 라이선스를 보유한 앱(또는 활성 임시 라이선스)이며 사용자 정의 워터마크가 없을 경우 이 단계가 건너뛰어집니다.
• Rotate/flip — 위젯에서 사용자가 설정한 페이지별 상태(90°/180°/270°, 수평/수직 플립)는 세션에 저장되어 해당 페이지가 이후 렌더링될 때마다 적용됩니다.
• Scale — 썸네일 및 줌 레벨은 렌더링된 페이지를 요청된 목표 크기로 스케일링하여 생성됩니다; 0은 원본 크기로 제공함을 의미합니다.
• Annotation burn — 저장된 주석이 비트맵에 그려져 내보내기 및 페이지 이미지에 표시됩니다.
• Encoding — 결과는 풀링된 메모리 스트림을 사용해 PNG로 인코딩되고 HTTP 응답에 직접 기록됩니다.

미들웨어 내부에서 발생한 오류는 HTTP 오류 페이지 대신 PNG 오류 이미지(흰 배경에 빨간 텍스트)로 반환되어 위젯이 페이지 영역에 표시할 수 있습니다.

페이지 캐싱

BaseConfig.CachePages(기본값 true)는 문서 세션 기간 동안 렌더링된 페이지 이미지를 메모리에 유지하여 페이지를 다시 방문해도 재렌더링되지 않게 합니다. BaseConfig.ImageResolution(25–300 DPI, 0 = 형식 기본값)은 주요 품질/메모리 조절값이며, 각 형식의 기본값은 해당 구성 페이지에 문서화되어 있습니다.

무엇을 조정할까