뷰어

Viewer (namespace Doconut) 은 Razor 페이지, MVC 컨트롤러, Blazor 컴포넌트 또는 최소 API에서 문서를 열기 위한 공개 진입점입니다. sealed이며 AddDoconut() 로 transient 서비스로 등록되고 생성자 주입을 통해 해결됩니다 — 직접 인스턴스를 만들지 마세요.

Viewer 는 요청당 상태를 보유하지 않으며 의도적으로 IDisposable 을 구현하지 않습니다: 문서 세션은 세션 캐시에서 독립적으로 존재하므로 서비스 해제 시 열린 문서가 해제될 수 없습니다(코어 개념 → Viewer 작동 방식 참조).

OpenDocumentAsync 메서드

문서를 열고 클라이언트 위젯이 이후 모든 요청에 사용할 세션 토큰을 반환합니다.

// Simple open
string token = await viewer.OpenDocumentAsync(path);

// With per-format config and options
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// From an upload
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

처리해야 할 예외:

• LicenseException — 발견된 라이선스가 거부될 때(메시지에 거부 사유가 포함됨) 또는 형식에 더 이상 허용되지 않은 플러그인 기능이 필요할 때. 거부 메시지 없이 캘린더가 만료되면 예외를 발생시키는 대신 워터마크가 적용된 렌더링으로 낮아집니다.
• FormatNotSupportedException — Document format '<extension>' is not supported.
• InvalidDataException — 파일 내용이 손상되었거나 확장자와 일치하지 않을 때.

CloseDocument 메서드

void CloseDocument(string token)

세션을 캐시에서 제거하고(문서 엔진을 즉시 해제), 보안 마커를 삭제하며 접근 권한을 취소합니다. 선택 사항이지만 슬라이딩 만료도 동일한 정리를 수행하므로 대용량 문서에 권장됩니다.

GetPageCount 메서드

int GetPageCount(string token)

열린 세션의 전체 페이지 수를 반환합니다. 토큰이 알 수 없거나 만료된 경우 예외가 발생합니다.

DocOptions 클래스

열기 시점에 사용되는 형식에 독립적인 옵션 (namespace Doconut):

클래스는 일반 단일 호스트 뷰잉 흐름 밖에서 의도적으로 제공되는 특수 속성도 포함합니다:

사용자 지정 워터마크

DocOptions.Watermark 은 6개의 틸드(~) 구분 필드를 사용합니다. 선택적 선행 ^ 는 모든 모서리 레이아웃을 요청합니다:

^Text~Color~FontSize~FontName~Opacity~Angle

string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });

파서는 선택적 ^ 뒤에 정확히 여섯 개의 필드를 기대합니다. 정의가 잘못되면 SDK의 가시적인 Invalid Watermark 대체 텍스트가 사용되며, 조용히 사라지지는 않습니다.

라이선스 결정

동일한 결정이 제공되는 페이지 이미지와 주석 내보내기에 적용됩니다. 애니메이션 GIF 출력은 프레임마다 워터마크가 찍힙니다. 따라서 사용자 지정 워터마크는 평가 워터마크를 대체하거나 억제하는 것이 아니라, 라이선스가 있는 애플리케이션 기능입니다.

주석 API

서버 측 주석 로드 및 내보내기. 전체 가이드는 Guides → Annotations 에서 확인할 수 있습니다; 주요 인터페이스는 다음과 같습니다:

DICOM 메타데이터

Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

이 메서드는 API 정렬을 위해 존재하지만, .NET 6 DICOM 뷰어는 기술 태그를 제공할 수 없습니다. DICOM 및 비 DICOM 세션 모두 null 을 반환하며, DICOM 세션에서는 플랫폼 제한을 설명하는 일회성 경고가 기록됩니다. 페이지, 프레임 및 애니메이션 렌더링은 계속 지원됩니다.

리소스 도우미 — ReferenceCss / ReferenceScripts

UseDoconutResources() 로 제공되는 임베디드 리소스에 대한 <link>/<script> 태그를 올바른 의존 순서대로 출력합니다. 검색 및 주석과 같은 라이선스 제한 기능에 대한 번들은 라이선스가 활성화된 경우에만 출력되어 클라이언트 UI 가 서버 동작과 일치하도록 유지합니다.

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

CssConfig 플래그: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search‑gated), IncludeAnnotationCss (annotation‑gated).

ScriptConfig 플래그: IncludeJQuery (required by all others), IncludeBootstrap, IncludeViewerScripts (core: docViewer.js + splitter + links), IncludeSearchScripts 및 IncludeSearchBar (search‑gated), IncludeAnnotationScripts 및 IncludeAnnotationBar (annotation‑gated).

@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))