포맷 구성 – Doconut 문서

모든 문서는 BaseConfig 구현으로 시작합니다. 이를 OpenDocumentAsync(또는 OpenDocument)에 전달하거나 포맷 카탈로그가 기본값을 생성하도록 합니다. 아래 모든 클래스는 Doconut 네임스페이스에 포함됩니다.

csharp

var token = await viewer.OpenDocumentAsync(path, new PdfConfig
{
    AllowSearch = true,
    AllowCopy   = true,
    ImageResolution = 150
});

상속 및 중첩 PDF 설정

모든 포맷은 다섯 개의 BaseConfig 속성을 상속합니다. PDF를 통해 리다이렉트할 수 있는 포맷은 중첩된 PdfConfig를 노출합니다. WordConfig, ExcelConfig, PptConfig에서는 AllowSearch와 AllowCopy가 중첩된 PdfConfig를 읽고 쓰는 편의 속성입니다.

DefaultRender = true는 기본 포맷 렌더러를 선택합니다. PDF 리다이렉트가 있는 포맷에서는 false가 먼저 메모리 내 PDF로 변환한 뒤 PDF 뷰어를 사용합니다. 이 경로는 텍스트 좌표 검색에 유용하지만 추가 변환 비용이 발생합니다.

별도로 명시되지 않는 한, 표는 생성자/속성 기본값을 보여줍니다. 자동 포맷 카탈로그는 의도적으로 두 값을 재정의합니다: ExcelConfig를 SplitWorksheets = true로 생성하고, MhtConfig를 DefaultRender = false로 생성합니다.

BaseConfig

유형	속성	기본값	동작
`int`	`ImageResolution`	`0`	`0`은 포맷 기본값을 사용합니다. 유효한 명시 범위는 25-300 DPI이며, 잘못된 할당은 무시됩니다.
`string`	`DocumentCulture`	`""`	날짜와 숫자의 로케일입니다. 비공백 값은 트림되고, 공백 할당은 무시됩니다.
`string`	`Password`	`""`	보호된 문서의 비밀번호입니다. `DocOptions.Password`가 자동으로 여기 복사됩니다.
`bool`	`ShowUI`	`true`	호환성 속성; 현재 렌더러는 브라우저 툴바 제어에 이를 사용하지 않습니다.
`bool`	`CachePages`	`true`	문서 세션 동안 렌더링된 페이지 이미지를 캐시합니다.

PdfConfig

포맷: PDF. 기본 DPI: 200.

유형	속성	기본값	동작
`bool`	`DefaultRender`	`true`	호환성 스위치. 현재 팩토리는 기본 PDF 뷰어를 사용합니다.
`bool`	`AllowSearch`	`false`	PDF 텍스트 검색 인덱스를 구축/사용합니다. 요청에 Search 라이선스 기능이 필요합니다.
`bool`	`AllowCopy`	`false`	텍스트 선택/복사 작업을 허용합니다.
`bool`	`ExtractHyperlinks`	`false`	클라이언트 오버레이용 링크 사각형을 추출합니다.
`int`	`HyperlinksPageCount`	`0`	링크를 스캔할 최대 페이지 수; `0`은 모든 페이지를 의미합니다.
`bool`	`CompressImages`	`false`	렌더링 전에 포함된 이미지를 압축합니다.
`int`	`CompressQuality`	`100`	압축이 활성화될 때 사용되는 JPEG 품질입니다.
`bool`	`ResizeImages`	`false`	렌더링 전에 포함된 이미지를 크기 조정합니다.
`int`	`ResizeResolution`	`300`	크기 조정된 이미지의 목표 DPI입니다.
`bool`	`CompressFast`	`false`	더 빠르고 품질이 낮은 압축 경로를 선호합니다.
`bool`	`FixInvalidImages`	`false`	잘못된 포함 이미지 수리를 시도합니다.
`bool`	`SplitSegments`	`false`	검색/복사를 개선하기 위해 줄 구간에 걸쳐 분할된 단어를 다시 합칩니다.

ViewerConfig의 showHyperlinks는 클라이언트 오버레이를 제어하고, ExtractHyperlinks는 서버 추출을 제어합니다. 두 옵션을 모두 활성화합니다.

WordConfig

포맷: DOC, DOCX, DOCM, DOT, DOTX, DOTM, RTF, ODT, OTT, XML. 기본 DPI: 200.

유형	속성	기본값	동작
`bool`	`DefaultRender`	`true`	기본 Word 렌더링; `false`는 PDF 리다이렉트를 사용합니다.
`PdfConfig`	`PdfConfig`	new instance	PDF/검색 경로에서 사용되는 설정입니다.
`DocPaperSize`	`PaperSize`	`A4`	출력 용지 크기. `Custom`을 사용해 너비/높이를 지정합니다.
`int`	`PaperWidth`	`595`	포인트 단위의 사용자 정의 너비.
`int`	`PaperHeight`	`841`	포인트 단위의 사용자 정의 높이.
`bool`	`RemovePaperMargin`	`false`	문서 페이지 여백을 제거합니다.
`bool`	`RenderPageColor`	`true`	Word에서 설정한 페이지 색상을 유지합니다; `false`는 흰색 페이지를 렌더링합니다.
`bool`	`ExportPdfA`	`false`	PDF 경로에서 보존용 PDF/A를 사용합니다.
`Encoding?`	`FileEncoding`	`null`	원본 인코딩을 재정의합니다.
`string`	`FontInfo`	`""`	글꼴 대체 정보.
`string[]?`	`FontFolders`	`null`	추가 글꼴 디렉터리 — 문서에 사용되는 글꼴이 없는 서버에 유용합니다.
`bool`	`AllowSearch`	`false`	`PdfConfig.AllowSearch`에 위임합니다.
`bool`	`AllowCopy`	`false`	`PdfConfig.AllowCopy`에 위임합니다.
`TableAutoFitBehavior`	`AutoFitAllTables`	`None`	`None`, `AutoFitToContents`, `AutoFitToWindow` 중 하나입니다.

ExcelConfig

지원 형식: XLS, XLSX, XLSM, XLSB, XLTX, XLTM, ODS, CSV. 기본 DPI: 200.

유형	속성	기본값	동작
`bool`	`DefaultRender`	`true`	네이티브 시트 렌더링; `false`는 PDF 리다이렉트를 사용합니다.
`PdfConfig`	`PdfConfig`	new instance	PDF/검색 경로에 대한 설정.
`ExcelPaperSize`	`PaperSize`	`PaperA4`	출력 용지 크기.
`double`	`PaperMargins`	`0.25`	인치 단위 페이지 여백.
`bool`	`PaperLandscape`	`true`	가로 방향 시트 렌더링.
`bool`	`AutoFitContents`	`false`	행 높이와 열 너비를 자동 맞춤.
`bool`	`RemoveEmptyContent`	`true`	빈 콘텐츠를 제외하여 출력 압축.
`bool`	`CalculateFormula`	`true`	렌더링 전에 수식을 다시 계산.
`bool`	`ShowRowColumnHeaders`	`true`	스프레드시트 헤더 포함.
`bool`	`ExportPdfA`	`false`	PDF 경로에서 PDF/A 사용.
`bool`	`SplitWorksheets`	`false`	워크시트를 별도 페이지 그룹으로 유지.
`bool`	`ShowEmptyWorkSheets`	`false`	빈 워크시트 포함.
`bool`	`ExportLandscape`	`false`	가로 방향 내보내기 강제.
`bool`	`ExportOnePagePerSheet`	`false`	각 워크시트를 하나의 출력 페이지에 맞춤.
`bool`	`MemoryOptimizationPreference`	`true`	피크 메모리를 줄이며, 속도가 약간 감소할 수 있음.
`bool`	`AutoTrimWorksheetRenderRange`	`true`	명시적 인쇄 영역이 없을 때 사용된 가시 범위만 렌더링.
`bool`	`AutoTrimPreserveExistingPrintArea`	`true`	자동 트림 중에 워크북에 정의된 인쇄 영역을 보존.
`string?`	`PrintArea`	`null`	예: `"A1:Z100"`와 같은 명시적 범위.
`bool`	`PrintGridlines`	`false`	워크시트 격자선 인쇄.
`bool`	`PrintHeadings`	`false`	행/열 헤더 인쇄.
`List<string>`	`SheetNames`	empty	지정된 워크시트 이름으로 렌더링 제한.
`CustomStyleCell?`	`CustomStyles`	`null`	선택적 날짜/소수/정수 형식 재정의.
`bool`	`AllowSearch`	`false`	`PdfConfig.AllowSearch`에 위임.
`bool`	`AllowCopy`	`false`	`PdfConfig.AllowCopy`에 위임.

CustomStyleCell은 CustomStyleDateTime, CustomStyleNumberDecimal, CustomStyleNumberInteger를 노출하며, 모두 nullable 문자열입니다.

new ExcelConfig()는 SplitWorksheets를 false로 설정합니다; 명시적 구성이 없는 Excel 파일을 열면 형식 카탈로그를 사용하며, 이때 SplitWorksheets가 true로 설정됩니다.

PptConfig

지원 형식: PPT, PPTX, PPTM, PPSX, PPSM, POT, POTX, POTM, ODP. 기본 DPI: 200.

유형	속성	기본값	동작
`bool`	`DefaultRender`	`true`	네이티브 슬라이드 렌더링; `false`는 PDF 리다이렉트를 사용합니다.
`bool`	`FastLoad`	`false`	열 때 첫 슬라이드 렌더링을 피하고 메타데이터를 사용해 필요 시 렌더링합니다.
`PdfConfig`	`PdfConfig`	new instance	PDF/검색 동작에 대한 설정.
`string`	`FontInfo`	`""`	글꼴 대체 정보.
`string[]?`	`FontFolders`	`null`	추가 글꼴 디렉터리.
`bool`	`AllowSearch`	`false`	`PdfConfig.AllowSearch`에 위임.
`bool`	`AllowCopy`	`false`	`PdfConfig.AllowCopy`에 위임.

프레젠테이션에서 사용하는 글꼴을 서버에 설치하거나 FontFolders를 해당 글꼴이 있는 폴더로 지정하십시오. Office가 설치되지 않은 Windows Server는 개발 머신보다 훨씬 적은 글꼴을 가지고 있으며, 누락된 글꼴은 오류 없이 대체됩니다.

CadConfig

지원 형식: DWG, DXF, DGN. 기본 DPI: 200.

유형	속성	기본값	동작
`bool`	`DefaultRender`	`true`	네이티브 CAD 렌더링; `false`는 PDF 리다이렉트를 사용합니다.
`PdfConfig`	`PdfConfig`	new instance	PDF 경로 설정.
`bool`	`ExportPdfA`	`false`	보관용 PDF/A 출력.
`bool`	`ShowColor`	`true`	흑백이 아닌 컬러.
`bool`	`WhiteBackground`	`true`	검은색 배경 대신 흰색 배경.
`short`	`LineWidth`	`25`	CAD 선 두께.
`bool`	`ShowLayouts`	`false`	레이아웃 탭 렌더링.
`bool`	`ShowModel`	`true`	모델 공간 렌더링.
`bool`	`Check3DSolid`	`true`	3D 솔리드 처리.
`bool`	`ExportAllLayouts`	`false`	모델/레이아웃 선택을 무시하고 모든 레이아웃을 내보냅니다.
`bool`	`LimitMinimumSize`	`false`	`MinimumSize` 적용.
`int`	`MinimumSize`	`700`	최소 출력 크기(픽셀).
`bool`	`LimitMaximumSize`	`false`	`MaximumSize` 적용.
`int`	`MaximumSize`	`700`	최대 출력 크기(픽셀).
`bool`	`ShowAllLayoutsDgn`	`false`	모든 DGN 레이아웃 포함.
`bool`	`AutomaticLayoutScaling`	`true`	레이아웃을 자동으로 스케일링.
`float`	`PdfMargins`	`0.5`	PDF 여백(인치).
`RenderQuality`	`QualityImage`	`Low`	래스터 품질: `Low`, `Medium`, `High`.
`RenderQuality`	`QualityText`	`Medium`	텍스트 품질: `Low`, `Medium`, `High`.

EmailConfig

지원 형식: EML, EMLX, MSG. 기본 DPI: 200.

유형	속성	기본값	동작
`bool`	`DefaultRender`	`true`	네이티브 이메일 렌더링; `false`는 PDF 리다이렉트를 사용합니다.
`PdfConfig`	`PdfConfig`	새 인스턴스	PDF 경로 설정.
`Encoding?`	`EmailEncoding`	`null`	메시지 인코딩을 재정의합니다.
`Encoding?`	`SubjectEncoding`	`null`	제목 인코딩을 재정의합니다.
`Encoding?`	`BodyEncoding`	`null`	본문 인코딩을 재정의합니다.
`bool`	`SkipExternalImages`	`false`	원격으로 참조된 이미지를 로드하지 않습니다. 신뢰할 수 없는 이메일에 권장됩니다.
`bool`	`RemoveLastWhitePage`	`false`	끝에 있는 빈 페이지를 제거합니다.
`bool`	`UseAntiAliasing`	`false`	안티앨리어싱을 활성화합니다.
`bool`	`UseHighQualityRendering`	`false`	보다 깔끔하지만 느린 렌더링을 선호합니다.
`TimeSpan?`	`TimeZoneOffset`	`null`	날짜에 사용되는 시간대를 재정의합니다.
`bool`	`ForcePageSize`	`false`	고정 페이지 크기를 강제합니다.

ImageConfig, TiffConfig, and PsdConfig

ImageConfig는 JPG, JPEG, JPE, PNG, BMP, GIF, ICO, EPS, TGA, WEBP, CDR, CMX, DNG, EMF, WMF, AVIF 및 SVG를 지원합니다. 기본 DPI는 100입니다.

구성	속성	기본값	동작
`ImageConfig`	`MaxImagePixelSize`	`3000`	최대 너비/높이. `0`은 무제한을 의미합니다; 0이 아닌 값이 50 미만이면 무시됩니다.
`ImageConfig`	`TransparentPng`	`true`	PNG 투명성을 유지합니다; `false`는 흰색 배경을 사용합니다.
`TiffConfig`	추가 속성 없음	DPI `200`	`BaseConfig`만 사용합니다; 다중 페이지 TIFF를 지원합니다.
`PsdConfig`	`MaxImagePixelSize`	`3000`	`ImageConfig`와 동일한 `0`/최소 50 검증; 기본 DPI는 `100`입니다.

DicomConfig

지원 형식: DCM, IMA. 기본 유효 DPI: 100. DICOM 플러그인이 필요합니다. 이 패키지에서는 DICOM 파일이 완전히 렌더링되지만 기술 메타데이터는 제공되지 않습니다 — DICOM 플러그인을 참고하십시오.

유형	속성	기본값	동작
`int`	`HorizontalResolution`	`100` (유효)	명시적인 가로 DPI; 그렇지 않으면 `ImageResolution`, 그 다음 100을 사용합니다.
`int`	`VerticalResolution`	`100` (유효)	명시적인 세로 DPI; 그렇지 않으면 `ImageResolution`, 그 다음 100을 사용합니다.
`int`	`AnimationFrameDelayMs`	`100`	다중 프레임 애니메이션 지연; GIF 타이밍은 10 ms 단위를 사용합니다.
`ushort`	`LoopCount`	`0`	`0`은 무한 반복; 양수 값은 해당 횟수만큼 반복 후 중지합니다.
`DicomDisplayMode`	`DisplayMode`	`AnimationAndFrames`	`AnimationOnly`, `FramesOnly` 또는 개요와 정적 프레임을 결합한 모드.

TxtConfig

지원 형식: TXT. 기본 DPI: 200.

유형	속성	기본값	동작
`DocPaperSize`	`PaperSize`	`A4`	출력 용지 크기.
`Encoding?`	`FileEncoding`	`null`	`null`은 UTF-8을 사용합니다.
`string`	`FontInformation`	`""`	텍스트 렌더링을 위한 글꼴 정보.

일반 텍스트에 더 풍부한 페이지 레이아웃 동작이 필요할 경우 WordConfig를 사용하십시오.

ProjectConfig

지원 형식: MPP, MPPX, MPX. 기본 DPI: 200.

유형	속성	기본값	동작
`bool`	`DefaultRender`	`true`	네이티브 Gantt 이미지; `false`는 텍스트 기반 PDF 경로를 사용합니다.
`PdfConfig`	`PdfConfig`	새 인스턴스	PDF 경로 설정.
`bool`	`ExportPdfA`	`true`	보관용 PDF/A 출력.
`MppPaperSize`	`PaperSize`	`Ledger`	프로젝트 출력 용지 크기.
`MppTimeScale`	`TimeScale`	`Months`	`Days` 또는 `Months`.
`MppFormat`	`PresentationFormat`	`GanttChart`	`GanttChart`, `TaskUsage`, `ResourceUsage`, `ResourceSheet`, 또는 `TaskSheet`.

정확한 텍스트 좌표 검색을 위해 DefaultRender = false를 사용하십시오.

VisioConfig

지원 형식: VSD, VSDX, VSS, VSSX, VST, VSTX, VDX, VSX, VSDM. 기본 DPI: 200.

유형	속성	기본값	동작
`bool`	`DefaultRender`	`true`	네이티브 다이어그램 렌더링; `false`는 PDF 리다이렉트를 사용합니다.
`PdfConfig`	`PdfConfig`	새 인스턴스	PDF 경로 설정.
`bool`	`ExportPdfA`	`true`	보관용 PDF/A 출력.

HtmlConfig, EpubConfig, MhtConfig, and XpsConfig

네 개 모두 기본 DPI가 200이며 중첩된 PdfConfig를 노출합니다.

구성	지원 형식	`DefaultRender`	추가 속성/동작
`HtmlConfig`	HTML, HTM	`true`	네이티브 렌더링; 텍스트 기반 PDF 검색 경로를 위해 `false`를 사용합니다.
`EpubConfig`	EPUB	`true`	네이티브 렌더링; `false`는 PDF를 사용합니다.
`MhtConfig`	MHT, MHTML	클래스에서 `true`; 자동 카탈로그에서는 `false`	일반적인 무구성 열기는 검색 가능한 PDF 리다이렉트를 사용합니다. 명시적으로 생성된 기본 인스턴스는 네이티브로 렌더링합니다.
`XpsConfig`	XPS	`false`	기본적으로 PDF 경로를 사용합니다; 네이티브 이미지 렌더링을 위해 `true`로 설정합니다.

가족별 구성 예시

csharp

BaseConfig[] configs =
{
    new PdfConfig
    {
        AllowSearch = true,
        ExtractHyperlinks = true,
        HyperlinksPageCount = 0
    },
    new WordConfig
    {
        PaperSize = DocPaperSize.A4,
        RemovePaperMargin = false,
        FontFolders = new[] { HostingEnvironment.MapPath("~/App_Data/Fonts") },
        AllowSearch = true
    },
    new ExcelConfig
    {
        PaperLandscape = true,
        AutoFitContents = true,
        CalculateFormula = true,
        SplitWorksheets = false,
        PrintGridlines = false
    },
    new PptConfig
    {
        FastLoad = true,
        FontFolders = new[] { HostingEnvironment.MapPath("~/App_Data/Fonts") },
        AllowSearch = true
    },
    new CadConfig
    {
        ShowColor = true,
        WhiteBackground = true,
        ShowModel = true,
        ShowLayouts = false,
        QualityText = CadConfig.RenderQuality.High
    },
    new EmailConfig
    {
        SkipExternalImages = true,
        RemoveLastWhitePage = true,
        TimeZoneOffset = TimeSpan.Zero
    },
    new ImageConfig
    {
        MaxImagePixelSize = 3000,
        TransparentPng = true
    },
    new DicomConfig
    {
        DisplayMode = DicomDisplayMode.AnimationAndFrames,
        AnimationFrameDelayMs = 100,
        LoopCount = 0
    }
};

확장자별 선택

csharp

static BaseConfig ConfigForExtension(string extUpper)
{
    switch (extUpper)
    {
        case ".DOC": case ".DOCX": case ".DOT": case ".DOTX": case ".ODT":
            return new WordConfig
            {
                AutoFitAllTables = WordConfig.TableAutoFitBehavior.AutoFitToWindow,
                PaperSize = DocPaperSize.Tabloid,
                PdfConfig = new PdfConfig { ExtractHyperlinks = true, HyperlinksPageCount = 5, AllowCopy = true }
            };
        case ".PDF":
            return new PdfConfig { AllowSearch = true, AllowCopy = true };
        case ".XLS": case ".XLSX": case ".ODS": case ".CSV":
            return new ExcelConfig { AllowSearch = true, AllowCopy = true };
        case ".DCM": case ".IMA":
            return new DicomConfig { DisplayMode = DicomDisplayMode.AnimationAndFrames };
        // DefaultRender = false → PDF redirect → pixel-accurate native text search
        case ".HTML": case ".HTM":
            return new HtmlConfig { DefaultRender = false };
        case ".EML": case ".EMLX": case ".MSG":
            return new EmailConfig { DefaultRender = false };
        default:
            return null; // fall back to the format's default config
    }
}