빠른 시작

몇 분 안에 첫 번째 문서를 렌더링하세요

이 안내서는 빈 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을 등록했습니까? 다음 섹션으로 건너뛰세요.

csharp
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());

프로덕션 스타일 경로 레이아웃을 위해, 문서 미들웨어를 명시적인 분기로 매핑하고 네 개의 경로 설정을 정렬된 상태로 유지합니다:

csharp
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 를 사용합니다:

html
<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

툴바, 모듈 마운트 및 Viewer 표면을 하나의 페이지 구성으로 취급하십시오. 검색 및 주석은 선택적 마운트에 임베디드 리본을 삽입하지만, 해당 모듈은 절대 독립적으로 존재하지 않으며 항상 같은 페이지의 Viewer에 연결됩니다. 다음 순서를 사용하십시오:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Viewer 탐색, 확대/축소, Search 및 Annotation 버튼 -->
</nav>

<div id="searchBarMount"></div>
<div id="annBarMount"></div>

<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

뷰어 자산 참조

Razor 뷰에서 주입된 Viewer 서비스는 의존 순서대로 뷰어의 <link> 와 <script> 태그를 출력합니다 — 위젯은 jQuery 플러그인이므로, jQuery를 뷰어 스크립트보다 먼저 로드해야 합니다:

html
@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
@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 플러그인입니다. 이것은 실제 초기화 옵션의 최소 집합이며(의사코드가 아님):

javascript
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를 호출합니다
Search 리본옵션, 라이선스 모듈doconutSearchBar(...).attach(objViewer)
Annotation 리본옵션, 라이선스 모듈doconutAnnotationBar(...).attach(objViewer)

주요 Viewer 툴바는 호스트 마크업이지만 Viewer와 함께 설치되며 절대로 독립된 컨트롤로 문서화되지 않아야 합니다. 이렇게 하면 레이아웃, 라벨, 아이콘 및 권한 규칙이 애플리케이션의 제어 하에 유지되면서 모든 버튼이 동일한 Viewer 인스턴스를 구동합니다:

html
<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"> 마크업과 함께 유지하세요.

다음 초기화 순서를 유지하세요:

  1. Viewer와 라이선스 모듈용 CSS를 출력합니다.
  2. Viewer 툴바, Search/Annotation 마운트, 그리고 Viewer 마운트를 함께 렌더링합니다.
  3. Viewer와 라이선스 모듈용 스크립트를 출력합니다.
  4. 호스트 애플리케이션의 자체 툴바 헬퍼 스크립트를 로드합니다.
  5. docViewer를 초기화하고 결과로 얻은 objViewer를 유지합니다.
  6. 각 라이선스된 Search 또는 Annotation 리본을 초기화합니다.
  7. 모든 리본에 대해 attach(objViewer)를 호출합니다.
  8. 문서를 열고 Viewer 및 모듈 요청에 사용할 토큰을 보관합니다.

분산 배포 환경에서는 추가 access 요청 값과 비동기 렌더링 재시도 설정이 전송 계층에 속하며, Viewer, 툴바 또는 리본이 조립되는 방식에는 영향을 주지 않습니다.

서버 측 가드가 중요합니다: 선택적 기능을 사용할 수 없을 경우 해당 스크립트가 출력되지 않으며, 따라서 해당 jQuery 플러그인 함수도 존재하지 않게 됩니다.

html
<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을 생성합니다. Search는 Find, Options, Results 그룹을 포함하고, Annotation은 저작 도구, 스타일 제어, 저장 동작 및 옵션인 export/image 동작을 포함합니다. 각 바는 open(), close(), reset(), isOpen()를 노출하며; 생성 후 반드시 한 번 attach(objViewer)를 호출하세요.

위 예시는 시작을 최소화하기 위해 옵션인 호스트 콜백 및 Annotation export/image 엔드포인트를 생략했습니다. 전체 기능별 설정을 보려면 Search와 Annotations를 확인하고, 호스트가 소유한 Viewer 툴바를 스타일링하거나 교체하려면 Custom Themes를 참고하세요.

문서 열기

서버 측은 하나의 엔드포인트이며, 주입된 Viewer 서비스가 문서를 열고 세션 토큰을 반환합니다.

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // 토큰은 불투명합니다 — 위젯에 전달하고, 절대로 로그에 남기거나 영구 저장하지 마세요.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

클라이언트는 해당 토큰을 가져와 objViewer.View(token)와 함께 위젯에 전달합니다:

javascript
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)가 즉시 캐시된 세션을 제거하고, 렌더링 엔진을 폐기하며, 보안 마커를 삭제하고, 토큰을 무효화합니다. 슬라이딩 만료는 결국 동일한 정리를 수행하지만, 큰 문서의 경우 명시적인 닫기가 권장됩니다.

완료된 요청 흐름은 다음과 같습니다:

text
AddDoconut + middleware
    -> render CSS/scripts and mount div
    -> initialize docViewer
    -> OpenDocumentAsync
    -> return opaque token
    -> objViewer.View(token)
    -> page/search/annotation requests
    -> Close / CloseDocument

토큰을 베어러 자격 증명처럼 취급하십시오: 절대로 로그에 남기지 말고, 영구 저장하지 말며, 위젯에만 전달하십시오. 이 토큰은 서버의 실시간 문서 세션을 식별하고 해당 세션이 만료되면 작동을 멈춥니다 — 새 토큰을 얻으려면 문서를 다시 열어야 합니다.

실행하기

PDF를 wwwroot/files/Sample.pdf에 배치하고, dotnet run를 실행한 뒤 위젯을 호스팅하는 페이지를 엽니다. 첫 페이지가 뷰어에 렌더링되며 왼쪽에 썸네일 패널이 표시됩니다. 표시되지 않을 경우, 문제 해결을 참조하십시오.

라이선스 없이 얻는 것

라이선스가 없다고 오류가 발생하지는 않습니다. 뷰어는 정상적으로 렌더링되지만 모든 페이지에 평가용 워터마크가 표시됩니다. Doconut이 라이선스를 찾는 방법과 찾은 후 어떤 변화가 있는지 보려면 라이선스 설정을 확인하십시오.

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