플러그인 시스템

플러그인으로 뷰어 확장

Doconut의 핵심은 간결하게 유지됩니다; 선택적 기능은 플러그인 형태로 제공됩니다 — 뷰어 또는 서비스를 제공하고 라이선스로 활성화되는 별도의 NuGet 패키지입니다. 이 페이지에서는 등록 모델, 라이선스가 플러그인을 포함하지 않을 때 시작 시 발생하는 일, 그리고 자체 뷰어를 연결하는 방법을 설명합니다.

플러그인 등록

각 플러그인 패키지는 하나의 플러그인 클래스를 노출합니다. Application_Start에 한 번 등록합니다:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});
// 라이선스가 누락된 등록된 플러그인은 Application_Start에서 여기에서 예외를 발생시키고,
// 사이트는 이후 모든 요청에 빈 500 응답을 반환합니다. 이유는 Windows 이벤트 로그에 있습니다.

AddPlugin<TPlugin>()은 플러그인을 생성하고 DoconutOptions를 통해 기여 내용을 등록하도록 합니다. 플러그인이 제공하는 모든 항목은 플러그인의 필수 기능으로 태그되며, DoconutHost.Initialize는 사이트가 첫 요청을 처리하기 전에 모든 등록된 플러그인을 라이선스와 비교하여 확인합니다.

플러그인 라이선스가 없으면 사이트가 중단됩니다

활성화된 라이선스가 등록된 플러그인의 기능을 부여하지 않을 경우 — 라이선스가 전혀 없거나, 레거시 TRIAL 파일이 있거나, 해당 기능이 없는 유료 라이선스인 경우 — DoconutHost.Initialize는 Application_Start에서 InvalidOperationException를 발생시킵니다:

text
The Converter plugin is registered via AddPlugin but no active license grants Converter.
Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

System.Web에서는 Application_Start에서 발생한 예외가 오류 페이지를 생성하지 않습니다. 모든 요청이 빈 500로 응답하고, IIS 로그에는 유용한 정보가 나타나지 않으며, 메시지는 Windows 이벤트 로그(응용 프로그램 로그, 소스 ASP.NET)에만 표시됩니다. 사이트가 AddPlugin 라인을 추가한 직후 응답을 멈추면, 먼저 wwwroot의 라이선스 파일을 확인하십시오 — 라이선스 설정 참고.

계약

플러그인은 의도적으로 작은 인터페이스를 구현합니다:

csharp
public interface IDoconutPlugin
{
    string Name { get; }                          // 예: "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // 라이선스 게이트
    void Register(IDoconutPluginBuilder builder); // 뷰어/서비스 기여
}

Register 내부에서 빌더는 두 종류의 기여를 허용합니다:

  • builder.RegisterViewer(extension, factory) — 파일 확장자를 위한 뷰어; 팩토리는 IFormatViewer를 반환합니다 (DICOM 플러그인은 이 방식으로 .dcm와 .ima를 등록합니다),
  • builder.RegisterService<TContract>(() => …) — 파이프라인의 다른 부분에서 조회할 수 있는 형식화된 서비스.

기능 및 게이팅

기능은 라이선스 단위입니다. Converter, Dicom 및 Signer는 선택적 플러그인으로 제공되며; Search와 Annotation는 동일한 방식으로 게이팅되는 기본 기능입니다. 기본 뷰어는 기능이 아니며 — 전제 조건으로, 라이선스 서비스에서 IsViewerLicensed로 노출됩니다.

시작 시 검증은 일반적으로 라이선스가 없는 플러그인을 요청 파이프라인에서 제외합니다. 뷰어 팩토리는 또한 두 가지 방어 규칙을 적용하는데, 이는 사이트가 실행되는 동안 권한이 변경될 경우 중요합니다:

  • 기본 뷰어를 재정의하는 플러그인 (기본 뷰어도 처리하는 확장자를 주장하는 경우): 기능이 라이선스된 경우 플러그인 뷰어가 우선합니다; 그렇지 않으면 Doconut는 기본 뷰어로 되돌아갑니다. 사용자는 여전히 문서를 볼 수 있지만 플러그인 동작은 적용되지 않습니다.
  • 플러그인 전용 포맷 (.dcm 및 .ima — DICOM에는 기본 뷰어가 없음): 기능이 없으면 열기가 실패합니다:
text
LicenseException: This document type requires the 'Dicom' plugin license.

활성화된 임시 라이선스는 모든 기능을 부여합니다. 이는 전형적인 실서비스 시 놀라움입니다: 평가 중에 실행된 동일한 AddPlugin 라인이 구매한 라이선스에서 해당 기능이 누락되면 사이트를 중단시킵니다. 배포 전에 구매한 내용과 IsCapabilityGranted(...)를 비교하십시오. 라이선스가 전혀 없으면 아무 것도 부여되지 않습니다 — 누락된 라이선스는 임시 라이선스가 아닙니다.

동일한 게이팅이 브라우저에도 적용됩니다: Viewer.ReferenceScripts()와 ReferenceCss()는 라이선스가 부여된 경우에만 라이선스 게이팅 기능(검색, 주석)의 파일을 내보내므로, 페이지가 서버가 거부할 기능을 제공하지 않습니다.

기능 및 플러그인 맵

기능활성화 방법권한기여 내용
주석뷰어에 내장; 주석 리소스 포함Annotation브라우저 저작, 세션 지속성, 내장된 내보내기
검색검색 가능한 포맷 뷰어에 내장; 검색 리소스 포함Search네이티브 텍스트 인덱스, 하이라이트, 결과 탐색
컨버터Doconut.NETFramework.Converter 설치 및 ConverterPlugin 등록ConverterC# 변환 서비스 및 선택적 웹 위젯
DICOMDoconut.NETFramework.Dicom 설치 및 DicomPlugin 등록Dicom.dcm 및 .ima용 의료 이미지 뷰어
서명기Doconut.NETFramework.Signer 설치 및 SignerPlugin 등록SignerPDF 및 Word용 가시 서명 및 디지털 씰: C# 서명 서비스 및 선택적 웹 위젯

주석 및 검색은 AddPlugin<TPlugin>()를 사용하지 않습니다. 컨버터, DICOM 및 서명기 각각은 플러그인 아래에 구성 및 사용법 페이지가 있습니다. 이 패키지에서는 DICOM이 페이지, 프레임 및 애니메이션을 렌더링하지만 기술 메타데이터는 읽지 않습니다 — DICOM 플러그인 참고.

맞춤 뷰어 — 자체 포맷 핸들러

플러그인 패키지를 작성하지 않고도 Application_Start에 직접 뷰어를 파이프라인에 연결할 수 있습니다:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),                        // IFormatViewer 구현
        () => new ImageConfig { ImageResolution = 150 });  // 옵션 기본 구성
});

// 팩토리가 생성하는 포맷 핸들러입니다. 이 멤버들을 여러분의 렌더링으로 교체하십시오.
public sealed class MyCustomViewer : Doconut.Core.Interfaces.IFormatViewer
{
    public ViewerType ViewerType => ViewerType.None;
    public int TotalPages => 0;
    public int DefaultWidth => 0;
    public int DefaultHeight => 0;
    public bool PreferOcr => false;

    public Task LoadAsync(Stream documentStream, BaseConfig config, CancellationToken ct = default)
        => Task.CompletedTask;

    public Task<byte[]> GetPageImageAsync(int pageNumber, CancellationToken ct = default)
        => Task.FromResult(Array.Empty<byte>());

    public void Dispose() { }
}

맞춤 뷰어는 모든 것 — 기본 및 플러그인 모두 — 보다 우선하며 라이선스 게이팅되지 않습니다: 이는 여러분의 코드입니다. 기본 구성을 제공하지 않으면 팩토리는 ImageConfig를 사용합니다.

핵심 요점

  • 플러그인은 DoconutHost.Initialize에 명시적으로 등록되며, 해당 위치에서 기능이 검증됩니다; 권한이 누락되면 빈 500와 함께 사이트가 중단되고 그 이유는 Windows 이벤트 로그에 기록됩니다.
  • 오버라이드 방식 플러그인은 정상적으로 감소하며; 플러그인 전용 포맷은 LicenseException로 실패합니다.
  • 활성화된 임시 라이선스는 모든 기능을 해제하고; 프로덕션에서는 구매한 기능만 해제됩니다. 배포 전에 IDoconutLicenseService를 확인하십시오.

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