DoconutExtensions

서비스 및 미들웨어 등록

DoconutExtensions (namespace 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 → Startup validation 참조), 전체 서비스 그래프를 등록합니다:

서비스수명역할
DoconutOptionsSingleton구성 객체
IViewerFactorySingleton확장자를 형식 뷰어에 매핑
IDocumentSessionManagerSingletonToken → 세션 캐시 (IMemoryCache도 등록됨)
IDoconutLicenseServiceSingleton시작 시 한 번 로드되는 라이선스 (우선순위: LicenseStream → LicenseContent → LicensePath → 자동 검색)
PageImageServiceSingleton페이지 이미지 파이프라인 (워터마크/회전/스케일/주석)
Document security (access store)SingletonToken-세션 바인딩을 위한 권한 부여
ViewerTransient공개 오픈/클로즈 파사드
DocumentConverterTransient변환 파사드 — Converter 플러그인이 필요합니다
DistributedDocumentPublisher—문서 아티팩트를 공유 스토리지에 게시
Health check "doconut"—ASP.NET 헬스 체크를 통해 라이선스/만료 상태 보고

이전 .NET Standard 라이브러리에는 동등한 호출이 없습니다. 해당 라이브러리는 요청당 new Viewer(cache, accessor) 를 생성하고 옵션을 미들웨어에 전달했으며, 이 두 작업이 이제 하나의 등록으로 대체되었습니다.

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

  • 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 인 경우, 문서 보안 레이어가 자동으로 앞에 연결됩니다.

인수를 받지 않습니다. 여기서 DoconutOptions 인스턴스를 전달하던 이전 라이브러리 방식은 더 이상 컴파일되지 않습니다.

참조 샘플은 위젯 요청을 경로 분기로 라우팅하여 기존 요청 형태를 유지합니다:

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 오류가 표시되면, 이 호출이 누락되었거나 잘못된 위치에 있습니다.

이는 app.UseMiddleware<EmbeddedResourceMiddleware>() 로 직접 임베디드 리소스 미들웨어를 연결하던 방식을 지원하는 대체 방법입니다.

Serving from shared storage

문서를 렌더링하는 노드가 반드시 페이지를 제공하는 노드와 동일하지 않을 수 있는 배포 환경을 위한 두 가지 추가 등록이 존재합니다. 두 경우 모두 분산 배포에서 처음부터 끝까지 다루며, 시그니처는 다음과 같습니다:

text
IServiceCollection AddDoconutDistributedAsyncPublish(...)   // opt-in background publish queue
IServiceCollection AddDoconutDistributedWidgets(...)        // shared backing store for widget uploads

읽기 측면은 Doconut.Clouds 패키지의 별도 미들웨어입니다:

text
IApplicationBuilder UseDoconutCloud<THandler>(
    this IApplicationBuilder app,
    Action<CloudOptions>? configure = null,
    string pathPrefix = "/doconut-cloud")
    where THandler : BaseCloudHandler

UseDoconutWebFarm(...) 및 WebFarmOptions 은 이번 릴리스에 포함되지 않았습니다. 설정별 매핑은 마이그레이션 가이드를 참고하세요.

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)

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