DoconutExtensions
서비스 및 미들웨어 등록
DoconutExtensions (namespace Doconut.Middleware)은 모든 Doconut 호스트가 수행하는 세 가지 호출을 가진 정적 클래스입니다: 하나의 서비스 등록과 두 개의 미들웨어 등록.
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession(); // UseDoconut() 전에 UseSession()을 호출하세요
app.UseDoconutResources(); // UseDoconut() 전에 등록되어야 합니다
app.Map("/doconut", branch => branch.UseDoconut());UseDoconut()은 도달하는 모든 요청에 응답하므로, app.Map와 함께 자체 브랜치에 마운트하십시오.
AddDoconut
IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)DoconutOptions을(를) 빌드하고, 즉시 실패하도록 검증하며(DoconutOptions → Startup validation 참조), 전체 서비스 그래프를 등록합니다:
| 서비스 | 수명 | 역할 |
|---|---|---|
DoconutOptions | Singleton | 구성 객체 |
| 세션 캐시 서비스 | Singleton | Token → session cache (IMemoryCache도 등록됨) |
IDoconutLicenseService | Singleton | 시작 시 한 번 로드되는 라이선스 (우선순위: LicenseStream → LicenseContent → LicensePath → 자동 검색) |
| 페이지 이미지 파이프라인 | Singleton | 페이지에 대한 이미지 처리 수행(워터마크, 회전, 스케일, 주석) |
| 문서 보안 (액세스 스토어) | Singleton | 토큰-세션 바인딩에 대한 권한 부여 |
Viewer | Transient | 공개 열기/닫기 파사드 |
DocumentConverter | Transient | 변환 파사드 — Converter 플러그인 필요 |
DocumentSigner | Transient | 서명 파사드 — Signer 플러그인 필요 (see Signer 플러그인) |
DistributedDocumentPublisher | Transient | 문서 아티팩트를 공유 스토리지에 게시 (see 분산 배포) |
Health check "doconut" | — | ASP.NET health check를 통해 라이선스/만료 상태 보고 |
알아두면 좋은 두 가지 동작:
- Converter는 플러그인이 필요합니다.
DocumentConverter을options.AddPlugin<ConverterPlugin>()없이 해결하면 예외가 발생합니다:
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 엔드포인트에 표시하려면 매핑하십시오:
app.MapHealthChecks("/health");UseDoconut
IApplicationBuilder UseDoconut(this IApplicationBuilder app)Doconut 페이지 이미지 미들웨어를 추가합니다. ?token= 쿼리 매개변수를 포함한 모든 요청(페이지, 썸네일, 검색, 주석, 페이지 액션 등; 전체 요청 표는 Core Concepts → How the Viewer Works에 있음)을 제공하고, 다른 모든 요청에는 404(또는 ShowDoconutInfo 배너)로 직접 응답합니다: 파이프라인의 나머지로 요청을 전달하지 않습니다. 이 페이지의 샘플과 같이 자체 브랜치에 마운트하십시오. UnsafeMode가 false이면, 문서 보안 레이어가 자동으로 그 앞에 연결됩니다.
일반적인 대안은 기존 DocImage.axd 요청 형태를 MapWhen 브랜치로 유지하는 것입니다(클라이언트는 이후 BasePath: '/'를 사용합니다):
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());UseDoconutResources
IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)DoconutOptions.ResourcesPath(기본값 /doconut-res)에서 임베드된 JS, CSS, 이미지 및 폰트를 제공합니다. 이러한 파일들은 Viewer.ReferenceCss() / ReferenceScripts()가 태그를 내보내는 대상입니다.
UseDoconut()보다 먼저 호출해야 합니다. 뷰어 영역이 비어 있고 브라우저 콘솔에 /doconut-res/...에 대한 404가 표시되면, 이 호출이 누락되었거나 잘못된 위치에 있습니다.
Serving from shared storage
문서를 렌더링하는 노드가 페이지를 제공하는 노드와 반드시 동일하지 않은 배포를 위해 두 개의 추가 등록이 존재합니다. 두 경우 모두 분산 배포에서 끝까지 다루며, 시그니처는 다음과 같습니다:
IServiceCollection AddDoconutDistributedAsyncPublish(this IServiceCollection services, Action<DistributedAsyncPublishOptions>? configure = null) // 옵트인 백그라운드 게시 큐
IServiceCollection AddDoconutDistributedWidgets(this IServiceCollection services, Action<DistributedWidgetsOptions> configure) // 위젯 업로드용 공유 백엔드 저장소읽기 측은 동일 패키지에 포함된 Doconut.Clouds 어셈블리의 별도 미들웨어입니다:
IApplicationBuilder UseDoconutCloud<THandler>(
this IApplicationBuilder app,
Action<CloudOptions>? configure = null,
string pathPrefix = "/doconut-cloud")
where THandler : BaseCloudHandlerOrdering recap
app.UseRouting();
app.UseSession(); // UseDoconut() 전에 UseSession()을 호출하세요
app.UseDoconutResources(); // UseDoconut() 전에 등록되어야 합니다
app.Map("/doconut", branch => branch.UseDoconut()); // 또는 MapWhen 분기이 페이지가 도움이 되었나요?