뷰어
주 문서 뷰어 클래스
Viewer (namespace Doconut) 은 Razor 페이지, MVC 컨트롤러, Blazor 컴포넌트 또는 최소 API에서 문서를 여는 공개 진입점입니다. 이는 봉인된이며, AddDoconut() 에 의해 일시적인 서비스로 등록되고 생성자 주입을 통해 해결됩니다 — 직접 인스턴스를 생성하지 마세요.
Viewer 은 요청당 상태를 보유하지 않으며 의도적으로 IDisposable 를 구현하지 않습니다: 문서 세션은 세션 캐시에서 독립적으로 존재하므로 서비스를 폐기해도 열린 문서를 해제할 수 없습니다 (핵심 개념 → 뷰어 작동 방식 참조).
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 뷰에서 이를 사용하여 서버가 실제로 제공할 때만 라이선스가 있는 리본을 렌더링합니다 — 빠른 시작을 참조하십시오.
문서 옵션
열기당, 형식에 독립적인 옵션 (네임스페이스 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 | 별도로 배포되는 편집기 워크플로를 위해 예약됨; 표준 뷰어를 위해 false을 남겨두십시오. |
사용자 지정 워터마크
DocOptions.Watermark은 여섯 개의 물결표(~) 구분 필드를 사용합니다. 선택적인 선행 ^은 모든 모서리 레이아웃을 요청합니다:
^Text~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| 필드 | 예시 | 의미 |
|---|---|---|
선행 ^ | ^ | 선택적인 모든 모서리 레이아웃. 이것이 없으면 일반 워터마크 배치가 사용됩니다. |
| 텍스트 | Confidential | 각 페이지에 렌더링되는 텍스트. 비어 있어서는 안 됩니다. |
| 색상 | Red | 그리기 레이어가 이해하는 명명된 색상. |
| 글꼴 크기 | 24 | 글꼴 크기; 잘못된 숫자 입력은 렌더러 기본값으로 대체됩니다. |
| 글꼴 이름 | Verdana | 요청된 글꼴 패밀리. 배포 환경에 설치되어 있는지 확인하십시오. |
| 불투명도 | 80 | 0에서 255 사이의 바이트 값. 성공적으로 파싱되어야 합니다. |
| 각도 | -45 | 도 단위 회전 각도; 잘못된 숫자 입력은 기본값으로 대체됩니다. |
파서는 선택적인 ^ 뒤에 정확히 여섯 개의 필드를 기대합니다. 잘못된 정의는 조용히 사라지는 대신 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)이 메서드는 API 정렬을 위해 존재하지만, .NET 6 DICOM 뷰어는 기술 태그를 제공할 수 없습니다. DICOM 및 비 DICOM 세션에 대해 null을 반환합니다; DICOM 세션에서는 플랫폼 제한을 설명하는 일회성 경고를 기록합니다. 페이지, 프레임 및 애니메이션 렌더링은 여전히 지원됩니다.
리소스 도우미 — ReferenceCss / ReferenceScripts
임베드된 리소스를 제공하는 UseDoconutResources()에 대해 올바른 의존 순서로 <link>/<script> 태그를 출력합니다. 검색 및 주석과 같은 라이선스 제한 기능을 위한 번들은 라이선스가 활성화된 경우에만 출력되어, 클라이언트 UI가 서버 동작과 일치하도록 유지합니다.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + 뷰어 + 검색 + 주석
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 }))이 페이지가 도움이 되었나요?