DoconutExtensions

서비스 및 미들웨어 등록

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

csharp
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession();          // UseDoconut() 전에 UseSession()을 호출하세요
app.UseDoconutResources(); // UseDoconut() 전에 등록되어야 합니다
app.Map("/doconut", branch => branch.UseDoconut());

UseDoconut()은 도달하는 모든 요청에 응답하므로, app.Map와 함께 자체 브랜치에 마운트하십시오.

AddDoconut

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

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

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

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

  • Converter는 플러그인이 필요합니다. DocumentConverter을 options.AddPlugin<ConverterPlugin>() 없이 해결하면 예외가 발생합니다:
text
InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

DocumentSigner도 동일한 규칙을 따릅니다: options.AddPlugin<SignerPlugin>() 없이이면 No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().를 발생시킵니다

  • 플러그인 권한은 시작 시 검증됩니다. 라이선스 누락, 레거시 TRIAL 파일, 또는 등록된 플러그인 기능 없이 유료 라이선스는 AddDoconut() 시점에 실패합니다. 임시/데모 등록은 만료일을 넘겨도 유지되며, 런타임 게이트는 만료된 기능을 회수합니다.

Health check는 표준 ASP.NET Core 메커니즘과 통합됩니다 — 라이선스 상태를 health 엔드포인트에 표시하려면 매핑하십시오:

csharp
app.MapHealthChecks("/health");

UseDoconut

text
IApplicationBuilder UseDoconut(this IApplicationBuilder app)

Doconut 페이지 이미지 미들웨어를 추가합니다. ?token= 쿼리 매개변수를 포함한 모든 요청(페이지, 썸네일, 검색, 주석, 페이지 액션 등; 전체 요청 표는 Core Concepts → How the Viewer Works에 있음)을 제공하고, 다른 모든 요청에는 404(또는 ShowDoconutInfo 배너)로 직접 응답합니다: 파이프라인의 나머지로 요청을 전달하지 않습니다. 이 페이지의 샘플과 같이 자체 브랜치에 마운트하십시오. UnsafeMode가 false이면, 문서 보안 레이어가 자동으로 그 앞에 연결됩니다.

일반적인 대안은 기존 DocImage.axd 요청 형태를 MapWhen 브랜치로 유지하는 것입니다(클라이언트는 이후 BasePath: '/'를 사용합니다):

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

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

text
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null)   // 옵트인 백그라운드 게시 큐
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure)                     // 위젯 업로드용 공유 백엔드 저장소

읽기 측은 동일 패키지에 포함된 Doconut.Clouds 어셈블리의 별도 미들웨어입니다:

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

Ordering recap

csharp
app.UseRouting();
app.UseSession();          // UseDoconut() 전에 UseSession()을 호출하세요
app.UseDoconutResources(); // UseDoconut() 전에 등록되어야 합니다
app.Map("/doconut", branch => branch.UseDoconut()); // 또는 MapWhen 분기

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