Doconut의 드롭‑인 변환기 위젯을 .NET 8에서 활성화하기
.NET 8에서 Doconut 드롭‑인 변환기 위젯 등록 및 활성화
드롭‑인 위젯은 파일을 업로드하고 변환을 실행하며 결과를 다운로드하기 위한 Doconut의 즉시 사용 가능한 UI입니다.
기본 상태에서 위젯의 세 개 ?convert= 엔드포인트는 404를 반환합니다; Converter 플러그인을 등록하고 AddConverterWidget()를 DoconutOptions에 호출할 때만 활성화됩니다.
아래는 두 요구 사항을 모두 만족하는 완전한 복사‑붙여넣기 가능한 시작 구성입니다.
1. 사전 요구 사항 – 라이선스 및 세션 지원
- License – Converter 플러그인은
Converter기능을 부여하는 라이선스가 필요합니다. 파일(예:Doconut.Viewer.lic)을 앱에서 접근 가능한 위치에 두고DoconutOptions.LicensePath를 해당 파일을 가리키도록 설정하세요. - Session state – Doconut의 보안 모델은 문서‑세션 토큰을 ASP.NET Core 세션에 저장합니다. 미들웨어가 연결되기 전에 분산 캐시와
AddSession()를 추가하세요.
builder.Services.AddDistributedMemoryCache(); // 세션에 필요
builder.Services.AddSession(); // IDistributedCache‑지원 세션을 활성화합니다
2. 핵심 Doconut 서비스 등록
AddDoconut()은 뷰어, 라이선스 서비스 및 플러그인 레지스트리를 주입하는 단일 진입점입니다.
builder.Services.AddDoconut(options =>
{
// Doconut에 라이선스 파일 위치를 알려줍니다.
options.LicensePath = "Doconut.Viewer.lic";
// Converter 플러그인을 등록합니다 – 이것은 라이선스 기능도 검증합니다.
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});
라이선스에 Converter 기능이 포함되지 않은 경우, 위 호출은 InvalidOperationException를 발생시키며 애플리케이션이 시작되지 않습니다. 이러한 빠른 실패 동작은 잘못된 라이선스 빌드 배포를 방지합니다.
3. AddConverterWidget으로 위젯 활성화
위젯은 선택적으로 활성화됩니다. AddConverterWidget()를 호출하면 세 개의 변환 엔드포인트(?convert=open, ?convert=run, ?convert=download)가 등록되고 클라이언트‑사이드 구성(최대 업로드 크기, 기본 경로 등)이 연결됩니다.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
// 드롭‑인 UI를 활성화하고 클라이언트‑사이드 업로드 제한을 설정합니다.
options.AddConverterWidget(widget =>
{
widget.MaxUploadMb = 25; // 클라이언트 사전‑검사; 서버는 자체 제한을 적용합니다
});
});
엔드포인트를 생성하는 것은 오직 AddConverterWidget 호출뿐이며, 정적 JavaScript 파일(doconutConverter.js)은 항상 임베디드 리소스로 제공되지만 엔드포인트가 없으면 서버와 연결에 실패합니다.
4. 올바른 순서로 미들웨어 연결
정적 자산을 제공하는 미들웨어(UseDoconutResources)는 터미널 뷰어 미들웨어(UseDoconut) 앞에 실행되어야 합니다. Doconut은 모든 요청에서 세션을 검증하므로 세션 미들웨어도 더 앞에 배치해야 합니다.
app.UseSession(); // UseDoconut()보다 먼저 호출되어야 합니다
app.UseDoconutResources(); // JS, CSS, 이미지 파일을 제공합니다
app.UseDoconut(); // ?convert= 및 문서 페이지 요청을 처리합니다
이 파이프라인이 구성되면 /doconut-res/doconutConverter.js에 대한 요청이 성공하고, 위젯은 /doconut?convert=open, /doconut?convert=run, 그리고 /doconut?convert=download를 호출할 수 있습니다.
5. 위젯이 실제로 수행하는 작업
| 단계 | 서버 엔드포인트 | 일반적인 응답 |
|---|---|---|
| Open | ?convert=open | JSON 페이로드를 반환하며, 여기에는 token, 페이지 수, 원본 확장자 및 허용된 대상 포맷 목록이 포함됩니다. |
| Run | ?convert=run | 변환을 시작하고 downloadToken, 결과 페이지 수, 제안 파일명, 그리고 출력에 워터마크가 있는지 여부를 나타내는 플래그를 반환합니다. |
| Download | ?convert=download | 클라이언트가 제공된 다운로드 URL을 따라가면 변환된 파일을 스트리밍합니다. |
클라이언트 측에서 위젯은 widget.MaxUploadMb에 대한 사전 업로드 크기 검사를 수행합니다. 파일이 해당 제한을 초과하면 위젯은 업로드를 중단하고 onError 콜백을 phase = "open"와 친절한 메시지와 함께 호출합니다. 서버는 자체 제한을 적용하며, 클라이언트 검사를 우회한 요청에 대해 413 Payload Too Large 응답을 반환합니다.
6. 위젯 이벤트 연결 (C# 측은 필요 없음)
모든 콜백(onReady, onSourceLoaded, onConverted, onError 등)은 위젯을 호스팅하는 페이지에서 제공하는 JavaScript 함수입니다. 질문이 등록 측면에 초점을 맞추고 있기 때문에, 해당 콜백을 처리하기 위해 추가적인 C# 코드를 작성할 필요가 없습니다—엔드포인트가 활성화되면 위젯이 자동으로 호출합니다.
7. 흔히 발생하는 함정 및 회피 방법
| 증상 | 가능한 원인 | 해결책 |
|---|---|---|
404 on /doconut?convert=open | AddConverterWidget()가 누락되었습니다. | 섹션 3에 표시된 대로 호출을 추가하세요. |
애플리케이션이 InvalidOperationException(누락된 기능) 때문에 시작에 실패 | 라이선스 파일이 Converter를 부여하지 않습니다. | Converter 기능을 포함하는 라이선스를 확보하세요. |
세션 관련 500 오류 | UseSession()가 UseDoconut() 뒤에 있거나 캐시 등록이 누락되었습니다. | app.UseSession()가 app.UseDoconut() 앞에 실행되고 캐시 서비스가 등록되었는지 확인하세요. |
8. 앱을 실행하고 위젯 동작 확인
- ASP.NET Core 프로젝트를 빌드하고 실행합니다.
<div id="doconut-convert"></div>요소를 포함하고 Doconut 변환기 스크립트를 포함하는 페이지를 엽니다(스크립트는/doconut-res/doconutConverter.js에서 자동으로 제공됩니다).- 지원되는 파일(PDF, DOCX, DWG 등)을 드롭 영역으로 끌어다 놓습니다.
- 위젯은
?convert=open를 호출하고, 다음으로?convert=run를 호출한 뒤, 최종적으로?convert=download을 가리키는 Download 링크를 표시합니다.
세 개의 엔드포인트가 404 대신 JSON으로 응답하면 위젯이 올바르게 등록된 것이며 프로덕션 사용 준비가 된 것입니다.
다음 단계: 위의 코드 조각을 Program.cs(또는 Startup.cs)에 추가하고, 라이선스 파일이 존재하는지 확인한 뒤 앱을 실행하세요. 드롭‑인 변환기 위젯이 추가적인 서버 측 변경 없이 바로 활성화됩니다.