뷰어

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

이전 .NET Standard 라이브러리는 메모리 캐시, HTTP 컨텍스트 접근자 및 하나 이상의 라이선스 경로를 받는 공개 생성자를 제공했습니다. 해당 생성자는 사라졌으며, 서비스 그래프가 이러한 종속성을 제공합니다.

Viewer는 요청당 상태를 보유하지 않으며 의도적으로 IDisposable을 구현하지 않습니다: 문서 세션은 세션 캐시에서 독립적으로 살아가기 때문에 서비스를 폐기해도 열려 있는 문서를 해제할 수 없습니다 (Core Concepts → How the Viewer Works 참조).

OpenDocumentAsync

문서를 열고 클라이언트 위젯이 이후 모든 요청에 사용하는 세션 토큰을 반환합니다. 모든 열기는 비동기이며 동기 OpenDocument는 존재하지 않습니다.

// 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)

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

Capability flags

Razor 뷰에서 이 플래그를 사용해 서버가 실제로 제공할 때만 라이선스가 적용된 리본을 렌더링하세요 — 빠른 시작 참고.

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

파서는 선택적인 ^ 뒤에 정확히 6개의 필드가 있어야 합니다. 정의가 잘못되면 SDK의 가시적인 Invalid Watermark 대체값으로 교체되며, 조용히 사라지지는 않습니다.

라이선스 결정

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

주석 API

서버 측 주석 로드 및 내보내기. 전체 가이드는 Guides → Annotations에 있으며, 핵심은 다음과 같습니다:

이 메서드들은 모두 세션 토큰을 필요로 합니다. 이전 라이브러리의 세션 없이 사용할 수 있던 GetAnnotationManager(pageWidth, pageHeight) 형태는 세션 외부에서 주석을 만들 때는 여전히 사용할 수 있지만, 로드할 때는 토큰이 필요합니다.

DICOM 메타데이터

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

이 메서드는 API 정렬을 위해 존재하지만, 이 패키지는 기술적인 DICOM 태그를 제공할 수 없습니다. 메타데이터 리더는 .NET 8 빌드만 포함하고 있기 때문입니다. 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 (검색 기반), IncludeAnnotationCss (주석 기반).

ScriptConfig 플래그: IncludeJQuery (모든 다른 플래그가 필요함), IncludeBootstrap, IncludeViewerScripts (핵심: docViewer.js + splitter + links), IncludeSearchScripts 및 IncludeSearchBar (검색 기반), IncludeAnnotationScripts 및 IncludeAnnotationBar (주석 기반).

@inject Doconut.Viewer Viewer

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

이 헬퍼들은 브라우저 리소스를 제공하는 권장 방법입니다. docViewer.js, documentLinks.js, docViewer.UI.js를 wwwroot에 복사해 둔 애플리케이션은, 페이지가 출력된 태그에서 렌더링될 때 해당 복사본을 제거해야 합니다.