렌더링 파이프라인

OpenDocumentAsync와 브라우저에 도달하는 PNG 사이에는 두 개의 뚜렷한 단계가 있습니다: 뷰어 해석(어떤 엔진이 문서를 로드할지, 열 때 한 번 결정)와 페이지 처리(DocImage.axd에 대한 각 요청에서 각 페이지 이미지에 대해 수행되는 작업). 두 단계를 모두 이해하면 형식이 어떻게 렌더링되는지, 그리고 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 등 뷰어 패밀리와 연결합니다. 동일한 확장자에 대해 라이선스가 있는 플러그인이 뷰어를 제공하면, 해당 플러그인 뷰어가 내장 뷰어를 대체합니다.
3. 플러그인 전용 형식. 일부 확장자는 내장 뷰어가 전혀 없으며, DICOM(.dcm, .ima)처럼 플러그인을 통해서만 사용할 수 있습니다. 필요한 기능 없이 열면 다음과 같은 예외가 발생합니다:

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

어떤 뷰어도 매핑되지 않은 확장자는 FormatNotSupportedException을 발생시킵니다.

해결이 끝나면 설정이 확정됩니다: 전달한 명시적 설정 객체가 있으면 그것을 사용하고, 없으면 카탈로그에 정의된 형식 기본 설정을 사용합니다. DocOptions.Password는 보호된 문서의 경우 설정에 복사됩니다.

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

대부분의 형식별 설정에는 DefaultRender 플래그가 있습니다. 이 플래그는 두 가지 근본적으로 다른 경로 중 하나를 선택합니다:

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

XPS와 MHT는 기본적으로 리다이렉트 경로를 사용합니다. PDF 프로젝션은 HTML이나 Microsoft Project와 같은 형식에 네이티브 검색을 제공합니다. 결과 PDF에 텍스트 레이어가 없는 이미지만 포함된 경우 해당 픽셀은 검색할 수 없습니다.

검색 가능하고 텍스트가 포함된 프로젝션이 필요할 때 리다이렉트 모드를 사용하십시오—문서가 열릴 때 초기 변환 비용이 발생합니다.

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

DocImage.axd에 대한 각 페이지 요청은 다음과 같은 고정 순서를 실행합니다:

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

• 워터마크 — 라이선스 상태(라이선스 없음, 만료된 임시·구독 라이선스, 잘못된 도메인, 라이선스 버전 외 빌드)와 DocOptions.Watermark에 지정한 사용자 텍스트에 따라 적용됩니다. 커스텀 워터마크가 없는 라이선스 사이트는 이 단계를 건너뜁니다.
• 회전/플립 — 위젯에서 사용자가 페이지별로 설정한 회전·플립(90°/180°/270°, 수평·수직 플립) 상태가 세션에 저장되고 이후 해당 페이지를 렌더링할 때마다 적용됩니다.
• 스케일 — 썸네일 및 줌 레벨은 렌더링된 페이지를 요청된 크기로 스케일링하여 생성됩니다.
• 주석 삽입 — 저장된 주석이 비트맵에 그려져, 내보내기 및 페이지 이미지에 주석이 표시됩니다.
• 인코딩 — 최종 결과를 PNG로 인코딩하여 바로 응답에 씁니다.

핸들러 내부에서 발생한 오류는 PNG 오류 이미지(흰 배경에 빨간 텍스트)로 반환되며 상태 코드는 200입니다. 이는 위젯이 페이지 영역에 오류를 표시할 수 있게 합니다.

페이지 캐싱

BaseConfig.CachePages(기본값 true)는 문서 세션 수명 동안 렌더링된 페이지 이미지를 메모리에 보관합니다. 따라서 페이지를 다시 방문해도 재렌더링되지 않습니다. BaseConfig.ImageResolution(25–300 DPI, 0 = 형식 기본값)은 품질 및 메모리 사용량을 조절하는 주요 설정이며, 각 형식의 기본값은 형식 설정에서 확인할 수 있습니다.

단일 노드에서는 세션과 캐시된 페이지가 워커 프로세스 메모리에 존재합니다. 애플리케이션 풀 재시작(예약된 재시작, Web.config 편집, 유휴 시간 초과 등) 시 모든 열린 문서 세션이 사라지고 위젯은 Document session not found. Please re-open document. 메시지를 표시합니다. 분산 모드(세션 및 보안 참고)에서는 공유 스토어에서 세션이 재구성됩니다.

조정 위치