마이그레이션

이 페이지는 기존 ASP.NET 애플리케이션을 Doconut.NETFramework 26.8.0 또는 이전 버전(.NET Framework 4.7)에서 26.9.0 및 이후 버전(.NET Framework 4.7.2)으로 업그레이드하는 방법을 다룹니다. Doconut 샘플 패키지는 전체 마이그레이션 가이드를 포함하고 있으며, 새로운 API로 포팅된 클래식 샘플—MVC 5, 웹 팜, Web Forms—도 제공합니다. 시작 샘플과 애플리케이션을 비교(diff)하는 것이 가장 빠른 방법입니다.

하나의 패키지, 두 버전

두 라이브러리 모두 동일한 패키지 ID인 Doconut.NETFramework로 배포됩니다. 버전이 구분을 합니다:

패키지를 업데이트하는 것이 업그레이드입니다. 별도의 설치 패키지나 호환성 레이어가 없습니다: 26.9.0은 다른 API 표면이므로 업데이트 후 컴파일 오류가 발생할 수 있습니다—이 페이지의 나머지 부분을 참고하십시오. .NET Framework 4.7 라인은 중단되었으며 26.8.0이 마지막 릴리스입니다. 계속 사용할 수는 있지만—여기에는 놓칠 보안 수정 사항이 없습니다—새로운 릴리스, 플러그인, 분산 모드 및 드롭인 위젯은 26.9.0 및 이후 버전에서만 제공됩니다.

1. 대상 재설정 및 패키지 업데이트

먼저 웹 프로젝트의 대상 프레임워크를 .NET Framework 4.7.2로 변경하십시오: 여전히 4.7을 대상으로 하는 프로젝트는 26.9.0을 설치할 수 없으며 NuGet이 업데이트를 거부합니다. 그런 다음 Doconut.NETFramework를 업데이트하고 사용 중인 플러그인 패키지(Doconut.NETFramework.Converter, Doconut.NETFramework.Dicom, …)를 추가합니다. 각 플러그인에는 해당 라이선스가 필요합니다.

프로젝트가 packages.config를 사용하는 경우, 업데이트 과정에서 이전 버전의 제거 단계가 실행되어 Web.config에서 DocImage 핸들러가 제거되고 26.9.0에서는 다시 추가되지 않습니다. 3단계에 표시된 대로 다시 등록하십시오; 그렇게 할 때까지 DocImage.axd는 404 응답을 반환하고 페이지가 표시되지 않습니다.

2. 네임스페이스: 거의 모든 것이 루트로 이동

형식 이름은 변경되지 않았습니다: WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, FileShareConfig 및 나머지도 모두 여전히 존재합니다. 대부분의 파일에서는 전체 편집이 using 라인을 삭제하는 것입니다.

3. 시작: DoconutHost.Initialize 및 두 개의 Web.config 항목

클래식 패키지는 요청마다 뷰어를 생성했으며, 옵션은 해당 인스턴스의 속성으로 제공되었습니다. 새 패키지는 Application_Start에서 한 번만 구축되는 컴포지션 루트를 가지고 있으며, 뷰어는 해결(resolve)하는 서비스입니다:

// 이전 - Doconut.NETFramework 26.8.0 및 이전 버전, 요청에 따라
var viewer = new Viewer
{
    ID = "ctlDoc",
    IncludeJQuery = true,
    BasePath = "/",
    FitType = "width"
};

// Doconut.NETFramework 26.9.0\u002B - Viewer가 DoconutHost에서 해결되고, 라이선스는 DoconutHost.Initialize()에서 한 번 구성됩니다
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
var token  = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

DoconutHost.Initialize는 Application_Start에, DoconutHost.Shutdown는 Application_End에 넣으며, Web.config는 DocImage.axd 핸들러와 리소스 모듈을 얻습니다 — 두 항목 모두 설치 에 있습니다. 페이지별 표시 설정(FitType, FixedZoom, ShowHyperlinks, …)은 뷰어 인스턴스에서 위젯 옵션으로, 또는 Viewer.RenderViewer에 전달되는 ViewerConfig로 이동했습니다(ViewerConfig 참고). new Viewer()는 DoconutHost.Initialize가 실행된 후에도 계속 컴파일되므로, 마이그레이션된 코드 비하인드에서 해당 라인을 유지하면서 설정을 이동할 수 있습니다.

보안은 이전과 동일하게 작동합니다. 문서를 열면 현재 ASP.NET 세션에 해당 페이지에 대한 접근 권한이 부여되고, DocImage.axd는 다른 모든 사용자를 거부합니다. 이 기능을 끈 DoconutUnSafeMode 앱 설정은 이제 DoconutHost.Initialize의 options.UnsafeMode에 있습니다 — 그대로 false 상태로 두세요. 보세요 세션 및 보안.

전체 사이트를 중단시키는 시작 실패
라이선스가 부여되지 않은 기능을 가진 등록된 플러그인이 Application_Start에서 예외를 발생시키고, 애플리케이션은 모든 요청에 대해 빈 500을 반환합니다 — 오류 페이지도 없고 IIS 로그에도 기록되지 않으며, Windows 이벤트 로그(소스 ASP.NET)에만 항목이 남습니다. 라이선스는 사이트 루트 아래의 wwwroot에서만 읽히며 다른 곳에서는 읽히지 않으며, 기본 Doconut.Viewer.lic가 존재해야 플러그인 라이선스가 함께 읽힙니다. 보세요 라이선스 설정.

4. 웹 팜: 플래그에서 분산 모드로

클래식 모델은 viewer.IsWebfarm = true와 ExportToPng(path)였습니다. 새로운 모델은 한 번만 등록됩니다: 모든 노드가 하나의 스토어와 하나의 서명 키를 공유하고, 브라우저에 바인딩된 서명된 티켓이 "어느 노드가 응답하든"을 대체합니다:

Doconut.DoconutHost.Initialize(
    options => options.UnsafeMode = false,
    services => services.AddDoconutDistributed(d =>
    {
        d.Store             = CloudLocation.FileShare;
        d.FileShareRootPath = @"\\fileserver\doconut-shared";   // WebfarmPath은 별칭입니다
        d.SigningKey        = farmKey;                           // >= 32 bytes, 모든 노드에서 동일합니다
    }));

그런 다음 문서를 일반적으로 열고, 브라우저 (DocOptions.BrowserId = DoconutFarmBinding.EnsureBrowserId(...))를 바인딩하고 토큰과 함께 위젯에 viewer.AccessToken를 전달합니다. 세션 및 보안 에 단계가 있습니다; 웹 팜 샘플은 완전한 노드입니다. IsWebfarm와 WebfarmPath는 여전히 컴파일되지만, 이제는 아무것도 전환하지 않습니다.

성공처럼 보이지만 실제는 아닌 두 가지가 있습니다: DistributedDocumentPublisher.PublishAsync은 문서의 렌더링된 파일을 기록하지만 세션을 열지 않으므로, 발행된 토큰을 가리키는 뷰어는 상태 200과 함께 ~2KB 오류 이미지를 받습니다; 그리고 doconut-client 쿠키가 없는 테스트 클라이언트는 같은 이미지를 받으며, 401를 받지 않습니다. 실제 페이지와 오류 이미지를 크기로 구분하십시오.

5. 변환은 플러그인이며, 훨씬 작습니다

SourceFormatConverter 열거형, 열두 개의 *ConfigConverter 클래스 및 그들의 중첩된 대상 열거형은 하나의 열거형 ConversionTarget와 하나의 호출로 대체됩니다:

using System.IO;
using System.Threading;
using Doconut;
using Doconut.Configs.Conversion;

// DoconutHost가 이미 초기화되어 있고 ct라는 CancellationToken이 사용 가능하다고 가정합니다.
var provider = DoconutHost.Services;
var converter = (DocumentConverter)provider.GetService(typeof(DocumentConverter));
Stream source = /* 입력 스트림 */;
var result = await converter.ConvertAsync(source, ".dwg", ConversionTarget.Pdf, null, ct);

소스 형식은 전달한 확장자에서 옵니다. 호환성 shim은 없습니다: 모든 SourceFormatConverter 참조는 컴파일 오류이며, 이를 삭제함으로써 해결합니다. 포맷별 옵션 객체는 살아남지 못했습니다 — WordConfigConverter.HtmlOptions와 CadConfigConverter.CadOptions.ShowColor는 ConvertAsync를 통해 동등한 것이 없습니다. Web Forms에서는 절대 ConvertAsync에 블록을 걸지 마세요 — 컨버터 플러그인을 참고하십시오.

6. 클라우드 스토리지: 공유 폴더로 접근하기

클라우드 구성 유형은 Doconut.Clouds로 그대로 이동했습니다. 그러나 클라우드 요청 핸들러는 ASP.NET Core 구성 요소이며, 클래식 애플리케이션에는 이를 실행할 파이프라인이 없습니다. System.Web 사이트에서 클라우드 스토리지를 공유 폴더로 접근합니다 — Azure에서는 각 노드에 마운트된 Azure Files 공유이며 — FileShareConfig를 통해 주소 지정됩니다.

7. 조용히 실패하는 클라이언트 측 변경 사항

아래의 모든 항목은 컴파일되고 실행되며 로그를 남기지 않고, 잘못된 동작을 합니다:

추가로 세 가지가 더 있습니다: 뷰어는 자체 툴바를 그리지 않으며(페이지가 Zoom, Next, GotoPage 및 나머지를 자체 버튼에 연결합니다); 숨겨진 Bootstrap 모달 안에 생성된 뷰어는 크기가 0×0으로 측정되어 아무것도 그리지 않으며, 컨테이너에 명시적인 높이를 지정하고 shown.bs.modal에서 다시 맞출 때까지 그리지 않습니다; 그리고 AllowSearch는 PDF에 대해 기본값이 false이므로, 문서는 완벽하게 렌더링되지만 모든 검색은 결과를 반환하지 않습니다.

8. 사라지는 것

제안된 작업 순서

1. 대상 재설정, 패키지 교체, 그리고 Global.asax가 DoconutHost.Initialize와 두 개의 Web.config 등록과 함께 컴파일되도록 합니다. 사이트가 시작되어야 합니다.
2. 뷰어 페이지 하나: 문서를 렌더링하도록 하고, 섹션 7을 진행하여 툴바, 검색 및 주석이 정상 동작하도록 합니다. 실제 브라우저에서 확인 — 해당 섹션에서 오류가 발생하지 않습니다.
3. 변환 (섹션 5): 기계적이며, 대부분의 컴파일 오류를 포함합니다.
4. 포팅된 샘플을 차이점 대상(diff target)으로 사용하여 나머지 페이지를 처리합니다.
5. 웹 팜 (섹션 4), 보유하고 있다면. 두 노드와 브라우저, 혹은 쿠키를 유지하는 클라이언트로 테스트합니다.