빠른 시작
몇 분 안에 첫 문서를 렌더링하세요
이 안내서는 빈 Program.cs에서 브라우저에 문서가 렌더링되는 ASP.NET Core 앱으로 전환합니다: 서버 등록, 전체 Viewer 패키지(Viewer 툴바, Viewer 마운트 및 선택적 검색/주석 리본), 자산 참조, 클라이언트 초기화, 문서 열기 및 실행.
서버 설정
AddDoconut() 은 서비스를 등록합니다; UseDoconutResources() 와 UseDoconut() 은 미들웨어를 연결합니다. 리소스 호출은 먼저 와야 합니다. UseDoconut() 은 도달하는 모든 요청에 응답하므로 app.Map 로 자체 브랜치에 마운트하십시오. 세션 호출도 필요합니다 — Doconut의 기본 문서 보안은 모든 페이지 요청을 ASP.NET 세션 상태와 검증합니다. 세션 상태에는 캐시가 필요합니다: AddDistributedMemoryCache() 가 제공합니다. MVC 또는 Razor Pages 앱은 이미 이를 등록하지만, 최소 API 앱은 등록하지 않으며, 없으면 앱이 시작 시 Unable to resolve service for type 'IDistributedCache' 로 중단됩니다. 이미 설치 중에 Doconut을 등록했나요? 다음 섹션으로 건너뛰세요.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // 세션 상태에는 캐시가 필요합니다 (MVC/Razor Pages는 이미 하나를 추가합니다)
builder.Services.AddSession(); // Doconut 문서 보안은 ASP.NET 세션 상태에 의존합니다
app.UseSession(); // UseSession()을 UseDoconut()보다 먼저 호출하세요
app.UseDoconutResources(); // UseDoconut()보다 먼저 등록되어야 합니다
app.Map("/doconut", branch => branch.UseDoconut());프로덕션 스타일 경로 레이아웃을 위해, 문서 미들웨어를 명시적인 브랜치에 매핑하고 네 개의 경로 설정을 정렬된 상태로 유지하십시오:
builder.Services.AddDoconut(options =>
{
options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
options.MiddlewarePath = "/doconut";
options.ResourcesPath = "/doconut-res";
options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());MiddlewarePath 은 조정 값이며, 자체적으로 ASP.NET Core 브랜치를 매핑하지 않습니다. 이 예제에서 호스트는 /doconut 를 매핑하므로 클라이언트는 BasePath: 'doconut' 를 사용합니다. ResourcesPath 은 /doconut-res 에 임베디드 번들을 제공하고, 위젯의 이미지 리소스 경로는 따라서 ResPath: 'doconut-res/images' 입니다. 두 경로 모두 선행 슬래시 없이 작성하십시오: 뷰어가 자체적으로 슬래시를 추가하므로 '/doconut' 은 //doconut/DocImage.axd 로 변환되고, 브라우저는 이를 doconut 라는 호스트에 대한 요청으로 읽어 뷰어가 "The viewer handler could not be reached" 오류와 함께 실패합니다.
페이지에 뷰어 추가
Viewer는 페이지에 필수적인 핵심입니다. 그 렌더링 표면은 두 개의 중첩된 div 를 사용합니다:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>툴바, 모듈 마운트 및 Viewer 표면을 하나의 페이지 구성으로 취급하십시오. 검색 및 주석은 선택적 마운트에 임베디드 리본을 삽입하지만, 해당 모듈은 절대 독립적으로 존재하지 않으며 항상 같은 페이지의 Viewer에 연결됩니다. 다음 순서를 사용하십시오:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Viewer 탐색, 확대/축소, 검색 및 주석 버튼 -->
</nav>
<div id="searchBarMount"></div>
<div id="annBarMount"></div>
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>뷰어 자산 참조
Razor 뷰에서 주입된 Viewer 서비스는 의존 순서대로 뷰어의 <link> 와 <script> 태그를 출력합니다 — 위젯은 jQuery 플러그인이므로 jQuery를 뷰어 스크립트보다 먼저 로드해야 합니다:
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true
}))전체 Viewer 패키지를 위해 Viewer와 모듈 리소스를 함께 요청하십시오:
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true,
IncludeSearchCss = true,
IncludeAnnotationCss = true
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true,
IncludeSearchScripts = true,
IncludeSearchBar = true,
IncludeAnnotationScripts = true,
IncludeAnnotationBar = true
}))IncludeViewerCss 와 IncludeViewerScripts 은 필수 핵심 플래그입니다. 이를 포함하지 않고
Search 또는 Annotation Ribbon 예제를 게시하지 마십시오, Viewer 마운트와 docViewer 인스턴스도 포함해야 합니다.
ReferenceCss 와 ReferenceScripts 은 현재 라이선스가 해당 기능을 허용하지 않을 경우 선택적 모듈의 리소스를 생략합니다; 핵심 Viewer는 여전히 시작됩니다.
뷰어 초기화
클라이언트 측 위젯은 jQuery 플러그인입니다. 이것은 실제 초기화 옵션의 최소 집합입니다 (의사코드가 아닙니다):
let searchBar = null;
let annBar = null;
const objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: 'doconut', // 앞에 '/'가 없음
ResPath: 'doconut-res/images', // 앞에 '/'가 없음
onViewerReady: function () {
// 페이지가 표시됩니다; 여기에서 로딩 스피너를 숨겨도 안전합니다
},
// 리본이 존재할 때 주석 라이프사이클 이벤트를 임베드된 리본으로 전달합니다.
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: function (message) {
console.error('Doconut viewer error:', message);
}
});옵션 명명 규칙은 실제로 혼합되어 있습니다 — showThumbs, autoLoad, 그리고 pageZoom는 camelCase이며, FitType, BasePath, 그리고 ResPath는 PascalCase입니다. 일관된 규칙이 없으며, 대소문자를 잘못 지정하면 옵션이 조용히 무시됩니다 (위젯이 오류를 발생시키는 대신 기본값으로 되돌아갑니다).
다음 네 가지 세부 사항은 오류 메시지 없이 실패합니다:
BasePath에 앞 슬래시가 없습니다.'doconut'가/doconut/DocImage.axd를 요청하고;'/doconut'가//doconut/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와 함께 실패합니다.
전체 Viewer 패키지 조립
전체 뷰어 페이지는 다음 구성 요소들을 함께 설치합니다:
| 패키지 구성 요소 | 요구 사항 | 연결 방식 |
|---|---|---|
Viewer 리소스, 마운트, 및 objViewer | 필수 | 핵심 문서 렌더러 |
| Viewer 툴바 | 전체 페이지에 필수 | 호스트 마크업; 버튼은 동일한 objViewer를 호출합니다 |
| 검색 리본 | 옵션, 라이선스 모듈 | doconutSearchBar(...).attach(objViewer) |
| 주석 리본 | 옵션, 라이선스 모듈 | doconutAnnotationBar(...).attach(objViewer) |
주요 Viewer 툴바는 호스트 마크업이지만 Viewer와 함께 설치되며 절대로 독립된 컨트롤로 문서화되지 않아야 합니다. 이렇게 하면 레이아웃, 라벨, 아이콘 및 권한 규칙이 애플리케이션의 제어 하에 유지되면서 모든 버튼이 동일한 Viewer 인스턴스를 구동합니다:
<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.GotoPage(objViewer.TotalPages())">Last</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>
<button type="button" onclick="objViewer.FitType('height')">Fit height</button>
<button type="button" id="openSearch">Search</button>
<button type="button" id="openAnnotations">Annotations</button>
</nav>회전, 썸네일, 인쇄, 전체 화면, 레이아웃 및 버튼 상태 도우미는 동일한 objViewer를 호출하는 자체 툴바 스크립트에 포함되어야 합니다. Viewer.ReferenceScripts(...) 이후에 로드하고, 해당 <nav id="toolbar"> 마크업과 함께 유지하십시오.
다음 초기화 순서를 유지하십시오:
- Viewer와 라이선스 모듈에 대한 CSS를 출력합니다.
- Viewer 툴바, 검색/주석 마운트, 그리고 Viewer 마운트를 함께 렌더링합니다.
- Viewer와 라이선스 모듈에 대한 스크립트를 출력합니다.
- 호스트 애플리케이션의 자체 툴바 도우미 스크립트를 로드합니다.
docViewer를 초기화하고 결과objViewer를 유지합니다.- 각 라이선스된 검색 또는 주석 리본을 초기화합니다.
- 모든 리본에 대해
attach(objViewer)를 호출합니다. - 문서를 열고 Viewer 및 모듈 요청을 위한 토큰을 유지합니다.
분산 배포 환경에서는 추가 access 요청 값과 비동기 렌더 재시도 설정이 전송에 속하며, Viewer, 툴바 또는 리본이 조립되는 방식에 영향을 주지 않습니다.
서버 측 보호 장치는 중요합니다: 선택적 기능을 사용할 수 없을 때 해당 스크립트가 출력되지 않으며, 따라서 해당 jQuery 플러그인 함수가 존재하지 않습니다.
<script>
let token = '';
const refitViewer = () =>
requestAnimationFrame(() => objViewer.Refit());
@if (Viewer.IsSearchEnabled)
{
<text>
searchBar = $('#searchBarMount').doconutSearchBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token }),
onLayout: refitViewer
});
searchBar.attach(objViewer);
</text>
}
@if (Viewer.IsAnnotationEnabled)
{
<text>
annBar = $('#annBarMount').doconutAnnotationBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token }),
onLayout: refitViewer
});
annBar.attach(objViewer);
</text>
}
document.getElementById('openSearch').addEventListener('click', () => {
if (!searchBar) return;
searchBar.isOpen() ? searchBar.close() : searchBar.open();
});
document.getElementById('openAnnotations').addEventListener('click', () => {
if (!annBar) return;
annBar.isOpen() ? annBar.close() : annBar.open();
});
</script>두 임베디드 컴포넌트는 각각 자체 Ribbon DOM을 생성합니다. 검색은 Find, Options, Results 그룹을 포함합니다. 주석은 저작 도구, 스타일 제어, 저장 동작 및 옵션인 export/image 동작을 포함합니다. 이 바들은 open(), close(), reset(), 그리고 isOpen()를 노출하며; 생성 후 반드시 한 번 attach(objViewer)를 호출하십시오.
위 예시는 시작을 최소화하기 위해 옵션인 호스트 콜백 및 주석 export/image 엔드포인트를 생략했습니다. 전체 기능별 설정은 검색와 주석를 참조하고, 호스트 소유 Viewer 툴바를 스타일링하거나 교체하려면 맞춤 테마를 보십시오.
문서 열기
서버 측은 하나의 엔드포인트이며, 주입된 Viewer 서비스가 문서를 열고 세션 토큰을 반환합니다.
app.MapPost("/api/open", async (Viewer viewer) =>
{
// 토큰은 불투명합니다 — 위젯에 전달하고, 절대로 로그에 남기거나 영구 저장하지 마세요.
string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
return Results.Ok(new { token });
});클라이언트는 해당 토큰을 가져와 objViewer.View(token)와 함께 위젯에 전달합니다:
fetch('/api/open', { method: 'POST' })
.then(resp => resp.json())
.then(data => {
token = data.token;
objViewer.View(token);
});문서 닫기
사용자가 뷰어를 떠나거나 대체 문서를 열 때 objViewer.Close(true)를 호출합니다: 위젯을 초기화하고 서버에 닫기 요청을 보냅니다. 인수가 없는 objViewer.Close()는 위젯만 초기화합니다. 서버 주도 워크플로에서는 viewer.CloseDocument(token)가 즉시 캐시된 세션을 제거하고, 렌더링 엔진을 폐기하며, 보안 마커를 삭제하고, 토큰을 무효화합니다. 슬라이딩 만료는 결국 동일한 정리를 수행하지만, 큰 문서의 경우 명시적인 닫기가 권장됩니다.
완료된 요청 흐름은 다음과 같습니다:
AddDoconut + middleware
-> render CSS/scripts and mount div
-> initialize docViewer
-> OpenDocumentAsync
-> return opaque token
-> objViewer.View(token)
-> page/search/annotation requests
-> Close / CloseDocument토큰을 베어러 자격 증명처럼 취급하십시오: 절대로 로그에 남기지 말고, 영구 저장하지 말며, 위젯에만 전달하십시오. 이 토큰은 서버에서 활성 문서 세션을 식별하며, 세션이 만료되면 작동을 멈춥니다 — 새 토큰을 얻으려면 문서를 다시 열어야 합니다.
실행하기
wwwroot/files/Sample.pdf에 PDF를 배치하고, dotnet run를 실행한 뒤, 위젯을 호스팅하는 페이지를 엽니다. 첫 페이지가 뷰어에 렌더링되며, 왼쪽에 썸네일 패널이 표시됩니다. 표시되지 않을 경우, 문제 해결을 참고하십시오.
라이선스 없이 얻는 것
라이선스가 없다고 오류가 발생하지는 않습니다. 뷰어는 정상적으로 렌더링되지만, 모든 페이지에 평가용 워터마크가 표시됩니다. Doconut이 라이선스를 찾는 방법과 찾은 후 어떤 변화가 있는지 보려면 라이선스 설정을 참고하십시오.
이 페이지가 도움이 되었나요?