이 페이지에는 두 가지 마이그레이션이 있습니다: .NET 8 내에서 패키지 버전 업그레이드와 오래된 Doconut 프레임워크(.NET 6, .NET Standard 2.0, .NET Framework 4.7)에서 .NET 8 API로 통합을 이동하는 것입니다.

패키지 버전 업그레이드

패키지를 업데이트합니다 (플러그인 패키지도 — 버전을 맞춰 유지).

bash

dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Dicom

라이선스 창을 확인하세요. 라이선스는 버전 범위를 포함합니다. 새 버전이 그 범위를 벗어나면 열기가 차단됩니다 — OpenDocumentAsync는 LicenseException을 발생시킵니다 (즉시 실패); 워터마크로 대체되지 않으며 IsVersionValid는 false가 됩니다. 라이선스를 갱신하고 .lic 파일을 교체한 뒤 애플리케이션을 재시작하면 AddDoconut()가 새 라이선스를 로드합니다.
재빌드하고 NuGet이 선언된 종속성 버전을 복원하도록 합니다 — System.Text.Json이나 System.Drawing.Common을 다시 고정하지 마세요 (다운그레이드 시 발생하는 정확한 오류는 Troubleshooting을 참조).
사용하는 각 포맷군마다 문서 하나씩 스모크 테스트를 수행합니다.

.NET 6 / .NET Standard 2.0 마이그레이션

.NET 8 API는 DI와 비동기를 중심으로 재설계되었습니다. 매핑은 다음과 같습니다:

구분	.NET 6 / Standard 2.0	.NET 8
설정	`Viewer(cache, httpContextAccessor, licensePath)` 생성	`builder.Services.AddDoconut(options => …)` + `Viewer` 주입
라이선스	정적 `Viewer.DoconutLicense(path)` + 플러그인당 `SetLicensePlugin(...)`	`options.LicensePath` / `LicenseContent` / `LicenseStream` — 하나의 라이선스, 플러그인 파일 자동 탐색
열기	`viewer.OpenDocument(...)` (동기)	`await viewer.OpenDocumentAsync(...)`
닫기	`viewer.CloseDocument()` 또는 `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer`는 IDisposable이 아님
수명	`Viewer`가 `IDisposable`을 구현하고 열려 있는 문서를 보유	`Viewer`는 무상태; 세션은 토큰 아래 캐시에서 관리
변환기	`viewer.Converter` 속성	Converter 플러그인 (`AddPlugin<ConverterPlugin>()`) + `DocumentConverter` 서비스
구성 클래스	`Doconut.Configs.View.*` 네임스페이스	모두 `Doconut` 네임스페이스에 포함
미들웨어	수동 핸들러 연결	`app.UseDoconutResources()` + `app.UseDoconut()`

전후 예시:

text

// .NET 6 (old API, shown for contrast — not valid on .NET 8)
using var viewer = new Viewer(cache, httpContextAccessor, "wwwroot/Doconut.Viewer.lic");
var token = viewer.OpenDocument(path, new PdfConfig { AllowSearch = true }, new DocOptions());

csharp

// .NET 8 — Viewer injected, license configured once in AddDoconut()
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

.NET Framework 4.7 (Web Forms) 마이그레이션

4.7 Viewer는 WebControl입니다; .NET 8은 컨트롤 모델을 미들웨어와 DI 서비스로 대체합니다:

<doconut:DocViewer runat=server> 컨트롤이 사라지고 — 페이지가 위젯 div 쌍을 호스팅하며 엔드포인트가 토큰을 반환합니다 (Quick Start에 패턴이 나와 있습니다).
정적 라이선스 메서드 → DoconutOptions 라이선스 소스.
동기 OpenDocument → await OpenDocumentAsync.
Viewer.ReferenceScripts() / ReferenceCss()는 양쪽 모두 존재하지만 — .NET 8 버전은 ScriptConfig/CssConfig 객체를 받아들이며 라이선스로 제한됩니다.
컨트롤 속성 (ShowThumbs, PageZoom, FixedZoom, …) → ViewerConfig 및 docViewer JS 옵션에서 동일한 이름으로 사용됩니다.
byte[]를 반환하는 내보내기 메서드 → Viewer의 비동기 주석 내보내기 API.

이 마이그레이션은 변경되지 않은 개념(열기 → 토큰 → 위젯)을 중심으로 호스팅 레이어를 재작성하는 것으로 계획합니다.

명명 규칙 참고

모든 프레임워크에서 클래스는 **Viewer**입니다 — 오래된 코드 조각이나 타사 기사에서 DocumentViewer를 발견한다면, 해당 타입은 SDK에 존재하지 않았습니다.

마이그레이션 체크리스트

패키지를 교체하고 플러그인 패키지 버전을 맞춥니다.
라이선스 설정을 AddDoconut()으로 옮기고 정적 라이선스 호출을 삭제합니다.
열기 호출을 비동기로 만들고 Dispose/인자 없는 CloseDocument를 CloseDocument(token)으로 교체합니다.
viewer.Converter 사용을 Converter 플러그인 등록 및 DocumentConverter로 교체합니다.
보안 경로를 다시 테스트합니다: 기본 보안에서는 이제 AddSession()/UseSession()이 필요합니다.