DoconutExtensions

서비스 및 미들웨어 등록

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

csharp
builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseSession();          // UseSession()을 먼저 호출하고 UseDoconut()을 호출하세요
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 → 세션 캐시 (IMemoryCache 도 등록됨)
IDoconutLicenseServiceSingleton시작 시 한 번 로드되는 라이선스 (우선순위: LicenseStream → LicenseContent → LicensePath → 자동 검색)
페이지 이미지 파이프라인Singleton페이지에 대한 이미지 처리 수행 (워터마크, 회전, 스케일, 주석)
문서 보안 (액세스 스토어)Singleton토큰-세션 바인딩을 위한 권한 부여
ViewerTransient공개 오픈/클로즈 파사드
DocumentConverterTransient변환 파사드 — Converter 플러그인 필요
DocumentSignerTransient서명 파사드 — Signer 플러그인 필요 (see Signer 플러그인)
DistributedDocumentPublisherTransient문서 아티팩트를 공유 스토리지에 게시
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>().

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

  • 플러그인 권한은 시작 시 검증됩니다. 라이선스가 없거나, 레거시 TRIAL 파일이 있거나, 등록된 플러그인 기능 없이 유료 라이선스인 경우 AddDoconut() 시점에 실패합니다. 임시/데모 등록은 만료 날짜까지 유지되며, 런타임 게이트는 만료된 기능을 취소합니다.

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

csharp
app.MapHealthChecks("/health");

UseDoconut

text
IApplicationBuilder UseDoconut(this IApplicationBuilder app)

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

인자는 없습니다. 여기서 DoconutOptions 인스턴스를 전달하는 것은 이전 라이브러리의 형태였으며 이제는 컴파일되지 않습니다.

일반적인 설정은 역사적인 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가 표시되면, 이 호출이 없거나 잘못된 위치에 있습니다.

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

공유 스토리지에서 제공

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

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

UseDoconutWebFarm(...) 와 WebFarmOptions 는 이번 릴리스에 존재하지 않습니다. 설정별 매핑을 보려면 마이그레이션 가이드 를 참조하십시오.

순서 요약

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

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