클래식 .NET 6 통합에서 마이그레이션하기

Doconut은 두 가지 별도 .NET 6 통합 방식을 제공합니다. 동일한 Doconut.NET6 패키지 이름을 사용할 수 있으므로, 패키지, 시작 설정, 라이선스 또는 브라우저 리소스를 변경하기 전에 애플리케이션 내 API가 어느 세대에 속하는지 확인하십시오.

어떤 .NET 6 통합을 사용하고 있나요?

두 열이 동일 애플리케이션에 모두 나타나는 경우, 마이그레이션이 완전하지 않은 것으로 간주하고, 한 세대의 리소스나 미들웨어를 통해 다른 세대의 문서 토큰을 전송하지 마세요.

NuGet 패키지 이름만으로는 알 수 없는 이유

두 세대 모두 Doconut.NET6 패키지 ID 아래에서 배포되었습니다. 패키지 참조, lock 파일, 혹은 캐시된 .nupkg만으로는 어떤 호스팅 API를 사용하는지 판단할 수 없습니다. 정확한 패키지 버전을 기록하고 Program.cs, Viewer 생성, 문서 열기, 브라우저 스크립트를 함께 확인하십시오.

이 가이드에서 검토된 현재 릴리스는 Doconut.NET6 26.7.0입니다. 선택적인 공개 패키지는 Doconut.NET6.Converter와 Doconut.NET6.Dicom이며, 코어 패키지와 동일한 릴리스 버전으로 고정됩니다.

마이그레이션 전 준비 사항

1. 기존 애플리케이션의 브랜치를 만들고 배포 가능한 백업을 생성합니다.
2. 정확한 코어 및 플러그인 패키지 버전을 기록합니다.
3. 모든 DocImage.axd 매핑, new Viewer(...) 호출, 라이선스 로드 호출, 복사된 Doconut 스크립트, 사용자 정의 툴바 액션, 문서 열기 엔드포인트를 조사합니다.
4. 현재 .lic 파일과 배포 비밀 정보를 소스 제어 외부에 보관합니다.
5. PDF, Office, 이미지, CAD, 이메일, DICOM, 검색 가능, 비밀번호 보호, 주석이 포함된 문서 샘플을 대표적으로 수집합니다.
6. 기존 세션 타임아웃, 보안 동작, 폰트, 플랫폼 설정을 기록합니다.

프로덕션을 변경하기 전에 하나의 환경에서 먼저 마이그레이션을 수행하십시오. 현재 통합은 서비스 수명, 요청 라우팅, 세션 소유권, 클라이언트 리소스 전달 방식을 변경합니다.

패키지 및 라이선스 호환성

코어 패키지를 고의적으로 교체하거나 업데이트하십시오; 동일한 패키지 ID에 의존해 새 API를 선택하지 마세요. 기본 명령은 최신 안정 버전을 설치합니다:

dotnet add package Doconut.NET6

이 가이드에서 검증된 릴리스로 재현 가능한 마이그레이션을 위해 버전을 별도 옵션으로 지정합니다:

dotnet add package Doconut.NET6 --version 26.7.0

모든 Doconut 플러그인은 코어 패키지와 동일한 버전을 유지하십시오. 현재 통합은 AddDoconut() 실행 시 한 번 라이선스를 로드하며, 다음과 같은 우선순위를 사용합니다:

LicenseStream > LicenseContent > LicensePath > automatic discovery

자동 검색은 Doconut.Viewer.lic 및 동반 Doconut.Viewer.<Capability>.lic 파일을 찾습니다. Viewer.DoconutLicense(...) 또는 Viewer.SetLicensePlugin(...) 호출은 현재 시작 메커니즘이 아니므로 사용하지 마세요. 라이선스를 DoconutOptions에 이동하고, 자동 검색을 사용할 경우 동반 파일을 함께 두며, 라이선스를 변경한 뒤에는 재시작하고 IDoconutLicenseService를 통해 기능을 확인하십시오.

오래된 플러그인 라이선스가 현재 플러그인 빌드에 대한 권한을 자동으로 부여한다고 가정하지 마세요. Viewer, Search, Annotation, Converter, DICOM을 각각 승인된 릴리스 아티팩트로 테스트하십시오.

시작 및 의존성 주입

클래식 애플리케이션은 ASP.NET 캐시와 요청 접근자 의존성을 사용해 Viewer를 직접 생성합니다:

// Classic integration — contrast only; do not compile this against the current SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

현재 통합은 Doconut을 한 번 등록하고 DI를 통해 Viewer를 받아옵니다:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.UnsafeMode = false;
});
builder.Services.AddSession();

app.UseSession();
app.UseDoconutResources();
app.UseDoconut();

Viewer는 전형적인 Transient 서비스입니다. 문서 세션 관리자와 그 캐시가 장기적인 문서 상태를 소유하며, 특정 주입된 Viewer 인스턴스는 그렇지 않습니다.

미들웨어 및 리소스 라우팅

DocImage.axd를 감지하는 클래식 MapWhen 분기를 제거합니다:

// Classic integration — remove during the cutover.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

현재 파이프라인에서는:

1. 세션 보안이 활성화된 상태에서 Doconut 이전에 UseSession()을 호출합니다;
2. UseDoconutResources()를 UseDoconut() 앞에 호출합니다;
3. ResourcesPath, 생성된 리소스 URL, 클라이언트 ResPath를 일치시킵니다;
4. UseDoconut()를 브랜치에 매핑할 때 해당 브랜치와 클라이언트 BasePath를 일치시킵니다.

MiddlewarePath는 검증된 설정이며, 자체적으로 ASP.NET Core 브랜치를 생성하지 않습니다. 위의 컴파일 샘플에 있는 간단한 파이프라인을 사용하거나, 클라이언트에서 일관되게 사용하는 app.Map("/doconut", branch => branch.UseDoconut()) 구성을 사용하십시오.

Viewer 생성 및 수명 주기

Viewer 객체에 대한 애플리케이션 소유 캐시를 제거합니다. 엔드포인트, Razor 페이지, 컨트롤러, 혹은 스코프된 애플리케이션 서비스에 Viewer를 주입하십시오:

app.MapPost("/api/open", async (Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

반환된 토큰은 서버 측 문서 세션을 식별합니다. 이를 베어러 자격 증명으로 취급하고, 로그에 남기거나 영구 저장하거나 분석에 포함시키지 마세요.

문서 열기 및 닫기

동기식 OpenDocument(...)를 OpenDocumentAsync(...)로 교체합니다:

// Current .NET 6 integration: Viewer comes from DI and document opening is asynchronous.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

현재 오버로드는 파일 경로나 스트림, 선택적 포맷 설정, 선택적 DocOptions, 그리고 취소 토큰을 받습니다. 브라우저가 더 이상 필요하지 않을 때 서버 세션을 명시적으로 닫으십시오:

viewer.CloseDocument(token);

컷오버 후에는 클래식 토큰을 재사용하지 마세요. 현재 API를 통해 각 문서를 다시 열어야 합니다.

구성 클래스

현재 API는 관심사를 분리합니다:

렌더링 제어로 DocOptions.ImageResolution을 그대로 전달하지 마세요. 이는 폐기된 항목이며, 포맷별 설정의 BaseConfig.ImageResolution을 사용하십시오. 모든 기본값을 검토하고 클래식 설정이 동일하게 동작한다고 가정하지 마세요.

Viewer 툴바, Search, Annotation

구식 스크립트를 하나씩 마이그레이션하지 마세요. 현재 레퍼런스 애플리케이션은 하나의 완전한 페이지 패키지를 구성합니다:

1. ReferenceCss로 Viewer CSS와 라이선스가 적용된 Search/Annotation CSS를 출력합니다;
2. 애플리케이션 소유 Viewer 툴바를 렌더링합니다;
3. searchBarMount, annBarMount, 그리고 필요한 Viewer 마운트를 렌더링합니다;
4. ReferenceScripts로 Viewer와 라이선스가 적용된 모듈 스크립트를 출력합니다;
5. 애플리케이션 자체 viewerToolbar.js를 로드합니다;
6. 하나의 objViewer를 초기화합니다;
7. 라이선스가 적용된 Search와 Annotation 리본을 초기화합니다;
8. 각 리본에 attach(objViewer)를 호출합니다;
9. 문서를 열고 objViewer.View(token)을 호출합니다.

Search와 Annotation은 동일 Viewer에 부착되는 모듈이며, 독립적인 툴바가 아닙니다. 메인 툴바는 호스트 애플리케이션에 속하고, Search와 Annotation 리본은 임베드된, 기능에 따라 게이트된 리소스입니다.

documentLinks.js와 docViewer.UI.js와 같은 클래식 파일은 ReferenceCss와 ReferenceScripts가 출력하는 리소스로 현재 페이지가 정상 동작한 뒤에만 삭제하십시오.

플러그인 등록

클래식 정적 플러그인‑라이선스 메서드는 현재 플러그인을 등록하지 않습니다. 각 릴리스된 패키지를 명시적으로 설치하고 등록하십시오:

builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddDoconut()는 시작 시 등록된 플러그인 기능을 검증합니다. Converter와 DICOM은 .NET 6용으로 릴리스된 플러그인입니다. 일반 Search와 Annotation은 내장된 라이선스 기능이며 AddPlugin<TPlugin>() 패키지가 아닙니다.

세션 및 문서 보안

현재 통합은 문서를 불투명 토큰과 캐시된 세션에 바인딩합니다. UnsafeMode = false가 기본값인 경우, UseDoconut()는 문서 접근 보안을 추가하며 호스트는 ASP.NET 세션을 구성해야 합니다:

builder.Services.AddSession();
app.UseSession();

DocOptions.IsSecured = true를 유지하십시오(검토된 설계에서 별도 요구가 없는 한). 마이그레이션 지름길로 UnsafeMode = true를 절대 사용하지 마세요. 토큰이 없거나, 형식이 잘못됐거나, 만료됐거나, 다른 브라우저 세션에서 온 경우를 모두 테스트하십시오.

Distributed 레퍼런스 애플리케이션은 접근 티켓과 전송 세부 정보를 추가합니다. 일반 단일 노드 마이그레이션에는 필요하지 않습니다.

마이그레이션 테스트

최소한 다음을 검증하십시오:

• 프로덕션 라이선스와 모든 등록 플러그인으로 애플리케이션이 정상 시작되는지
• 선택된 경로 아래 Viewer CSS/스크립트와 모든 페이지 이미지 요청이 정상인지
• 문서 열기, 탐색, 확대/축소, 썸네일, 인쇄, 명시적 닫기 기능
• 텍스트가 포함된 문서에서 Search 동작 및 이미지 전용 파일에서 검색 불가 상태
• Annotation 로드, 저장, 내보내기 및 기능 게이트
• Converter 대상 탐색, 출력, 다운로드 및 워터마크 상태
• DICOM 페이지, 프레임, 애니메이션; .NET 6 기술 메타데이터는 제공되지 않음
• 비밀번호 보호 문서, 사용자 정의 폰트, 비라틴 문자, 구성된 타임아웃
• 세션 간 토큰 거부 및 만료된 세션 동작
• 모바일, 다크 모드, 프로덕션 리버스 프록시 경로

롤백 계획

클래식 배포 아티팩트, 일치하는 패키지, 라이선스 파일, 복사된 브라우저 리소스를 함께 보관하십시오. 안전한 롤백은 전체 애플리케이션 세대를 전환하는 것이며, 클래식 서버와 현재 스크립트를 혼합하거나 현재 서버와 클래식 DocImage.axd 호출을 혼합하지 않습니다.

컷오버 전에는 다음을 문서화하십시오:

• 롤백에 사용할 배포 슬롯 또는 아티팩트
• 데이터베이스/캐시 영향(있는 경우)
• 활성 문서 세션을 어떻게 무효화할지
• 롤백 결정을 위한 헬스 체크 및 스모크 문서
• 이전 패키지 세트와 구성을 복원할 수 있는 담당자

레거시 문서

번역된 클래식 매뉴얼은 Legacy .NET 6 setup에서 확인할 수 있습니다. 새로운 Classic integration gateway에서는 동일한 식별 신호를 설명하고 이 마이그레이션 가이드로 다시 연결합니다.

클래식 설치가 아직 존재하는 동안 즐겨찾기와 지원 티켓에 히스토리 URL을 유지하십시오. 해당 URL은 다른 세대를 문서화하며 현재 API로 리다이렉트되지 않습니다.