문제 해결
일반적인 오류 진단
많은 System.Web 오류는 눈에 보이는 예외를 발생시키지 않습니다: 페이지가 빈 500 로 응답하거나, 아이콘이 404를 반환하거나, 요청이 절대 반환되지 않습니다. 이 페이지는 관찰한 내용에 따라 정리되었습니다. 인용된 메시지는 Doconut이 실제로 출력하는 텍스트입니다.
한눈에 보는 증상
| 보이는 현상 | 가장 가능성 높은 원인 | 해결 방법 |
|---|---|---|
모든 요청이 빈 500 로 응답 | Application_Start 에서 발생한 예외: 라이선스가 없는 플러그인, 잘못된 옵션, 불완전한 팜 구성 — 또는 bin\ 에 없는 버전을 지정한 바인딩 리다이렉트 | Windows 이벤트 로그, Application, source ASP.NET. 시작 실패 보기 |
일부 MVC 페이지가 빈 500 로 응답 | Razor가 런타임에 뷰를 컴파일합니다: netstandard 파사드가 <compilation> 에 없거나, 뷰가 C# 5보다 최신 버전(?., $"...", nameof)을 사용합니다 | 파사드 추가 (설치); 로직을 뷰에서 컨트롤러로 이동 |
페이지에 대시와 악센트 대신 —, … 또는 유사한 문자가 표시 | 바이트 순서 표시가 없는 페이지 파일이 서버의 ANSI 코드 페이지로 읽힙니다 | <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" /> |
브라우저 콘솔에 HEAD /DocImage.axd?...&page=1 에 대한 404 가 표시 | 핸들러가 HEAD 동사 없이 등록되었습니다 | 핸들러에 verb="GET,HEAD,POST" 추가 |
| 문서는 렌더링되지만 툴바 아이콘과 로딩 스피너가 없습니다 | ResPath 가 리소스 루트를 가리키거나 / 로 시작합니다 | ResPath: 'doconut-res/images' |
/doconut-res/... 요청이 404 로 응답 | 리소스 모듈이 등록되지 않았거나, runAllManagedModulesForAllRequests 가 꺼져 있거나, MVC 라우팅이 경로를 잡습니다 | <modules> 항목 및 routes.IgnoreRoute("doconut-res/{*pathInfo}") |
뷰어가 The viewer handler could not be reached (no response). 를 보고합니다 | BasePath 가 / 로 시작합니다 ('/myapp' 가 //myapp/… 로 변환, 다른 호스트) | 사이트 루트에 BasePath: '/'; 가상 디렉터리에 'myapp' |
뷰어가 Please make sure your middleware is configured. 를 보고합니다 | DocImage.axd 가 404 로 응답: 핸들러가 Web.config 에 없거나, MVC 라우팅이 잡았거나, BasePath 가 다른 위치를 가리킵니다 | <handlers> 항목, routes.IgnoreRoute("{resource}.axd/{*pathInfo}"), 및 BasePath |
모든 페이지에 You Are Not Authorized To View This Page. 가 표시 | 문서가 세션 상태가 없는 요청에서 열렸거나, 세션 상태가 꺼져 있거나, 세션 쿠키가 DocImage.axd 에 도달하지 못함 | 권한 없음 보기 |
| Web Forms 변환이 절대 반환되지 않음 | 페이지가 ConvertAsync 에서 블록됨 — 교착 상태 | Async="true" + RegisterAsyncTask (변환 플러그인) |
| 모든 페이지에 평가 워터마크가 표시 | 라이선스를 찾을 수 없음 — <site root>\wwwroot 에 없습니다 | 라이선스 설정 |
위젯이 로드되지만 첫 번째 동작이 404 로 응답 | 위젯이 활성화되지 않았거나, basePath 가 '/DocImage.axd' 가 아님 | options.Add…Widget(), 및 basePath: '/DocImage.axd' |
| 사이트 시작 또는 재시작 후 첫 번째 문서는 1분 이상 걸리며, 이후 문서는 빠릅니다 | 문서 엔진이 첫 열기 시 로드되고, 실시간 안티바이러스가 로드 중에 스캔합니다 | 사이트를 미리 워밍업하고 풀을 계속 실행하십시오 — 시작 후 첫 번째 문서 보기 |
| 큰 파일 업로드 시 IIS 오류 페이지가 표시 | 업로드가 maxRequestLength (KB) 또는 maxAllowedContentLength (바이트)를 초과함 | 가장 큰 파일 또는 위젯 제한보다 높게 설정하십시오 |
시작 실패
Application_Start 에서 발생한 예외가 브라우저에 도달하지 않습니다: 모든 요청이 빈 500 로 응답하고, IIS 로그에는 유용한 정보가 없습니다. 예외는 Windows 이벤트 로그 (Event Viewer → Windows Logs → Application, source ASP.NET)에 기록됩니다. 일반적인 경우는 다음과 같습니다:
라이선스가 없는 플러그인:
The Converter plugin is registered via AddPlugin but no active license grants Converter.
Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.플러그인의 Doconut.Viewer.<Capability>.lic 은 wwwroot 에 있어야 하며, Doconut.Viewer.lic 옆에 위치합니다. 라이선스가 없고 레거시 TRIAL 파일이 있으면 플러그인 기능이 제공되지 않습니다.
잘못된 옵션:
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.로드할 수 없는 어셈블리. ASP.NET은 애플리케이션 시작 시 bin\ 에 있는 모든 어셈블리를 로드하므로, bin\ 에 없는 버전을 지정한 Web.config 의 바인딩 리다이렉트가 전체 사이트를 중단시킵니다. 수동으로 편집하는 대신 NuGet이 생성한 리다이렉트를 복사하십시오( SDK 스타일 프로젝트의 경우 bin\<YourApp>.dll.config 에서), 패키지 업데이트 후에도 다시 복사하십시오.
이 페이지를 볼 권한이 없습니다.
요청한 ASP.NET 세션에 문서 권한이 부여되지 않아 페이지가 거부되었습니다. 순서대로 확인하십시오:
- 세션 상태와 함께 열기가 실행되었습니다. MVC 컨트롤러와 Web Forms 페이지는 이를 가지고 있습니다. 문서를 여는 사용자 정의
IHttpHandler는System.Web.SessionState.IRequiresSessionState를 구현해야 하며, 그렇지 않으면 부여할 세션이 없습니다. - 세션 상태가 켜져 있습니다.
<sessionState mode="Off" />는 모든 페이지를 거부합니다. - 쿠키가 핸들러에 도달합니다. 위젯의 동일 출처 요청은
ASP.NET_SessionId를 포함합니다; 스크립트, 서버 간 호출, 또는 쿠키가 없는 교차 출처 페이지는 포함하지 않습니다. - 웹 팜: 열기는 브라우저(
DocOptions.BrowserId)와 바인딩되고 페이지는 티켓(objViewer.View(token, access))을 전달합니다; 모든 노드는 동일한 서명 키를 사용합니다.
거부는 상태 200와 함께 제공되는 이미지이며, 약 2KB입니다. 상태 코드만 확인하는 모니터는 이를 페이지로 간주합니다.
문서 세션을 찾을 수 없습니다. 문서를 다시 열어 주세요.
토큰이 만료되었습니다(슬라이딩 윈도우, DocOptions.TimeOut, 기본 60분), 문서가 닫혔거나 — 단일 서버에서는 — 애플리케이션 풀을 재활용했습니다. 재활용은 일정에 따라, 매 Web.config 편집 시, 그리고 풀의 유휴 시간 초과(기본 IIS에서는 20분) 후에 발생합니다. 새 토큰을 위해 문서를 다시 엽니다.
문서 열기 실패
LicenseException와 거부 사유 — 라이선스 파일은 발견되었지만 거부되었습니다(잘못된 서명, 변조, 블랙리스트, 또는 라이선스 버전 창을 벗어난 빌드). 열기는 워터마크가 아니라 차단됩니다.
LicenseException:
This document type requires the 'Dicom' plugin license.확장자는 플러그인(여기서는 DICOM)만 처리합니다. 플러그인은 등록되어 있지만 더 이상 해당 기능을 부여하는 라이선스가 없습니다 — 일반적으로 사이트 시작 후 만료된 임시 라이선스입니다. 기능을 부여하는 라이선스를 설치하십시오.
FormatNotSupportedException — 내장, 플러그인 또는 사용자 정의 뷰어 중 어느 것도 해당 확장자를 지원하지 않습니다. DoconutOptions.RegisterViewer를 사용하면 자체 포맷에 대한 뷰어를 추가할 수 있습니다.
InvalidDataException — 콘텐츠가 손상되었거나 확장자와 일치하지 않습니다(이름이 바뀐 파일). 열기 전에 업로드를 검증하십시오.
InvalidOperationException:
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().DocumentConverter는 Converter 플러그인을 등록하지 않고 해결되었습니다.
출력이 잘못 보입니다
페이지에 워터마크가 표시됩니다 — 라이선스를 찾을 수 없거나 임시 라이선스가 만료되었습니다. 활성 임시 라이선스 하에서는 플러그인 출력에만 워터마크가 적용됩니다. 이 버전을 포함하지 않는 라이선스는 워터마크가 적용되지 않으며, 열기 시 LicenseException가 발생합니다. IIS에서는 라이선스가 사이트 루트(AppContext.BaseDirectory\wwwroot) 아래 wwwroot에 있어야 하며, bin\에 있으면 안 됩니다. IDoconutLicenseService를 확인하십시오(License.IsLicenseFileFound, IsExpired, IsVersionValid, License.RejectionMessage).
레거시 문서가 깨진 텍스트로 표시됩니다 — 시작 시 한 번 코드 페이지 인코딩을 등록하십시오:
// Global.asax.cs, Application_Start - DoconutHost.Initialize 이전에.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);잘못된 또는 대체된 폰트 — 서버에 문서에 필요한 폰트가 없습니다. Office가 없는 Windows Server는 개발 머신보다 훨씬 적은 폰트를 가지고 있습니다. 폰트를 설치하거나, FontFolders(WordConfig 및 PptConfig에) 폰트가 들어 있는 폴더를 가리키도록 설정하십시오.
이미지 주석은 뷰어에 표시되지만 내보내기에서는 "Image blocked" 상자가 나타납니다 — 이미지 호스트가 사설 또는 루프백 주소여서 서버가 가져오기를 거부합니다. 주석을 참조하십시오.
평가에서는 작동했지만, 프로덕션에서는 무음
활성 임시 라이선스는 모든 기능을 부여합니다; 구매한 라이선스는 구매한 기능만 부여합니다. 기능이 없으면 해당 검색 또는 주석 파일이 생성되지 않으며, 등록된 플러그인은 시작 시 사이트를 중단시킵니다. 배포 전에 사용 중인 모든 기능과 IsCapabilityGranted(...)를 비교하십시오.
검색 결과가 없거나(또는 너무 적음)
- PDF의 경우, 문서를 열 때
AllowSearch가 활성화되지 않았으며 — 기본값은false입니다. Word, Excel, PowerPoint도 동일한 스위치를 제공합니다. - 내용이 스캔되었거나 이미지 전용이므로 일치시킬 텍스트 레이어가 없습니다.
- HTML 및 Microsoft Project (MPP)는 기본 설정에서는 검색할 수 없습니다:
DefaultRender = false를 설정하여 텍스트가 포함된 PDF 투영으로 렌더링하도록 하세요. objViewer.CanSearch()는 초기화 후false입니다: 해결된 형식에 검색 경로가 없습니다. 이는 Search 라이선스와 별개이며, 두 가지를 모두 확인하십시오.- 페이지는
objViewer.Search(...)의 반환 값을 읽습니다 — 카운트는 세 번째 인수인 콜백으로 전달됩니다.
아직도 막히셨나요?
문제를 최소 설정으로 재현하려면 빠른 시작을 사용하십시오. 해당 환경에서 재현된다면, 문서와 귀하의 Global.asax.cs, Doconut 부분의 Web.config, 그리고 존재한다면 Windows 이벤트 로그 항목을 포함하여 지원팀에 연락하십시오.
이 페이지가 도움이 되었나요?