뷰어

주요 문서 뷰어 클래스

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

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

OpenDocumentAsync

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

오버로드사용 상황
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)자동 형식 감지와 해당 형식의 기본 설정을 사용하여 디스크에서 열기
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)형식별 렌더링 옵션(PdfConfig, WordConfig, …)이 필요할 때
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)문서가 디스크에 파일이 아닌 경우(업로드, 데이터베이스, 블롭). fileInfo 은 올바른 확장자를 포함해야 하며—형식 감지를 결정합니다
csharp
// 간단한 열기
string token = await viewer.OpenDocumentAsync(path);

// 포맷별 설정 및 옵션과 함께
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// 업로드에서
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

text
void CloseDocument(string token)

세션을 캐시에서 제거하고(문서 엔진을 즉시 폐기), 보안 마커를 삭제하며 접근 권한을 취소합니다. 선택 사항 — 슬라이딩 만료가 동일한 정리를 수행하지만, 큰 문서의 경우 권장됩니다.

GetPageCount

text
int GetPageCount(string token)

열린 세션의 총 페이지 수입니다. 토큰이 알 수 없거나 만료된 경우 InvalidOperationException (Document session not found. Please re-open document.) 를 발생시키고, 빈 토큰인 경우 ArgumentException 를 발생시킵니다.

GetPageDimensions

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

문서의 기본 렌더링 페이지 크기(100% 줌) — 코드에서 만든 주석을 위한 좌표 공간입니다. 호환성을 위해 page 가 허용되며, 결과는 문서 기본값입니다. 토큰이 알 수 없거나 만료된 경우 InvalidOperationException (Document session not found. Please re-open document.) 를 발생시키고, 빈 토큰인 경우 ArgumentException 를 발생시킵니다.

GetWorksheetNames

text
IReadOnlyList<string> GetWorksheetNames(string token)

열린 스프레드시트의 워크시트 이름을 워크북 순서대로 반환합니다. 열린 문서가 스프레드시트가 아닌 경우 빈 리스트를 반환합니다.

렌더링된 워크시트만 나열됩니다: 숨겨진 워크시트와 빈 워크시트는 제외되며, ExcelConfig.SheetNames 가 렌더링을 제한할 경우 해당 워크시트만 표시됩니다. 워크시트가 항상 한 페이지인 것은 아니며—매우 큰 워크시트는 여러 페이지에 걸쳐 렌더링됩니다. 토큰이 알 수 없거나 만료된 경우 InvalidOperationException (Document session not found. Please re-open document.) 를 발생시키고, 빈 토큰인 경우 ArgumentException 를 발생시킵니다.

26.9.0에 추가됨.

기능 플래그

멤버의미
bool IsSearchEnabled현재 라이선스가 부여하는 Search
bool IsAnnotationEnabled현재 라이선스가 부여하는 Annotation

Razor 뷰에서 이를 사용하면 서버가 실제로 제공할 때만 라이선스가 있는 리본을 렌더링합니다 — 참조: 빠른 시작.

문서 옵션

열 때마다 적용되는 형식에 독립적인 옵션 (namespace Doconut):

유형속성기본값설명
stringPassword""보호된 문서에 대한 비밀번호 (형식 구성에 자동으로 복사됩니다).
intImageResolution0구식. 호환성을 위해서만 유지됩니다 — 대신 형식 구성에 ImageResolution을 설정하십시오.
stringWatermark""렌더링된 페이지에 그려지는 맞춤 워터마크 텍스트. 형식 문자열: "^Text~Color~FontSize~FontName~Opacity~Angle", 예: "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60세션 슬라이딩 만료(분).
boolIsSecuredtrue현재 적용되지 않음 — 예약됨. 토큰 바인딩은 전역적으로 DoconutOptions.UnsafeMode에 의해 제어됩니다 (참조: 핵심 개념 → 세션 및 보안).

이 클래스는 일반적인 단일 호스트 보기 흐름을 벗어나도록 의도된 특수 속성도 노출합니다:

유형속성기본값설명
boolIsWebFarmfalse구식 — 효과 없음. 문서를 DistributedDocumentPublisher.PublishAsync(또는 IDistributedPublishQueue.EnqueueAsync)로 발행하고 대신 FileShareConfig.RootPath을 설정하십시오.
stringWebFarmPath""구식 — 효과 없음. 대신 FileShareConfig.RootPath을 사용하십시오.
boolEditModefalse별도로 배포되는 Editor 워크플로우를 위해 예약됨; 표준 뷰어를 위해 false을 남겨두십시오.

맞춤 워터마크

DocOptions.Watermark은 물결표(~) 6개로 구분된 필드를 사용합니다. 선택적인 선행 ^은 전체 코너 레이아웃을 요청합니다:

text
^Text~Color~FontSize~FontName~Opacity~Angle
csharp
string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });
필드예시의미
선행 ^^선택적인 전체 코너 레이아웃. 없으면 일반 워터마크 배치가 사용됩니다.
TextConfidential각 페이지에 렌더링되는 텍스트. 비어 있어서는 안 됩니다.
ColorRed그리기 레이어가 이해하는 명명된 색상.
FontSize24폰트 크기; 잘못된 숫자 입력은 렌더러 기본값으로 대체됩니다.
FontNameVerdana요청된 폰트 패밀리. 배포 환경에 설치되어 있는지 확인하십시오.
Opacity800에서 255 사이의 바이트 값. 성공적으로 파싱되어야 합니다.
Angle-45회전 각도(도); 잘못된 숫자 입력은 기본값으로 대체됩니다.

파서는 선택적인 ^ 뒤에 정확히 6개의 필드를 기대합니다. 잘못된 정의는 조용히 사라지는 대신 SDK의 가시적인 Invalid Watermark 대체값으로 교체됩니다.

라이선스 결정

라이선스 상태제공된 사용자 정의 값렌더링 결과
유효한 유료 뷰어 라이선스아니오깨끗한 페이지
유효한 유료 뷰어 라이선스예맞춤 워터마크
활성 임시/데모 기본 뷰어아니오깨끗한 기본 뷰어 페이지
활성 임시/데모 기본 뷰어예깨끗한 기본 뷰어 경로가 적용될 때 맞춤 워터마크
누락, 거부, 만료, 버전 불일치, 또는 도메인 무효 라이선스모두적용/평가 워터마크; 사용자 정의 값이 이를 대체하지 않음
평가 규칙에 따른 플러그인 렌더링모두평가 워터마크

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

주석 API

서버 측 주석 로드 및 내보내기. 전체 안내서는 Guides → Annotations에 있으며, 주요 인터페이스는 다음과 같습니다:

멤버목적
AnnotationManager GetAnnotationManager(string token)열려 있는 세션의 페이지 차원에 바인딩된 관리자
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)명시적 페이지 차원을 가진 관리자
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)세션에 독립적인 관리자
void LoadAnnotationData(string token, AnnotationManager manager)C#로 만든 주석을 세션에 로드
void LoadAnnotationData(string token, string annotationData)AnnotationManager.GetAnnotationData()이 반환한 인코딩된 페이지/Base64 봉투에서 주석을 로드
void LoadAnnotationXML(string token, XmlDocument annotationXml)XML에서 주석을 로드
XmlDocument GetAnnotationXML(string token)세션의 주석을 XML로 내보내기
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)주석이 삽입된 PDF
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)페이지당 하나의 PNG, 주석이 삽입되어 directoryPath에 기록(없으면 생성); 기록된 이미지 수를 반환
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)주석이 삽입된 페이지별 PNG의 ZIP

DICOM 메타데이터

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

DICOM 플러그인을 통해 열린 세션에 대한 DICOM 태그 메타데이터를 반환합니다; 비-DICOM 문서의 경우 null.

리소스 도우미 — ReferenceCss / ReferenceScripts

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

text
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 (주석 제한), EmitFeatureFlags (기본 true: 인라인 window.Doconut.features = { search, annotation, editor } 스크립트도 작성; 인라인 스크립트를 차단하는 Content-Security-Policy 하에서는 false 로 설정).

html
@inject Doconut.Viewer Viewer

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

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