뷰어

주요 문서 뷰어 클래스

Viewer (namespace Doconut) 은 MVC 컨트롤러, Web Forms 페이지 및 핸들러에서 문서를 여는 공개 진입점입니다. 이것은 DoconutHost.Initialize 로 구성된 일시적 서비스이며, 사용 위치에서 해결하십시오:

csharp
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

new Viewer() 은 DoconutHost.Initialize 가 실행된 후에도 작동합니다 — 동일한 서비스를 해결하므로 클래식 패키지에서 마이그레이션된 코드가 컴파일될 수 있습니다. Initialize 이전에는 InvalidOperationException 를 발생시킵니다.

Viewer 은 요청당 문서 상태를 보유하지 않으며 의도적으로 IDisposable 를 구현하지 않음: 문서 세션은 그것과 독립적으로 존재하므로 Viewer 를 폐기해도 열린 문서를 닫을 수 없습니다 (see 뷰어 작동 방식).

비동기 문서 열기

문서를 열고 위젯이 이후 모든 요청에 사용하는 세션 토큰을 반환합니다. UnsafeMode 가 false (기본값)인 경우, 토큰은 현재 요청의 ASP.NET 세션에 부여됩니다 — 세션 상태가 있는 요청에서 호출하십시오 (see 세션 및 보안).

오버로드사용 시
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 });

// 업로드에서 (MVC의 HttpPostedFileBase; Web Forms의 HttpPostedFile)
using (var ms = new MemoryStream())
{
    await file.InputStream.CopyToAsync(ms);
    ms.Position = 0;
    token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}

처리해야 할 예외:

  • LicenseException — 라이선스가 발견되었지만 거부되었습니다 (메시지에 이유가 포함됨), 또는 형식에 라이선스가 부여하지 않은 플러그인 기능이 필요합니다.
  • FormatNotSupportedException — 파일 확장자를 처리하는 뷰어가 없습니다.
  • InvalidDataException — 콘텐츠가 손상되었거나 확장자와 일치하지 않습니다.

동기식 문서 열기

비동기 페이지를 사용하지 않는 Web Forms 코드 비하인드 및 기타 코드용:

text
string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)

각 메서드는 토큰을 반환하고 또한 viewer.Token 에 저장합니다. fileName 은 올바른 확장자를 포함해야 합니다. 이러한 래퍼는 Web Forms 페이지에서 호출해도 안전합니다: 열기 경로가 ASP.NET 요청 컨텍스트에서 다시 시작되지 않으므로 대기해도 교착 상태가 발생하지 않습니다. 모든 비동기 Doconut API에 대해 구현되지 않음은 사실이 아닙니다 — 컨버터 플러그인 의 Web Forms 섹션을 참조하십시오.

CloseDocument

text
void CloseDocument(string token)

세션을 제거하고(문서 엔진을 즉시 해제), 현재 요청의 ASP.NET 세션에서 토큰의 권한을 제거하며 토큰을 취소합니다. 선택 사항 — 슬라이딩 만료가 동일한 정리를 수행하지만, 큰 문서의 경우 권장됩니다.

세션 쿼리

멤버반환값
int GetPageCount(string token)열린 문서의 전체 페이지 수
(int Width, int Height) GetPageDimensions(string token, int page = 1)100% 줌에서 기본 렌더링 페이지 크기 — 코드에 내장된 주석용 좌표 공간
IReadOnlyList<string> GetWorksheetNames(string token)스프레드시트의 렌더링된 워크시트(워크북 순서대로); 다른 문서는 비어 있음

각각은 토큰이 알 수 없거나 만료된 경우 InvalidOperationException (Document session not found. Please re-open document.)을 발생시키고, 빈 토큰인 경우 ArgumentException을 발생시킵니다.

DocOptions

열기당, 형식에 독립적인 옵션 (네임스페이스 Doconut):

유형속성기본값설명
stringPassword""보호된 문서의 비밀번호 (자동으로 형식 구성에 복사됨).
stringWatermark""렌더링된 페이지에 그려지는 사용자 지정 워터마크 텍스트 — 아래 참고.
intTimeOut60세션 슬라이딩 만료, 분 단위.
stringBrowserId""웹 팜: 서명된 티켓이 바인딩되는 브라우저. DoconutFarmBinding.EnsureBrowserId으로 설정합니다 (세션 및 보안 참고).
stringUserId""웹 팜: 티켓이 바인딩되는 로그인 사용자, DoconutFarmBinding.ResolveUserId에서 가져옴.
intImageResolution0구식. 대신 형식 구성에 ImageResolution을 설정하십시오.
boolIsSecuredtrue예약됨; 적용되지 않음. 접근 제어는 DoconutOptions.UnsafeMode입니다.
boolIsWebFarm / string WebFarmPathfalse / ""클래식 패키지에서 마이그레이션된 코드를 위해 유지됩니다. 이들은 팜 모드를 켜지 않으며 — AddDoconutDistributed은 켭니다.
boolEditModefalse별도로 배포되는 편집기를 위해 예약됨; 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
    });
필드예시의미
Leading ^^선택적인 모든 모서리 레이아웃. 없으면 일반 배치가 사용됩니다.
TextConfidential각 페이지에 그려지는 텍스트. 비어 있어서는 안 됩니다.
ColorRed이름이 지정된 색상.
FontSize24글꼴 크기; 잘못된 숫자 입력은 기본값으로 대체됩니다.
FontNameVerdana폰트 패밀리. 서버에 설치되어 있어야 합니다 — Windows Server는 데스크톱보다 폰트가 적습니다.
Opacity800에서 255 사이. 파싱 가능해야 합니다.
Angle-45도 단위 회전; 잘못된 숫자 입력은 기본값으로 대체됩니다.

파서는 선택적 ^ 뒤에 정확히 6개의 필드를 기대합니다. 잘못된 정의는 조용히 사라지는 대신 보이는 Invalid Watermark 텍스트로 대체됩니다.

라이선스 결정

라이선스 상태제공된 사용자 지정 값렌더링 결과
유효한 유료 뷰어 라이선스아니오깨끗한 페이지
유효한 유료 뷰어 라이선스예사용자 지정 워터마크
활성 임시/데모 라이선스아니오깨끗한 페이지
활성 임시/데모 라이선스예사용자 지정 워터마크
누락, 거부, 만료, 잘못된 버전, 또는 잘못된 도메인 라이선스둘 중 하나평가 워터마크; 사용자 지정 값은 이를 대체하지 않습니다

같은 결정이 제공되는 페이지와 주석 내보내기에 적용됩니다. 사용자 지정 워터마크는 라이선스가 있는 애플리케이션의 기능이며, 평가 워터마크를 대체하는 방법이 아닙니다.

주석 API

서버 측 주석 로드 및 내보내기. 전체 안내는 주석에서 확인할 수 있습니다.

멤버목적
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()이 반환한 인코딩된 엔벨로프를 로드합니다
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)

이 패키지에서는 항상 null을 반환하며, 위젯의 메타데이터 요청은 501 Not Implemented으로 응답합니다: .NET Framework에서는 DICOM 태그를 읽을 수 없습니다. DICOM 렌더링 — 페이지, 프레임, 애니메이션 — 은 작동합니다. DICOM 플러그인을 참고하세요.

리소스 헬퍼 — ReferenceCss / ReferenceScripts

<link>와 <script> 태그를 의존성 순서대로, 리소스 모듈이 DoconutOptions.ResourcesPath 아래에서 제공하는 리소스에 대해 출력합니다. 라이선스 기반 기능(검색, 주석)의 파일은 라이선스가 허용할 때만 출력됩니다.

text
string ReferenceCss(CssConfig? config = null)       // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // 라이선스 상태, ribbon init 코드를 보호하기 위해
bool IsAnnotationEnabled { get; }

CssConfig 플래그: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (검색 제한), IncludeAnnotationCss (주석 제한).

ScriptConfig 플래그: IncludeJQuery (모든 다른 것에 필요), IncludeBootstrap, IncludeViewerScripts (핵심 뷰어 스크립트), IncludeSearchScripts와 IncludeSearchBar (검색 제한), IncludeAnnotationScripts와 IncludeAnnotationBar (주석 제한), EmitFeatureFlags (기본 true: 인라인 window.Doconut.features = { search, annotation, editor } 스크립트도 작성합니다; 인라인 스크립트를 차단하는 Content-Security-Policy 하에서는 false로 설정합니다).

두 경우 모두 HTML을 반환합니다: MVC 5에서는 @Html.Raw(...)를 사용해 작성하고(컨트롤러에서 생성 — 뷰에는 @inject가 없습니다), Web Forms에서는 <%= %>를 사용합니다. 빠른 시작에서는 두 방법을 모두 보여줍니다.

RenderViewer

text
string RenderViewer(string elementId, string token, ViewerConfig? config = null)

<script> 블록을 반환하며, 이는 id가 elementId인 요소에 위젯을 초기화하고 문서를 표시합니다: docViewer({...})은 ViewerConfig에서 구축됩니다(기본값: BasePath: '/', ResPath: 'doconut-res/images'), 그 다음 .View(token). 뷰어 스크립트 뒤에 작성하십시오. 생성된 스크립트는 뷰어 객체에 대한 참조를 유지하지 않으므로, 자체 툴바가 있는 페이지는 대신 위젯을 수동으로 초기화해야 합니다. 뷰어 구성를 참고하세요.

웹 팜

string? AccessToken는 분산 모드가 활성화된 상태에서 가장 최근에 열린 시점에 발행된 서명된 티켓을 보관하며, UnsafeMode는 false입니다; 단일 서버에서는 null입니다. 토큰과 함께 위젯에 전송하십시오: objViewer.View(token, accessToken).

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