이 페이지에는 두 가지 마이그레이션이 있습니다: .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.

이 작업은 변경되지 않은 개념을 중심으로 호스팅 레이어를 재작성하는 것으로 계획합니다: open → token → widget.

명명 규칙 참고

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

마이그레이션 체크리스트

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