DoconutExtensions

서비스 및 미들웨어 등록

DoconutExtensions (namespace Doconut.Middleware) 은(는) 모든 Doconut 호스트가 수행하는 세 가지 호출을 포함하는 정적 클래스이며, 하나는 서비스 등록이고 두 개는 미들웨어 등록입니다.

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

AddDoconut

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

DoconutOptions 를 구축하고, 즉시 실패하도록 검증하며 (DoconutOptions → Startup validation 참조), 전체 서비스 그래프를 등록합니다:

서비스수명역할
DoconutOptionsSingleton구성 객체
세션 캐시 서비스SingletonToken → 세션 캐시 (IMemoryCache 가 또한 등록됩니다)
IDoconutLicenseServiceSingleton시작 시 한 번 로드되는 라이선스 (우선순위: LicenseStream → LicenseContent → LicensePath → 자동 검색)
페이지 이미지 파이프라인Singleton페이지에 대한 이미지 처리 수행 (워터마크, 회전, 스케일, 주석)
문서 보안 (액세스 스토어)Singleton토큰-세션 바인딩을 위한 권한 부여
ViewerTransient공개 열기/닫기 파사드
DocumentConverterTransient변환 파사드 — Converter 플러그인 필요
DistributedDocumentPublisher—문서 아티팩트를 공유 스토리지에 게시
Health check "doconut"—ASP.NET 헬스 체크를 통해 라이선스/만료 상태 보고

이전 .NET Standard 라이브러리에는 동등한 호출이 없습니다. 요청당 new Viewer(cache, accessor) 를 생성하고 옵션을 미들웨어에 전달했으며; 이 두 가지가 이 단일 등록으로 대체됩니다.

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

  • Converter는 플러그인이 필요합니다. DocumentConverter 를 options.AddPlugin<ConverterPlugin>() 없이 해결하면 예외가 발생합니다:
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 인스턴스를 전달하던 이전 라이브러리 방식은 더 이상 컴파일되지 않습니다.

참조 샘플은 위젯 요청을 경로 분기(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 오류가 표시되면, 이 호출이 누락되었거나 잘못된 위치에 있습니다.

이는 임베디드 리소스 처리 미들웨어를 수동으로 연결하는 대신 지원되는 대체 방법입니다.

Serving from shared storage

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

text
IServiceCollection AddDoconutDistributedAsyncPublish(...)   // 옵트인 백그라운드 게시 대기열
IServiceCollection AddDoconutDistributedWidgets(...)        // 위젯 업로드를 위한 공유 백업 저장소

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

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

UseDoconutWebFarm(...) 및 WebFarmOptions 은 이 릴리스에 존재하지 않습니다. 설정별 매핑은 migration guide 를 참조하세요.

Ordering recap

csharp
app.UseRouting();
app.UseSession();          // UnsafeMode = false일 때 필수
app.UseDoconutResources(); // 1st Doconut 호출
app.UseDoconut();          // 2nd Doconut 호출 (또는 MapWhen 분기)

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