DoconutExtensions – Doconut 문서

DoconutExtensions (네임스페이스 Doconut.Middleware)는 모든 Doconut 호스트가 수행하는 세 가지 호출(서비스 등록 하나와 미들웨어 등록 두 개)을 제공하는 정적 클래스입니다.

csharp

builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseDoconutResources(); // BEFORE UseDoconut()
app.UseDoconut();

AddDoconut

text

IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)

DoconutOptions를 빌드하고, 빠르게 실패하도록 검증한 뒤(DoconutOptions → 시작 검증을 참조), 전체 서비스 그래프를 등록합니다:

서비스	수명	역할
`DoconutOptions`	싱글톤	구성 객체
`IViewerFactory`	싱글톤	확장자를 포맷 뷰어에 매핑합니다
`IDocumentSessionManager`	싱글톤	Token → 세션 캐시 (`IMemoryCache`도 등록됩니다)
`IDoconutLicenseService`	싱글톤	시작 시 한 번 로드되는 라이선스 (우선순위: `LicenseStream` → `LicenseContent` → `LicensePath` → 자동 검색)
`PageImageService`	싱글톤	페이지 이미지 파이프라인 (워터마크/회전/스케일/주석)
Document security (access store)	싱글톤	Token과 세션 바인딩을 위한 권한 부여
`Viewer`	트랜지언트	공개 열기/닫기 파사드
`DocumentConverter`	트랜지언트	변환 파사드 — Converter 플러그인 필요
Health check `"doconut"`	—	ASP.NET 헬스 체크를 통해 라이선스/만료 상태를 보고합니다

알아두면 좋은 두 가지 동작:

Converter는 플러그인이 필요합니다. options.AddPlugin<ConverterPlugin>() 없이 DocumentConverter를 해결하면 다음과 같은 예외가 발생합니다:

text

InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

플러그인 권한은 시작 시 검증됩니다. 라이선스가 없거나 레거시 TRIAL 파일이 있거나, 등록된 플러그인 기능 없이 유료 라이선스를 사용하면 AddDoconut() 시점에 실패합니다. 임시/데모 등록은 만료 날짜까지 유지되지만, 런타임 게이트는 만료된 기능을 회수합니다.

헬스 체크는 표준 ASP.NET Core 메커니즘과 통합됩니다 — 라이선스 상태를 헬스 엔드포인트에 표시하려면 매핑하세요:

csharp

app.MapHealthChecks("/health");

UseDoconut

text

IApplicationBuilder UseDoconut(this IApplicationBuilder app)

Doconut 페이지 이미지 미들웨어를 추가합니다. ?token= 쿼리 매개변수를 포함한 모든 요청에 응답합니다 — 페이지, 썸네일, 검색, 주석, 페이지 액션(전체 요청 표는 핵심 개념 → 뷰어 작동 방식에 있음). UnsafeMode가 false이면 문서 보안 레이어가 자동으로 앞에 연결됩니다.

참조 샘플은 위젯 요청을 경로 분기(branch)로 라우팅합니다:

csharp

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconutResources

text

IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)

DoconutOptions.ResourcesPath(기본값 /doconut-res)에 포함된 JS, CSS, 이미지 및 폰트를 제공합니다. 이러한 파일은 Viewer.ReferenceCss() / ReferenceScripts()가 태그를 생성하는 대상입니다.

UseDoconut() 호출 전에 항상 먼저 호출하세요. 뷰어 영역이 비어 있고 브라우저 콘솔에 /doconut-res/...에 대한 404 오류가 표시되면 이 호출이 누락되었거나 잘못된 위치에 있습니다.

Ordering recap

csharp

app.UseRouting();
app.UseSession();          // required when UnsafeMode = false
app.UseDoconutResources(); // 1st Doconut call
app.UseDoconut();          // 2nd Doconut call (or via a MapWhen branch)