플러그인 시스템

플러그인을 사용하여 뷰어 확장

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 은 InvalidOperationException 를 Application_Start 로부터 발생시킵니다:

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(".dcm", () => new DicomViewer()) — 파일 확장자를 위한 뷰어,
  • builder.RegisterService<TContract>(() => …) — 파이프라인의 다른 부분이 조회할 수 있는 형식화된 서비스.

기능 및 게이팅

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

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

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

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

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

기능 및 플러그인 맵

기능활성화 방법기능 단위기여 내용
Annotation뷰어에 내장됨; 주석 리소스를 포함Annotation브라우저 저작, 세션 지속성, 내장된 내보내기
Search검색 가능한 형식 뷰어에 내장됨; 검색 리소스를 포함Search네이티브 텍스트 인덱스, 하이라이트, 결과 탐색
ConverterDoconut.NETFramework.Converter을 설치하고 ConverterPlugin을 등록ConverterC# 변환 서비스 및 선택적 웹 위젯
DICOMDoconut.NETFramework.Dicom을 설치하고 DicomPlugin을 등록Dicom.dcm 및 .ima용 의료 이미지 뷰어

Annotation 과 Search 는 AddPlugin<TPlugin>() 를 사용하지 않습니다. Converter 와 DICOM 은 각각 플러그인 아래 페이지가 있어 구성 및 사용법을 제공합니다. 이 패키지에서는 DICOM 이 페이지, 프레임, 애니메이션을 렌더링하지만 기술 메타데이터는 읽지 않습니다 — DICOM 플러그인을 참고하십시오.

사용자 정의 뷰어 — 자체 형식 핸들러

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

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

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

요약

  • 플러그인은 DoconutHost.Initialize 에 명시적으로 등록되며, 해당 기능이 그곳에서 검증됩니다; 권한이 누락되면 빈 500 로 사이트가 중단되고 원인은 Windows 이벤트 로그에 기록됩니다.
  • 재정의형 플러그인은 우아하게 감소하고, 플러그인 전용 포맷은 LicenseException 로 실패합니다.
  • 활성 임시 라이선스는 모든 것을 해제하고, 프로덕션 라이선스는 구매한 항목만 해제합니다. 배포 전에 IDoconutLicenseService 로 확인하십시오.

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