빠른 시작
MVC 5 또는 Web Forms에서 첫 번째 문서를 렌더링
이 단계별 가이드는 .NET Framework 4.7.2에서 ASP.NET 애플리케이션을 설치된 패키지에서 브라우저에 렌더링된 문서로 전환합니다: Global.asax, 열린 엔드포인트, 뷰어 자산, 위젯, 그리고 이를 연결하는 토큰. Installation에서의 Web.config 등록이 설정되어 있다고 가정합니다 — DocImage.axd 핸들러와 리소스 모듈이 없으면 아래 내용이 서버에 도달할 수 없습니다.
Global.asax에서 Doconut 구성
MVC 5 애플리케이션을 위한 완전한 Application_Start:
// Global.asax.cs - 작업자 프로세스당 한 번 구성하고, 종료 시 해제합니다.
protected void Application_Start()
{
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.UnsafeMode = false; // 페이지는 문서를 연 세션에만 제공됩니다.
});
// MVC 전용: 두 Doconut 엔드포인트를 라우팅에서 제외합니다.
RouteTable.Routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
RouteTable.Routes.IgnoreRoute("doconut-res/{*pathInfo}");
}
protected void Application_End()
{
Doconut.DoconutHost.Shutdown();
}- **
Encoding.RegisterProvider**은 일부 문서 형식에서 사용하는 레거시 코드 페이지를 프로세스에서 사용할 수 있게 합니다. 첫 번째 문서를 열기 전에 한 번 호출하십시오. - **
UnsafeMode = false**은 기본값이며, 실수로 변경되지 않도록 명시적으로 적습니다:DocImage.axd는 문서를 연 ASP.NET 세션에만 페이지를 제공합니다. - 두
IgnoreRoute호출은 MVC 라우팅이DocImage.axd와/doconut-res/*에 접근하지 않도록 합니다. 이들은 핸들러와 모듈이 제공합니다. Web Forms 애플리케이션에는 MVC 라우트가 없으므로 이 줄이 필요하지 않습니다. - **
DoconutHost.Shutdown**는 애플리케이션 풀 재시작 시 Doconut의 백그라운드 작업을 중지하고 서비스를 해제합니다.Initialize가 실행되지 않았더라도 호출해도 안전합니다.
문서 열기
문서를 열면 불투명 토큰이 반환됩니다. 위젯은 각 페이지 요청에 해당 토큰을 함께 보냅니다.
MVC 5에서는 컨트롤러 액션이 DoconutHost.Services에서 Viewer 서비스를 해결합니다 — MVC 5는 이에 대한 생성자 주입을 지원하지 않습니다:
// POST /Document/Open
[HttpPost]
public async Task<ActionResult> Open()
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
// 토큰은 불투명합니다 - 뷰어에 전달하고, 절대 로그에 남기거나 저장하지 마세요.
string token = await viewer.OpenDocumentAsync(Server.MapPath("~/files/Sample.pdf"));
return Json(new { token });
}문서는 세션 상태가 있는 요청 내부에서 열어야 합니다. 이는 현재 ASP.NET 세션에 페이지 접근 권한을 부여하기 때문입니다. MVC 컨트롤러와 Web Forms 페이지는 기본적으로 세션 상태를 가집니다. 맞춤형 IHttpHandler는 System.Web.SessionState.IRequiresSessionState를 구현하지 않는 한 세션 상태가 없습니다. 핸들러에서 이를 사용하지 않고 문서를 열면 뷰어는 모든 페이지에서 "이 페이지를 볼 권한이 없습니다." 라는 메시지를 표시합니다.
Web Forms에서는 페이지 자체가 코드 비하인드에서 문서를 열 수 있습니다. OpenDocument는 비동기 페이지를 사용하지 않는 코드 비하인드를 위해 설계된 OpenDocumentAsync의 동기 형태입니다:
// Default.aspx.cs
protected string Token;
protected void Page_Load(object sender, EventArgs e)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
Token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
}토큰을 베어러 자격 증명처럼 취급하십시오: 절대 로그에 남기거나 저장하지 말고 위젯에만 전달하십시오. 문서 세션이 만료되면 토큰은 작동을 멈춥니다 — 새 토큰을 얻으려면 문서를 다시 열어야 합니다.
뷰어 자산 참조
Viewer.ReferenceCss와 Viewer.ReferenceScripts는 임베디드 자산을 위한 <link>와 <script> 태그를 종속 순서대로 생성하며, /doconut-res/를 가리킵니다. 위젯은 jQuery 플러그인이므로 jQuery가 먼저 로드됩니다.
MVC 5. 뷰에는 @inject가 없으므로, 컨트롤러에서 태그를 생성하고 ViewBag에 전달합니다:
public ActionResult Index()
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true
});
ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true
});
return View();
}@Html.Raw(ViewBag.ViewerCss)
...
@Html.Raw(ViewBag.ViewerScripts)그 작업은 컨트롤러에 두세요. MVC 5는 뷰를 처음 제공할 때 컴파일하며, 추가 컴파일러 패키지가 없으면 해당 컴파일러는 C# 5만 이해합니다 — no ?., no $"...", no nameof. 이를 사용하는 뷰는 Visual Studio에서 정상적으로 컴파일되지만 브라우저에서는 빈 500를 반환합니다.
Web Forms. 코드 비하인드에서 동일한 문자열을 노출하고 <%= %>로 작성합니다:
<head>
<%= ViewerCss %>
</head>
<body>
...
<%= ViewerScripts %>
</body>IncludeViewerCss와 IncludeViewerScripts는 필수 코어입니다. 검색 및 주석 리본을 추가하려면 IncludeSearchCss, IncludeAnnotationCss, IncludeSearchScripts, IncludeSearchBar, IncludeAnnotationScripts 및 IncludeAnnotationBar도 설정하십시오. 라이선스가 해당 기능을 허용하지 않을 경우 두 방법 모두 리본 파일을 제외하지만, 뷰어 자체는 여전히 시작됩니다.
페이지에 뷰어 추가
렌더링 표면은 두 개의 중첩된 div입니다:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>외부 div에 실제 높이를 지정하세요 — 뷰어는 컨테이너를 채우고 시작 시 측정합니다. 뷰어는 자체 툴바를 그리지 않으며: GotoPage, Next, Zoom, FitType 및 나머지는 페이지가 자체 버튼에 연결하는 메서드이며, 뷰어 옆에 배치됩니다:
<nav id="toolbar" aria-label="Document viewer controls">
<button type="button" onclick="objViewer.GotoPage(1)">First</button>
<button type="button" onclick="objViewer.Next(false)">Previous</button>
<button type="button" onclick="objViewer.Next(true)">Next</button>
<button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
<button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
<button type="button" onclick="objViewer.FitType('width')">Fit width</button>
</nav>뷰어 초기화 및 문서 표시
뷰어 스크립트를 로드한 후 위젯을 생성하고 토큰을 전달합니다:
var objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: '/', // '/' 은 사이트 루트의 DocImage.axd 를 의미합니다
ResPath: 'doconut-res/images', // 앞에 '/' 가 없습니다
onViewerReady: function () {
// 페이지가 표시됩니다; 여기에서 로딩 표시기를 숨깁니다
},
onError: function (message) {
console.error('Doconut viewer error:', message);
}
});
fetch('/Document/Open', { method: 'POST' })
.then(function (resp) { return resp.json(); })
.then(function (data) { objViewer.View(data.token); });Web Forms에서 페이지가 직접 문서를 열 경우, 마지막 세 줄은 objViewer.View('<%= Token %>');가 됩니다.
다음 네 가지 세부 사항은 오류 메시지 없이 실패합니다:
- **
BasePath: '/'**는 사이트 루트의DocImage.axd를 가리킵니다. 가상 디렉터리의 애플리케이션인 경우 슬래시 없이 이름을 사용하세요 ('myapp'는/myapp/DocImage.axd를 요청합니다). 앞에 슬래시('/myapp')가 있으면//myapp/DocImage.axd가 생성되어 브라우저가 이를 다른 호스트에 대한 요청으로 해석합니다. ResPath: 'doconut-res/images'— 아이콘은 리소스 루트 아래 한 폴더에 있습니다.'doconut-res'를 사용하면 모든 아이콘이 404를 반환합니다: 툴바 글리프와 로딩 스피너가 없으며 문서 자체는 여전히 렌더링됩니다. 앞에 슬래시가 있으면BasePath와 동일하게 깨집니다.- 콜백은 옵션입니다.
onViewerReady,onError및 나머지는docViewer(...)에 전달되는 객체에 포함됩니다. 뷰어 이름과 같은 전역 함수, 예를 들어ctlDoc_ViewerReady는 호출되지 않습니다. - 뷰어를 유지하고, 별도로
View를 호출하십시오.docViewer(...)는Zoom,Next및FitType가 포함된 객체를 반환합니다;View(...)는 다른 것을 반환합니다.var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)는 문서를 렌더링하지만 첫 번째 툴바 클릭 시objViewer.Zoom is not a function와 함께 실패합니다.
옵션 이름은 camelCase(showThumbs, autoLoad, pageZoom)와 PascalCase(FitType, BasePath, ResPath)가 혼합됩니다. 철자가 틀린 옵션은 무시되고 위젯은 기본값을 사용합니다.
한 줄 대안
자신만의 툴바가 필요 없는, 문서만 표시하면 되는 페이지의 경우, Viewer.RenderViewer 은 전체 초기화 스크립트를 작성합니다 — docViewer(...) 은 BasePath: '/' 와 ResPath: 'doconut-res/images' 로, 그 다음에 .View(token) 합니다. 이 스크립트는 이 패키지에만 포함되어 있습니다:
// Default.aspx.cs
protected string ViewerInit;
protected void Page_Load(object sender, EventArgs e)
{
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
string token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
ViewerInit = viewer.RenderViewer("div_ctlDoc", token);
}<div id="div_ctlDoc" style="height: 100vh"></div>
<%= ViewerScripts %>
<%= ViewerInit %>줌, 맞춤, 썸네일 패널을 변경하려면 세 번째 인수로 ViewerConfig 를 전달하십시오. 생성된 스크립트가 뷰어에 대한 참조를 유지하지 않기 때문에, 페이지에 자체 툴바가 필요할 때는 위의 수동 초기화를 사용하십시오.
문서 닫기
사용자가 뷰어를 떠나거나 대체 뷰어를 열 때 objViewer.Close(true) 를 호출하십시오: 위젯을 정리하고 DocImage.axd 에 닫기 요청을 보냅니다. 인자를 전달하지 않은 objViewer.Close() 은 위젯만 정리합니다. 서버에서는 viewer.CloseDocument(token) 가 문서 세션을 즉시 제거하고, 렌더링 자원을 해제하며, 해당 세션의 페이지 접근 권한을 회수합니다. 슬라이딩 만료도 결국 동일하게 동작하지만, 큰 문서를 명시적으로 닫으면 메모리를 더 빨리 해제할 수 있습니다.
실행하기
~/files/Sample.pdf 에 PDF를 배치하고, IIS Express에서 사이트를 시작합니다 (Visual Studio에서 F5). 위젯을 호스팅하는 페이지를 엽니다. 첫 페이지가 렌더링되고 왼쪽에 썸네일이 표시됩니다. 만약 표시되지 않으면 문제 해결 을 참고하십시오.
라이선스 없이 얻는 것
라이선스가 없다고 오류가 발생하지는 않습니다. 뷰어는 정상적으로 렌더링되지만, 모든 페이지에 평가용 워터마크가 표시됩니다. Doconut이 라이선스를 찾는 위치는 라이선스 설정 을 참고하십시오.
이 페이지가 도움이 되었나요?