빠른 시작

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

이 안내서는 빈 Program.cs에서 브라우저에 문서가 렌더링되는 ASP.NET Core 앱으로 전환합니다: 서버 등록, 전체 Viewer 패키지(Viewer 툴바, Viewer 마운트 및 선택적 검색/주석 리본), 자산 참조, 클라이언트 초기화, 문서 열기 및 실행.

호스트 애플리케이션은 netstandard2.1을 지원하는 런타임(.NET Core 3.0 이상)을 대상으로 해야 합니다.

서버 설정

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

이 설정은 기존 DocImage.axd 요청 형태를 유지하고 일치하는 브랜치에 문서 미들웨어를 마운트합니다. 기존 .NET Standard 애플리케이션을 앞으로 옮길 때 복사해야 할 구성이며, 클라이언트는 항상 동일한 URL을 호출하기 때문입니다:

csharp
builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // Doconut의 세션 검사를 활성화된 상태로 유지하세요
    options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // 세션 상태에 캐시가 필요합니다 (MVC/Razor Pages는 이미 하나를 추가합니다)
builder.Services.AddSession(options =>
{
    options.IdleTimeout        = TimeSpan.FromSeconds(3600);
    options.Cookie.HttpOnly    = true;
    options.Cookie.IsEssential = true;
});

// 일부 문서 형식에서 멀티바이트 인코딩에 필요합니다.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

app.UseStaticFiles();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();   // 문서 브랜치 이전에
app.MapWhen(
    context => context.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconut()는 이번 릴리스에서 옵션을 받지 않으며 — 모든 것이 AddDoconut()로 이동되었습니다. MiddlewarePath는 조정 값이며, 자체적으로 ASP.NET Core 브랜치를 매핑하지 않습니다. 위의 DocImage.axd 브랜치를 사용하면 클라이언트는 BasePath: '/'를 사용하고; 최소 설정에서 app.Map("/doconut", ...)를 사용하면 BasePath: 'doconut'를 사용합니다. ResourcesPath는 /doconut-res에서 임베디드 번들을 제공하며, 따라서 위젯의 이미지 리소스 경로는 ResPath: 'doconut-res/images'입니다.

페이지에 뷰어 추가

Viewer는 페이지에 필수적인 핵심 요소입니다. 그 렌더링 표면은 두 개의 중첩된 div를 사용합니다:

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

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

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- 뷰어 탐색, 확대/축소, 검색 및 주석 버튼 -->
</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는 필수 코어 플래그입니다. 이들, Viewer 마운트 및 docViewer 인스턴스 없이 검색 또는 주석 리본 예제를 절대로 게시하지 마세요. ReferenceCss와 ReferenceScripts는 현재 라이선스가 해당 기능을 허용하지 않을 경우 선택적 모듈의 리소스를 생략합니다; 코어 Viewer는 여전히 시작됩니다.

이 호출들은 수동으로 복사한 스크립트 파일을 대체합니다. 애플리케이션이 여전히 자체 docViewer.js, documentLinks.js, 또는 docViewer.UI.js를 로드한다면, 페이지가 내보낸 리소스로 정상 동작할 때 해당 태그들을 제거하세요 — 자세한 내용은 마이그레이션 가이드를 참조하세요.

뷰어 초기화

클라이언트 측 위젯은 jQuery 플러그인입니다. 이것은 실제 초기화 옵션의 최소 집합이며 (의사코드가 아님):

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // DocImage.axd 브랜치; 'doconut'와 app.Map("/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);
    }
});

네 가지 세부 사항이 이 페이지가 전혀 작동하는지를 결정합니다:

  • 콜백은 옵션입니다. onViewerReady, onViewerBusy, onCopy, 및 onAutoLoadStatus는 옵션 객체에 전달됩니다. 이전 뷰어는 컨테이너 ID에서 전역 함수 이름을 유도하고 이를 호출했지만, 이 뷰어는 그렇지 않습니다. 전역 함수로만 선언된 핸들러는 절대 실행되지 않으며, 아무것도 보고되지 않습니다.
  • ResPath는 리소스 접두사를 가리킵니다, 애플리케이션 루트가 아닙니다. 기본 ResourcesPath를 사용하면 해당 값은 doconut-res/images입니다. ResourcesPath를 변경했다면 자체 접두사를 사용하세요. 아이콘은 리소스 루트 아래 한 폴더에 위치합니다: 'doconut-res'를 사용하면 모든 아이콘이 404를 반환하지만 문서 자체는 여전히 렌더링됩니다.
  • BasePath에는 선행 슬래시가 없습니다 사이트 루트 값 '/' 외에는. 'doconut'는 /doconut/DocImage.axd를 요청하고, '/doconut'는 //doconut/DocImage.axd를 생성합니다. 브라우저는 이를 다른 호스트에 대한 요청으로 해석합니다.
  • 뷰어를 유지하고, View를 별도로 호출하세요. docViewer(...)는 Zoom, Next 및 FitType를 포함하는 객체를 반환합니다; View(...)는 다른 것을 반환합니다. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)는 문서를 렌더링하고, 첫 번째 툴바 클릭 시 objViewer.Zoom is not a function와 함께 실패합니다.

이 모든 경우가 조용히 실패합니다 — 문제 해결 및 마이그레이션 가이드를 참조하세요.

옵션의 대소문자 표기는 실제로 혼합되어 있습니다 — showThumbs, autoLoad, pageZoom는 camelCase이며, FitType, BasePath, ResPath는 PascalCase입니다. 일관된 규칙이 없으며, 대소문자를 잘못 지정하면 옵션이 조용히 무시됩니다 (위젯이 오류를 발생시키는 대신 기본값으로 돌아갑니다).

전체 Viewer 패키지 조립

전체 Viewer 페이지는 다음 구성 요소들을 함께 설치합니다:

패키지 구성 요소요구 사항연결 방식
Viewer 리소스, 마운트 및 objViewer필수핵심 문서 렌더러
Viewer 툴바전체 페이지에 필요호스트 마크업; 버튼은 동일한 objViewer 를 호출합니다
검색 리본선택 사항, 라이선스 모듈doconutSearchBar(...).attach(objViewer)
주석 리본선택 사항, 라이선스 모듈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>

다음 초기화 순서를 유지하십시오:

  1. Viewer 및 라이선스 모듈용 CSS를 출력합니다.
  2. Viewer 툴바, 검색/주석 마운트 및 Viewer 마운트를 함께 렌더링합니다.
  3. Viewer 및 라이선스 모듈용 스크립트를 출력합니다.
  4. 호스트 애플리케이션의 자체 툴바 헬퍼 스크립트를 로드합니다.
  5. docViewer 를 초기화하고 결과인 objViewer 를 유지합니다.
  6. 각 라이선스 검색 또는 주석 리본을 초기화합니다.
  7. 모든 리본에 대해 attach(objViewer) 를 호출합니다.
  8. 문서를 열고 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을 생성합니다. 검색에는 찾기, 옵션 및 결과 그룹이 포함됩니다. 주석에는 저작 도구, 스타일 제어, 저장 동작 및 선택적 내보내기/이미지 동작이 포함됩니다. 이 바들은 open(), close(), reset(), 그리고 isOpen() 를 노출하며; 생성 후 한 번씩 반드시 attach(objViewer) 를 호출하십시오.

위 예제는 시작을 최소화하기 위해 선택적 호스트 콜백 및 주석 내보내기/이미지 엔드포인트를 생략합니다. 전체 기능별 설정을 보려면 검색 및 주석을 참고하고, 호스트 소유 Viewer 툴바를 스타일링하거나 교체하려면 맞춤 테마를 확인하십시오.

문서 열기

서버 측은 하나의 엔드포인트이며, 주입된 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);
    });

첫 번째 열기 전에 준비할 것이 없습니다. 애플리케이션을 이어서 사용하고 있다면, 모든 InitCache() 호출과 이를 보호하는 플래그를 삭제하십시오 — 해당 메서드는 더 이상 존재하지 않습니다.

문서 닫기

사용자가 뷰어를 떠나거나 교체 문서를 열 때 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

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

실행하기

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

라이선스 없이 얻는 것

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

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