뷰어
주요 문서 뷰어 클래스
Viewer (namespace Doconut) 은 Razor 페이지, MVC 컨트롤러, Blazor 컴포넌트 또는 최소 API에서 문서를 열기 위한 공개 진입점입니다. 이는 sealed이며, AddDoconut() 에 의해 transient 서비스로 등록되고 생성자 주입을 통해 해결됩니다 — 직접 인스턴스를 만들지 마세요.
이전 .NET Standard 라이브러리는 메모리 캐시, HTTP 컨텍스트 액세서, 그리고 하나 이상의 라이선스 경로를 받는 공개 생성자를 제공했습니다. 해당 생성자는 사라졌으며, 서비스 그래프가 이러한 종속성을 제공합니다.
Viewer 은 요청당 상태를 보유하지 않으며 의도적으로 IDisposable 를 구현하지 않습니다: 문서 세션은 세션 캐시에서 독립적으로 존재하므로 서비스를 해제해도 열린 문서를 종료할 수 없습니다 (Core Concepts → How the Viewer Works 를 참조).
OpenDocumentAsync
문서를 열고 클라이언트 위젯이 이후 모든 요청에 사용하는 세션 토큰을 반환합니다. 모든 열기는 비동기식이며 — 동기식 OpenDocument 은 존재하지 않습니다.
| Overload | Use when |
|---|---|
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 를 발생시킵니다.
워크시트 이름 가져오기
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 에 의해 제어됩니다 (Core Concepts → Sessions & Security 참조). |
이 클래스는 일반적인 단일 호스트 보기 흐름 밖에 의도적으로 배치된 특수 속성도 노출합니다:
| 형식 | 속성 | 기본값 | 설명 |
|---|---|---|---|
bool | IsWebFarm | false | 구식 — 효과 없음. 문서를 DistributedDocumentPublisher.PublishAsync (또는 IDistributedPublishQueue.EnqueueAsync) 로 게시하고 대신 FileShareConfig.RootPath 를 설정하십시오. 대소문자에 유의하십시오 — 이전 라이브러리는 이를 IsWebfarm 로 표기했습니다. |
string | WebFarmPath | "" | 구식 — 효과 없음. FileShareConfig.RootPath 를 사용하십시오, 분산 배포 에 설명된 대로. 이전에 WebfarmPath 로 표기되었습니다. |
bool | EditMode | false | 별도로 배포되는 편집 워크플로를 위해 예약됨; 표준 뷰어를 위해 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
});| 필드 | 예시 | 의미 |
|---|---|---|
선행 ^ | ^ | 선택적인 모든 모서리 레이아웃. 없을 경우 일반 워터마크 배치가 사용됩니다. |
| 텍스트 | 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 |
이들 각각은 세션 토큰을 필요로 합니다. 이전 라이브러리의 세션 없는 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 (주석 제한), 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 }))이 헬퍼들은 브라우저 리소스를 제공하는 지원되는 방법입니다. docViewer.js, documentLinks.js, docViewer.UI.js을 wwwroot에 복사한 애플리케이션은, 페이지가 출력된 태그에서 렌더링된 후 해당 복사본을 제거해야 합니다.
이 페이지가 도움이 되었나요?