두 가지 마이그레이션이 이 페이지에 포함됩니다: .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
설정	Construct `Viewer(cache, httpContextAccessor, licensePath)`	`builder.Services.AddDoconut(options => …)` + inject `Viewer`
라이선스	Static `Viewer.DoconutLicense(path)` + `SetLicensePlugin(...)` per plugin	`options.LicensePath` / `LicenseContent` / `LicenseStream` — one license, auto-discovery for plugin files
열기	`viewer.OpenDocument(...)` (synchronous)	`await viewer.OpenDocumentAsync(...)`
닫기	`viewer.CloseDocument()` or `viewer.Dispose()`	`viewer.CloseDocument(token)` — `Viewer` is not `IDisposable`
수명	`Viewer` implements `IDisposable`, holds the open document	`Viewer` is stateless; sessions live in the cache under tokens
컨버터	`viewer.Converter` property	The Converter plugin (`AddPlugin<ConverterPlugin>()`) + the `DocumentConverter` service
구성 클래스	`Doconut.Configs.View.*` namespaces	All in the `Doconut` namespace
미들웨어	Manual handler wiring	`app.UseDoconutResources()` + `app.UseDoconut()`

전형적인 전/후 예시:

text

// .NET 6 (구식 API, 대비를 위해 표시 — .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가 주입되고, 라이선스는 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 사용을 컨버터 플러그인 등록 + DocumentConverter 로 교체합니다.
보안 경로를 재테스트하십시오: 기본 보안에서는 이제 AddSession()/UseSession() 가 필요하며 (minimal-API 앱에서는 AddDistributedMemoryCache() 도 포함됩니다).