뷰어

Viewer (namespace Doconut)는 MVC 컨트롤러, Web Forms 페이지 및 핸들러에서 문서를 여는 공개 진입점입니다. DoconutHost.Initialize에 의해 구성된 일시적 서비스이며, 사용 위치에서 다음과 같이 해결합니다:

var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

DoconutHost.Initialize가 실행된 후에는 new Viewer()도 동작합니다 — 동일한 서비스를 해결하므로 클래식 패키지에서 마이그레이션된 코드가 그대로 컴파일됩니다. Initialize 이전에 호출하면 InvalidOperationException이 발생합니다.

Viewer는 요청당 문서 상태를 보유하지 않으며 의도적으로 IDisposable을 구현하지 않습니다: 문서 세션은 독립적으로 존재하므로 Viewer를 폐기해도 열린 문서가 닫히지 않습니다 (자세한 내용은 뷰어 작동 방식 참고).

OpenDocumentAsync (문서 비동기 열기)

문서를 열고 위젯이 이후 모든 요청에 사용할 세션 토큰을 반환합니다. UnsafeMode가 false(기본값)인 경우 토큰은 현재 요청의 ASP.NET 세션에 부여됩니다 — 세션 상태가 있는 요청에서 호출하십시오 (세션 및 보안 참고).

// 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 (HttpPostedFileBase in MVC; HttpPostedFile in Web Forms)
using (var ms = new MemoryStream())
{
    await file.InputStream.CopyToAsync(ms);
    ms.Position = 0;
    token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}

처리해야 할 예외:

• LicenseException — 라이선스가 발견되었지만 거부된 경우(메시지에 이유가 포함) 또는 형식에 필요한 플러그인 기능이 라이선스에 포함되지 않은 경우.
• FormatNotSupportedException — 파일 확장자를 처리할 수 있는 뷰어가 없는 경우.
• InvalidDataException — 내용이 손상되었거나 확장자와 일치하지 않는 경우.

OpenDocument (synchronous) (문서 동기식 열기)

Web Forms 코드 비하인드 및 비동기 페이지를 사용하지 않는 기타 코드용:

string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)

각 메서드는 토큰을 반환하고 viewer.Token에도 저장합니다. fileName에는 올바른 확장자가 포함되어야 합니다. 이러한 래퍼는 Web Forms 페이지에서 안전하게 호출할 수 있습니다: 열기 경로가 ASP.NET 요청 컨텍스트에서 재개되지 않으므로 대기 시 교착 상태가 발생하지 않습니다. 모든 비동기 Doconut API가 동일한 보장을 제공하는 것은 아니며, 자세한 내용은 변환기 플러그인 섹션의 Web Forms 부분을 참고하십시오.

CloseDocument

void CloseDocument(string token)

세션을 제거하고(문서 엔진을 즉시 해제), 현재 요청의 ASP.NET 세션에서 토큰의 권한을 제거하며 토큰을 폐기합니다. 선택 사항 — 슬라이딩 만료도 동일한 정리를 수행하지만, 큰 문서의 경우 권장됩니다.

Session queries

토큰이 알 수 없거나 만료된 경우 각각 예외를 발생합니다.

DocOptions

Per-open, format-independent options (namespace Doconut):

Custom watermark

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개의 필드를 기대합니다. 잘못된 정의는 보이지 않게 사라지는 대신 눈에 보이는 Invalid Watermark 텍스트로 대체됩니다.

License decision

같은 결정이 제공되는 페이지와 주석 내보내기에 모두 적용됩니다. 사용자 정의 워터마크는 라이선스가 있는 애플리케이션의 기능이며, 평가용 워터마크를 대체하는 방법이 아닙니다.

Annotations API

서버 측 주석 로드 및 내보내기. 안내서는 주석 에 있습니다.

DICOM 메타데이터

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

이 패키지에서는 항상 null을 반환하며, 위젯의 메타데이터 요청은 501 Not Implemented 응답을 반환합니다: DICOM 태그를 읽는 기능은 .NET Framework에서 제공되지 않습니다. DICOM 렌더링 — 페이지, 프레임 및 애니메이션 — 은 정상적으로 동작합니다. DICOM 플러그인을 참고하세요.

리소스 도우미 — ReferenceCss / ReferenceScripts

리소스 모듈이 DoconutOptions.ResourcesPath 아래에서 제공하는 리소스에 대한 <link>와 <script> 태그를 종속성 순서대로 출력합니다. 라이선스로 제한된 기능(검색, 주석)의 파일은 라이선스가 해당 기능을 허용할 때만 출력됩니다.

string ReferenceCss(CssConfig? config = null)       // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // 라이선스 상태, 리본 초기화 코드 보호용
bool IsAnnotationEnabled { get; }

CssConfig 플래그: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (검색 제한), IncludeAnnotationCss (주석 제한).

ScriptConfig 플래그: IncludeJQuery (다른 모든 스크립트에 필요), IncludeBootstrap, IncludeViewerScripts (핵심 뷰어 스크립트), IncludeSearchScripts 및 IncludeSearchBar (검색 제한), IncludeAnnotationScripts 및 IncludeAnnotationBar (주석 제한).

두 메서드 모두 HTML을 반환합니다: MVC 5에서는 @Html.Raw(...) 로, 컨트롤러에서 생성하고 뷰에서는 @inject 를 사용하지 않습니다. Web Forms에서는 <%= %> 로 출력합니다. 빠른 시작에서 두 가지 방법을 확인할 수 있습니다.

RenderViewer

string RenderViewer(string elementId, string token, ViewerConfig? config = null)

해당 elementId를 가진 요소에 위젯을 초기화하고 문서를 표시하는 <script> 블록을 반환합니다: docViewer({...}) 가 ViewerConfig(기본값: BasePath: '/', ResPath: 'doconut-res/images') 로부터 생성된 뒤 .View(token)을 호출합니다. 뷰어 스크립트 뒤에 작성하십시오. 생성된 스크립트는 뷰어 객체에 대한 참조를 유지하지 않으므로, 자체 툴바를 가진 페이지에서는 위젯을 직접 초기화해야 합니다. ViewerConfig을 참고하세요.

웹 팜

string? AccessToken 은 분산 모드가 활성화되고 UnsafeMode 가 false 일 때 가장 최근에 열린 세션에서 발급된 서명된 티켓을 보관합니다; 단일 서버 환경에서는 null 입니다. 위젯에 토큰과 함께 전달하려면 objViewer.View(token, access) 를 사용하십시오.