문제 해결

일반 오류 진단

아래의 모든 메시지는 Doconut이 생성하는 실제 텍스트이며, 증상별로 정리되었습니다. 오류를 찾아서 해결책을 적용하십시오.

뷰어에 아무 것도 표시되지 않음

빈 뷰어 영역, 브라우저 콘솔에 /doconut-res/...에 대한 404 오류가 가득함
UseDoconutResources()가 없거나 UseDoconut() 뒤에 배치되었습니다. 파이프라인에서 가장 먼저 와야 합니다.

뷰어가 The viewer handler could not be reached (no response).를 보고합니다
요청에 응답이 전혀 오지 않았습니다. 일반적인 원인은 BasePath가 /로 시작하는 경우이며, 이 경우 '/doconut'가 //doconut/DocImage.axd가 되어 다른 호스트에 대한 요청이 됩니다. 선행 슬래시 없이 작성하십시오 (BasePath: 'doconut').

뷰어가 Please make sure your middleware is configured.를 보고합니다
페이지 엔드포인트가 404로 응답했습니다: UseDoconut()가 클라이언트의 BasePath가 가리키는 위치에 마운트되지 않았습니다. app.Map("/doconut", branch => branch.UseDoconut())를 사용하면, 클라이언트는 BasePath: 'doconut'를 사용합니다.

HTTP 500 발생 시:

text
Session middleware not configured. Call UseSession() before UseDoconut().

Doconut의 토큰 보안(기본적으로 활성화)은 ASP.NET 세션 상태가 필요합니다. Doconut 미들웨어 분기 앞에 builder.Services.AddSession()와 app.UseSession()를 추가하십시오. 세션 상태에는 캐시도 필요합니다: 최소 API 앱에서는 builder.Services.AddDistributedMemoryCache()를 추가하고, 그렇지 않으면 Unable to resolve service for type 'IDistributedCache'로 시작 시 앱이 중지됩니다 (MVC 및 Razor Pages 앱은 이미 하나를 등록합니다).

페이지 영역에 표시되는 오류 이미지:

text
You Are Not Authorized To View This Page.

토큰이 다른 브라우저 세션에 의해 열렸습니다. 일반적인 원인: 세션 쿠키가 페이지 요청에 도달하지 않음(크로스 오리진 설정, SameSite 정책, 쿠키 저장소가 없는 API 클라이언트), 또는 앱이 재시작되어(새 세션 키). 이는 설계대로 동작하는 보안 레이어이며 — Core Concepts → Sessions & Security를 참고하십시오. 거부는 상태 200와 함께 제공되는 이미지이며, 상태 코드만 확인하는 모니터는 이를 페이지로 간주합니다.

오류 이미지 내용:

text
Document session not found. Please re-open document.

토큰이 만료되었습니다(슬라이딩 윈도우, 기본 60분 — DocOptions.TimeOut) 또는 세션이 종료되었습니다. 새 토큰을 얻으려면 문서를 다시 열어 주세요.

서버는 정상인데 페이지가 이상하게 동작함 — 오류가 전혀 없음

다음은 애플리케이션을 진행하면서 먼저 의심해야 할 실패 모드입니다. 세 경우 모두 서버는 정상적으로 동작하고, 문서를 올바르게 렌더링하며, 브라우저 콘솔에 아무 오류도 보고하지 않습니다.

멈추지 않는 로딩 스피너. 뷰어 콜백은 컨테이너 ID 이름을 딴 전역 함수로 선언됩니다 — ctlDoc_OnViewerReady() 및 관련 함수들. 이전 뷰어는 이러한 이름을 찾아 사용했지만, 현재 뷰어는 그렇지 않습니다. 스피너를 숨기는 핸들러가 실행되지 않아 스피너가 계속 표시됩니다. 대신 함수를 옵션으로 전달하십시오:

javascript
function ctlDoc_OnViewerBusy() { /* 바쁜 표시기를 표시합니다 */ }
function ctlDoc_OnViewerReady() { /* 숨깁니다 */ }
function ctlDoc_Copy(text) { /* 복사된 텍스트를 사용합니다 */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* 진행 상황을 보고합니다 */ }

const objViewer = $('#div_ctlDoc').docViewer({
    // ... 기존 옵션 ...
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

문서는 스피너 뒤에서 정상입니다. 전체 옵션 목록은 뷰어 구성에서 확인할 수 있습니다.

뷰어 아이콘이나 크롬이 누락되고, 페이지는 그 외에는 정상입니다. ResPath가 비어 있거나 애플리케이션 루트를 가리키고 있습니다 — 이전 라이브러리에서는 올바르지만 여기서는 잘못되었습니다. 이는 UseDoconutResources()가 마운트하는 접두사를 지정해야 합니다:

javascript
ResPath: 'doconut-res/images'   // 또는 '<your ResourcesPath>/images'

공유 스토리지에서 제공할 때 이후 페이지의 타일이 깨짐. 아직 쓰이고 있는 페이지는 202 Accepted로 응답합니다. retryOn409: true가 없는 클라이언트는 이를 실패한 이미지로 처리합니다. 분산 배포를 참고하십시오.

문서 열기 실패

LicenseException: 거부 메시지와 함께 — 라이선스 파일은 발견되었지만 거부되었습니다 (잘못된 서명, 변조, 블랙리스트에 등재, 또는 라이선스의 버전/업데이트 기간 외의 빌드). 이 상태는 워터마크로 낮추는 대신 열기를 차단합니다 (빠른 실패); 이유는 License.RejectionMessage 를 참고하십시오.

LicenseException:

text
This document type requires the 'Dicom' plugin license.

해당 확장자는 플러그인(여기서는 DICOM)에서만 처리됩니다. 플러그인은 등록되어 있지만 더 이상 기능을 허용하는 라이선스가 없습니다 — 일반적으로 앱 시작 후 만료된 임시 라이선스입니다. 기능을 허용하는 라이선스를 설치하고 IDoconutLicenseService 에서 IsCapabilityGranted(LicenseCapability.Dicom) 를 확인하십시오. 누락되었거나 충분하지 않은 비임시 권한은 보통 AddDoconut() 중에 더 일찍 실패합니다.

FormatNotSupportedException:

text
Document format '<extension>' is not supported.

내장, 플러그인, 혹은 사용자 지정 뷰어 중 어느 것도 해당 확장자를 지원하지 않습니다. 지원되는 형식 목록을 확인하십시오; 자체 형식의 경우 DoconutOptions.RegisterViewer 로 추가할 수 있습니다.

InvalidDataException — 파일 내용이 손상되었거나 확장자와 일치하지 않습니다 (예: 파일명을 변경한 경우). 열기 전에 업로드를 검증하십시오.

InvalidOperationException:

text
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

Converter 플러그인을 등록하지 않고 DocumentConverter 를 해결했습니다.

시작 실패

InvalidOperationException: AddPlugin 로 등록된 플러그인을 언급함 — 현재 비임시 라이선스는 해당 플러그인 기능을 허용하지 않습니다. 등록을 제거하거나 해당 기능을 허용하는 라이선스를 설치하십시오. 라이선스가 없고 레거시 TRIAL 파일도 플러그인 기능을 제공하지 않습니다.

ArgumentException: AddDoconut() 로부터

text
DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

빠른 실패 옵션 검증 — 문제 경로를 수정하십시오.

빌드 / 종속성 오류

패키지를 전혀 설치할 수 없음 — Doconut.NETStandard 가 netstandard2.1을 대상으로 하므로 NuGet이 .NET Framework 프로젝트를 거부합니다. 이는 해결 가능한 복원 오류가 아닙니다: .NET Framework은 netstandard2.1을 사용할 수 없습니다. 대신 Doconut.NETFramework 패키지를 사용하십시오.

컴파일 오류 CS1705, 또는 문서를 열 때 런타임 오류:

text
Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'

프로젝트가 Doconut.NETStandard 에서 선언한 9.0.x 의존성보다 낮은 버전의 System.Text.Json 또는 System.Text.Encodings.Web 로 고정되었습니다. 다운그레이드를 제거하고 NuGet이 패키지 그래프를 복원하도록 하십시오 (패키지에 선언된 System.Text.Json 9.0.0 및 System.Text.Encodings.Web 9.0.0).

패키지를 업데이트한 직후 발생하는 다수의 컴파일 오류 — 이는 예상된 동작입니다. 26.8.0 은 26.7.0 과 다른 API 영역이며 호환되는 업데이트가 아닙니다. 대부분의 오류는 루트 Doconut 네임스페이스로 이동한 using 라인 때문이며, 하나씩 패치하기보다 .NET Standard 2.1 로 마이그레이션 을 진행하십시오.

TypeInitializationException: 첫 번째 프레젠테이션 파일에서

text
Could not load ... System.Drawing.Common, Version=6.0.0.0

프레젠테이션 엔진은 System.Drawing.Common 6.0.0 (패키지에 선언됨)을 반드시 필요로 합니다. 해당 의존성을 제거하거나 재정의하지 마십시오 — 이 없이는 모든 PPT/PPTX/PPS/POT/ODP 파일 열기가 실패합니다.

출력이 잘못 표시됨

페이지에 워터마크가 표시됨 — 앱이 평가 모드에 있습니다: 라이선스 파일이 없거나, 만료된 임시 라이선스이거나, 도메인이 유효하지 않습니다. 활성 임시 라이선스 하에서는 플러그인 출력만 워터마크가 적용됩니다. 유료 라이선스 구독 날짜 이후에 릴리스된 빌드는 워터마크가 없으며, 열 때 LicenseException 가 발생합니다. IDoconutLicenseService 를 검사하십시오 (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — 라이선스 페이지의 IDoconutLicenseService 참조가 준비된 엔드포인트를 보여줍니다.

레거시 문서가 깨진 텍스트로 표시됨 — 코드 페이지 인코딩이 기본적으로 로드되지 않습니다. 시작 시 한 번 추가하십시오:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

잘못된 폰트 또는 대체 폰트 — 서버에 문서에 필요한 폰트가 없습니다. 폰트를 설치하거나, FontFolders (on WordConfig/PptConfig) 를 해당 폰트가 있는 폴더로 지정하십시오.

이미지 주석은 뷰어에 표시되지만 내보내기에서는 "Image blocked" 상자가 나타남 — 이미지 호스트가 사설 주소이거나 루프백 주소여서 서버가 가져오기를 거부합니다. Annotations 를 참고하십시오.

평가에서는 기능이 작동하지만, 프로덕션에서는 조용함

클래식한 실시간 전환 서프라이즈: 활성 임시 라이선스는 모든 기능을 부여하지만, 구매한 라이선스는 구매한 것만 부여합니다. 검색 및 주석 번들은 해당 기능이 없을 경우 사라질 수 있습니다. 충분하지 않은 비임시 라이선스를 가진 등록된 Converter 또는 DICOM 플러그인은 AddDoconut() 중에 실패합니다. 배포 전에 활성화하는 모든 기능에 대해 IsCapabilityGranted(...) 를 비교하십시오.

검색이 아무 것도 찾지 못함 (또는 너무 적게)

  • 직접 PDF의 경우, 열 때 AllowSearch 가 활성화되지 않았습니다. Word, Excel, PowerPoint는 중첩된 PdfConfig 를 통해 동일한 스위치를 제공합니다.
  • 내용이 스캔/이미지 전용이므로 일반 검색에는 매칭할 텍스트 레이어가 없습니다. 텍스트가 포함된 소스나 텍스트를 보존하는 PDF 투영을 사용하십시오.
  • HTML 및 MS Project (MPP)는 기본 설정에서는 검색할 수 없습니다 — DefaultRender = false 를 설정하여 PDF 투영을 통해 네이티브 텍스트 레이어로 렌더링되도록 하세요. Word, Excel, PowerPoint, TXT, Visio, 이메일, EPUB, MHT는 카탈로그 기본값에서 검색됩니다.
  • objViewer.CanSearch() 은 초기화 후 false 입니다 — 해결된 형식에는 표준 검색 경로가 없습니다. 이 판단은 Search 라이선스와 별개이며, 두 가지를 모두 확인하십시오.
  • 페이지는 objViewer.Search(...) 의 반환값을 읽습니다 — 카운트는 세 번째 인수인 콜백으로 전달됩니다.

아직도 막혔나요?

문제를 최소 Quick Start 앱에 대해 격리해 보세요; 해당 앱에서 문제가 재현된다면, 문서와 귀하의 Program.cs, 그리고 라이선스 진단 출력을 가지고 지원팀에 연락하십시오.

이 페이지가 도움이 되었나요?