뷰어
주요 문서 뷰어 클래스
Viewer (namespace Doconut) 은 Razor 페이지, MVC 컨트롤러, Blazor 컴포넌트 또는 최소 API에서 문서를 여는 공개 진입점입니다. 이는 sealed이며, AddDoconut() 에 의해 transient 서비스로 등록되고 생성자 주입을 통해 해결됩니다 — 직접 인스턴스를 만들지 마세요.
이전 .NET Standard 라이브러리는 메모리 캐시, HTTP 컨텍스트 액세서, 그리고 하나 이상의 라이선스 경로를 받는 공개 생성자를 제공했습니다. 해당 생성자는 사라졌으며; 서비스 그래프가 이러한 종속성을 제공합니다.
Viewer 은 요청당 상태를 보유하지 않으며 의도적으로 IDisposable 를 not 구현합니다: 문서 세션은 세션 캐시에서 독립적으로 존재하므로 서비스를 폐기해도 열린 문서를 해제할 수 없습니다 (Core Concepts → How the Viewer Works 를 참조).
OpenDocumentAsync (문서 열기 비동기)
문서를 열고 클라이언트 위젯이 이후 모든 요청에 사용하는 세션 토큰을 반환합니다. 모든 열기는 비동기이며 — 동기 OpenDocument 은 존재하지 않습니다.
| 오버로드 | 사용 시기 |
|---|---|
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)열린 세션의 전체 페이지 수입니다. 토큰이 알 수 없거나 만료된 경우 예외가 발생합니다.
GetWorksheetNames (워크시트 이름 가져오기)
IReadOnlyList<string> GetWorksheetNames(string token)열린 스프레드시트의 워크시트 이름을 워크북 순서대로 반환합니다. 열린 문서가 스프레드시트가 아닌 경우 빈 리스트를 반환합니다.
렌더링된 워크시트만 나열됩니다: 숨겨진 및 빈 워크시트는 제외되며, ExcelConfig.SheetNames 가 렌더링을 제한할 경우 해당 워크시트만 표시됩니다. 워크시트가 항상 한 페이지인 것은 아니며—매우 큰 경우 여러 페이지에 걸쳐 렌더링됩니다. 토큰이 알 수 없거나 만료된 경우 예외가 발생합니다.
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 | 열기 작업을 공유 저장소 시나리오로 표시합니다. 대소문자에 유의하세요 — 이전 라이브러리는 이를 IsWebfarm 로 표기했습니다. |
string | WebFarmPath | "" | 해당 워크플로에서 사용되는 공유 경로. 이전에 WebfarmPath 로 표기되었습니다. 일반 단일 호스트 뷰어에서는 비어 있으며, 분산 배포에서 설명된 게시 경로에서는 필요하지 않습니다. |
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
});| 필드 | 예시 | 의미 |
|---|---|---|
선행 ^ | ^ | 선택적 모든 모서리 레이아웃. 없을 경우 일반 워터마크 배치가 사용됩니다. |
| Text | Confidential | 각 페이지에 렌더링되는 텍스트. 비어 있을 수 없습니다. |
| Color | Red | 그리기 레이어가 이해하는 명명된 색상. |
| FontSize | 24 | 글꼴 크기; 잘못된 숫자 입력은 렌더러 기본값으로 대체됩니다. |
| FontName | Verdana | 요청된 글꼴 패밀리. 배포 환경에 설치되어 있어야 합니다. |
| Opacity | 80 | 0에서 255 사이의 바이트 값. 성공적으로 파싱되어야 합니다. |
| Angle | -45 | 회전 각도(도). 잘못된 숫자 입력은 기본값으로 대체됩니다. |
파서는 선택적 ^ 뒤에 정확히 여섯 개의 필드를 기대합니다. 정의가 잘못되면 SDK의 가시적 Invalid Watermark 폴백으로 교체되며, 조용히 사라지지는 않습니다.
라이선스 결정
| 라이선스 상태 | 제공된 사용자 값 | 렌더링 결과 |
|---|---|---|
| 유효한 유료 뷰어 라이선스 | No | 깨끗한 페이지 |
| 유효한 유료 뷰어 라이선스 | Yes | 사용자 지정 워터마크 |
| 활성 임시/데모 기본 뷰어 | No | 깨끗한 기본 뷰어 페이지 |
| 활성 임시/데모 기본 뷰어 | Yes | 깨끗한 기본 뷰어 경로가 적용될 때 사용자 지정 워터마크 |
| 누락, 거부, 만료, 버전 불일치 또는 도메인 불일치 라이선스 | Either | 강제/평가 워터마크; 사용자 지정 값이 이를 대체하지 않음 |
| 평가 규칙에 따른 플러그인 렌더링 | Either | 평가 워터마크 |
같은 결정이 제공되는 페이지 이미지와 주석 내보내기에 적용됩니다. 애니메이션 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(…) | 주석이 포함된 PNG 파일 |
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 + 뷰어 + 검색 + 주석
string ReferenceScripts(ScriptConfig? config = null)CssConfig 플래그: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (검색 제한), IncludeAnnotationCss (주석 제한).
ScriptConfig 플래그: IncludeJQuery (다른 모든 것에 필요), IncludeBootstrap, IncludeViewerScripts (핵심: docViewer.js + splitter + links), IncludeSearchScripts 및 IncludeSearchBar (검색 제한), IncludeAnnotationScripts 및 IncludeAnnotationBar (주석 제한).
@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에 복사한 애플리케이션은, 페이지가 출력된 태그에서 렌더링된 후 해당 복사본을 제거해야 합니다.
이 페이지가 도움이 되었나요?