뷰어
주요 문서 뷰어 클래스
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 은 올바른 확장자를 포함해야 하며—형식 감지를 결정합니다 |
// 간단한 열기
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
void CloseDocument(string token)세션을 캐시에서 제거하고(문서 엔진을 즉시 폐기), 보안 마커를 삭제하며 접근 권한을 취소합니다. 선택 사항 — 슬라이딩 만료가 동일한 정리를 수행하지만, 큰 문서의 경우 권장됩니다.
GetPageCount
int GetPageCount(string token)열린 세션의 총 페이지 수입니다. 토큰이 알 수 없거나 만료된 경우 InvalidOperationException (Document session not found. Please re-open document.) 를 발생시키고, 빈 토큰인 경우 ArgumentException 를 발생시킵니다.
GetPageDimensions
(int Width, int Height) GetPageDimensions(string token, int page = 1)문서의 기본 렌더링 페이지 크기(100% 줌) — 코드에서 만든 주석을 위한 좌표 공간입니다. 호환성을 위해 page 가 허용되며, 결과는 문서 기본값입니다. 토큰이 알 수 없거나 만료된 경우 InvalidOperationException (Document session not found. Please re-open document.) 를 발생시키고, 빈 토큰인 경우 ArgumentException 를 발생시킵니다.
GetWorksheetNames
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):
| 유형 | 속성 | 기본값 | 설명 |
|---|---|---|---|
string | Password | "" | 보호된 문서에 대한 비밀번호 (형식 구성에 자동으로 복사됩니다). |
int | ImageResolution | 0 | 구식. 호환성을 위해서만 유지됩니다 — 대신 형식 구성에 ImageResolution을 설정하십시오. |
string | Watermark | "" | 렌더링된 페이지에 그려지는 맞춤 워터마크 텍스트. 형식 문자열: "^Text~Color~FontSize~FontName~Opacity~Angle", 예: "^Sample Copy~Red~24~Verdana~80~-45". |
int | TimeOut | 60 | 세션 슬라이딩 만료(분). |
bool | IsSecured | true | 현재 적용되지 않음 — 예약됨. 토큰 바인딩은 전역적으로 DoconutOptions.UnsafeMode에 의해 제어됩니다 (참조: 핵심 개념 → 세션 및 보안). |
이 클래스는 일반적인 단일 호스트 보기 흐름을 벗어나도록 의도된 특수 속성도 노출합니다:
| 유형 | 속성 | 기본값 | 설명 |
|---|---|---|---|
bool | IsWebFarm | false | 구식 — 효과 없음. 문서를 DistributedDocumentPublisher.PublishAsync(또는 IDistributedPublishQueue.EnqueueAsync)로 발행하고 대신 FileShareConfig.RootPath을 설정하십시오. |
string | WebFarmPath | "" | 구식 — 효과 없음. 대신 FileShareConfig.RootPath을 사용하십시오. |
bool | EditMode | false | 별도로 배포되는 Editor 워크플로우를 위해 예약됨; 표준 뷰어를 위해 false을 남겨두십시오. |
맞춤 워터마크
DocOptions.Watermark은 물결표(~) 6개로 구분된 필드를 사용합니다. 선택적인 선행 ^은 전체 코너 레이아웃을 요청합니다:
^Text~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| 필드 | 예시 | 의미 |
|---|---|---|
선행 ^ | ^ | 선택적인 전체 코너 레이아웃. 없으면 일반 워터마크 배치가 사용됩니다. |
| Text | Confidential | 각 페이지에 렌더링되는 텍스트. 비어 있어서는 안 됩니다. |
| Color | Red | 그리기 레이어가 이해하는 명명된 색상. |
| FontSize | 24 | 폰트 크기; 잘못된 숫자 입력은 렌더러 기본값으로 대체됩니다. |
| FontName | Verdana | 요청된 폰트 패밀리. 배포 환경에 설치되어 있는지 확인하십시오. |
| Opacity | 80 | 0에서 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 메타데이터
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)DICOM 플러그인을 통해 열린 세션에 대한 DICOM 태그 메타데이터를 반환합니다; 비-DICOM 문서의 경우 null.
리소스 도우미 — 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 (주석 제한), EmitFeatureFlags (기본 true: 인라인 window.Doconut.features = { search, annotation, editor } 스크립트도 작성; 인라인 스크립트를 차단하는 Content-Security-Policy 하에서는 false 로 설정).
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))이 페이지가 도움이 되었나요?