클래식 .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을 각각 테스트하십시오.

시작 및 의존성 주입

클래식 애플리케이션은 Viewer를 ASP.NET 캐시와 요청 접근자 종속성으로 구성합니다:

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

현재 통합은 Doconut을 한 번 등록하고 의존성 주입으로 Viewer를 받아옵니다:

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

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

Viewer는 일시적인 서비스입니다. 문서 세션 관리자와 그 캐시가 더 오래 지속되는 문서 상태를 소유하며, 특정 주입된 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. UseDoconut() 이전에 UseDoconutResources()를 호출합니다;
3. ResourcesPath와 생성된 리소스 URL, 클라이언트 ResPath가 일치하도록 유지합니다;
4. UseDoconut()를 브랜치에 매핑할 때, 해당 브랜치와 클라이언트 BasePath가 일치하도록 유지합니다.

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

Viewer 구성 및 수명

Viewer 객체에 대한 애플리케이션 소유 캐시를 제거합니다. Viewer를 엔드포인트, Razor 페이지, 컨트롤러 또는 범위가 지정된 애플리케이션 서비스에 주입합니다:

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 툴바, 검색 및 주석

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

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 리본은 임베드된 기능 기반 리소스입니다.

ReferenceCss와 ReferenceScripts가 내보낸 리소스로 현재 페이지가 정상 동작한 후에만 documentLinks.js와 docViewer.UI.js와 같은 클래식 파일을 수동으로 복사한 것을 제거하십시오.

플러그인 등록

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

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

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

세션 및 문서 보안

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

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

DocOptions.IsSecured = true를 유지하십시오(검토된 설계에서 달리 요구되지 않는 한). 마이그레이션 단축키로 UnsafeMode = true를 절대 사용하지 마십시오. 토큰이 없거나, 형식이 잘못되었거나, 만료된 토큰이거나, 다른 브라우저 세션에서 온 토큰에 대한 요청을 테스트하십시오.

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

마이그레이션 테스트

최소한 다음을 확인하십시오:

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

롤백 계획

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

전환 전, 다음을 문서화하십시오:

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

레거시 문서

번역된 클래식 매뉴얼은 레거시 .NET 6 설정에서 계속 이용할 수 있습니다. 새로운 클래식 통합 게이트웨이는 동일한 식별 신호를 설명하고 이 마이그레이션 가이드로 다시 연결됩니다.

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