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`	Singleton	구성 객체
`IViewerFactory`	Singleton	확장자를 포맷 뷰어에 매핑
`IDocumentSessionManager`	Singleton	Token → 세션 캐시 (`IMemoryCache`도 등록됨)
`IDoconutLicenseService`	Singleton	시작 시 한 번 로드되는 라이선스 (우선순위: `LicenseStream` → `LicenseContent` → `LicensePath` → 자동 검색)
`PageImageService`	Singleton	페이지 이미지 파이프라인 (워터마크/회전/스케일/주석)
Document security (access store)	Singleton	Token-세션 바인딩을 위한 권한 부여
`Viewer`	Transient	공개 열기/닫기 파사드
`DocumentConverter`	Transient	변환 파사드 — 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= 쿼리 매개변수를 포함한 모든 요청에 응답합니다 — 페이지, 썸네일, 검색, 주석, 페이지 액션(전체 요청 표는 Core Concepts → How the Viewer Works에 있습니다). 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)