.NET Standard 2.1 로 마이그레이션
기존 Doconut.NETStandard 애플리케이션을 26.7.0에서 26.8.0으로 이동
Doconut에는 두 가지 구별되는 .NET Standard 통합이 있습니다. 동일한 Doconut.NETStandard 패키지 이름을 사용하므로 버전과 애플리케이션의 API를 확인한 뒤 패키지, 시작 설정, 라이선스 또는 브라우저 리소스를 변경하십시오.
버전이 갈림길입니다
두 세대 모두 동일한 패키지 ID로 배포됩니다. 버전만이 두 세대를 구분합니다:
| 버전 | 대상 | API |
|---|---|---|
| 26.7.0 이하 | netstandard2.0 | 이전 API |
| 26.8.0 이상 | netstandard2.1 | 현재 API |
버전 번호를 올리는 것이 업그레이드입니다. 별도의 설치 패키지가 없으며 호환성 쉼이 없습니다 — 26.8.0은 다른 API 표면을 가집니다. 버전 올린 후 컴파일 오류가 발생할 것이며, 이 가이드의 나머지는 그 오류 목록입니다.
어떤 통합을 사용하고 있나요?
| 프로젝트에 포함된 경우… | 세대 |
|---|---|
new Viewer(_cache, _accessor, ...) | 이전 |
viewer.OpenDocument(...) (동기) | 이전 |
viewer.InitCache() | 이전 |
UseDoconut(new DoconutOptions { ... }) | 이전 |
UseDoconutWebFarm(...) / WebFarmOptions | 이전 |
Viewer.DoconutLicense(...) 또는 Viewer.SetLicensePlugin(...) | 이전 |
viewer.Converter.GetConverter() | 이전 |
using Doconut.Configs; / using Doconut.Models; | 이전 |
수동으로 복사한 docViewer.js, documentLinks.js, 또는 docViewer.UI.js | 이전 |
builder.Services.AddDoconut(...) | 현재 |
app.UseDoconutResources() plus app.UseDoconut() with no arguments | 현재 |
Viewer supplied by dependency injection | 현재 |
await viewer.OpenDocumentAsync(...) | 현재 |
두 열이 동일한 애플리케이션에 모두 나타난다면 마이그레이션을 미완료 상태로 간주하십시오. 한 세대의 리소스나 미들웨어를 통해 다른 세대의 문서 토큰을 보내지 마세요.
먼저 호스트 프레임워크를 확인하세요
이는 선호도가 아니라 강제 조건입니다. 현재 패키지는 netstandard2.1을 대상으로 합니다:
| 호스트 | 26.8.0 사용 가능 여부 |
|---|---|
| .NET Core 3.0 이상 (.NET 5/6/7/8 포함) | 예 |
| .NET Framework, 모든 버전 | 아니오 |
.NET Framework는 netstandard2.1 라이브러리를 참조할 수 없습니다. 애플리케이션이 .NET Framework에서 실행된다면 여기서 중단하고 대신 Doconut.NETFramework 패키지를 사용하십시오; 26.9.0부터는 .NET Framework 4.7.2가 필요합니다. 이번 릴리스의 두 참조 애플리케이션은 net8.0을 대상으로 합니다.
마이그레이션 전 준비 사항
- 기존 애플리케이션의 브랜치를 만들고 배포 가능한 백업을 생성합니다.
- 핵심 및 플러그인 패키지 버전을 정확히 기록합니다.
- 모든
new Viewer(...)호출,InitCache()호출, 라이선스 로드 호출,UseDoconutWebFarm매핑, 변환 컨트롤러, 복사된 Doconut 스크립트, 사용자 지정 툴바 액션, 뷰어 콜백 및 문서 열기 엔드포인트를 모두 인벤토리합니다. - 현재
.lic파일과 배포 비밀을 소스 제어 외부에 보관합니다. - PDF, Office, 이미지, CAD, 이메일, DICOM, 검색 가능, 비밀번호 보호, 주석이 달린 문서들의 대표적인 세트를 수집합니다.
- 기존 세션 타임아웃, 보안 동작, 폰트 및 플랫폼 설정을 기록합니다.
프로덕션을 변경하기 전에 하나의 환경을 마이그레이션하십시오. 현재 통합은 서비스 수명, 요청 라우팅, 세션 소유권, 클라이언트 리소스 전달을 변경하며, — 팜을 운영하는 경우 — 페이지가 브라우저에 도달하는 방식을 모두 변경합니다.
1. 네임스페이스: 거의 모든 것이 루트로 이동
구성 타입은 네 개의 네임스페이스에 분산되어 있었습니다. 이제 모두 Doconut에 있습니다.
| 이전 | 현재 |
|---|---|
using Doconut.Configs.View; | using Doconut; |
using Doconut.Models; | using Doconut; |
using Doconut.Configs; | using Doconut; |
using Doconut.Configs.Cloud; | using Doconut.Clouds; |
using Doconut.Configs.Conversion; | 변경되지 않음 |
using Doconut.Middleware; | 변경되지 않음 |
타입 이름은 변경되지 않았습니다: WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, CloudUploadConfig, AzureConfig, CDNConfig, FileShareConfig 그리고 나머지도 모두 여전히 존재합니다. 대부분의 파일에서 전체 편집은 두 개의 using 라인을 삭제하는 것입니다.
Doconut.Configs.Editor (BaseConfigEditor, PdfConfigEditor)가 제거되었으며 이 패키지에 대체가 없습니다. 애플리케이션이 해당 타입을 참조하고 있다면 해당 부분을 별도로 계획하고 이번 마이그레이션의 일부로 간주하지 마세요.
2. 패키지 및 라이선스 호환성
핵심 패키지를 의도적으로 교체하거나 업데이트하십시오; 동일한 패키지 ID에 의존하여 새 API를 선택하지 마세요. 기본 명령은 최신 안정 버전을 설치합니다:
dotnet add package Doconut.NETStandard이 가이드에서 검증된 릴리스로의 재현 가능한 마이그레이션을 위해, 버전을 별도 옵션으로 전달하십시오:
dotnet add package Doconut.NETStandard --version 26.9.0모든 Doconut 플러그인을 핵심 패키지와 동일한 버전으로 유지하십시오 — Doconut.NETStandard.Converter 및 Doconut.NETStandard.Dicom. 현재 통합은 AddDoconut() 동안 한 번 라이선스를 로드하며, 다음 우선순위를 사용합니다:
LicenseStream > LicenseContent > LicensePath > automatic discovery자동 발견은 Doconut.Viewer.lic와 보조 Doconut.Viewer.<Capability>.lic 파일을 찾습니다. 이전 정적 호출 Viewer.DoconutLicense(...) 및 Viewer.SetLicensePlugin(...)은 현재 시작 메커니즘이 아니며, 오래된 Viewer 생성자가 허용하던 라이선스 경로의 List<string>도 마찬가지입니다. 라이선스를 DoconutOptions 로 이동하고, 자동 발견을 사용할 때 보조 파일을 함께 유지하며, 라이선스를 변경한 후 재시작하고, IDoconutLicenseService 를 통해 기능을 검증하십시오.
오래된 플러그인 라이선스가 존재한다고 해서 현재 플러그인 빌드에 대한 권한이 보장된다고 가정하지 마세요. 승인된 릴리스 아티팩트를 사용하여 Viewer, Search, Annotation, Converter, 그리고 DICOM을 각각 별도로 테스트하십시오.
3. 시작 및 의존성 주입
이전에는 뷰어가 요청당 생성되었으며 옵션이 미들웨어에 전달되었습니다:
// 이전 통합 — 대비용만; 현재 SDK와 함께 컴파일하지 마세요.
var viewer = new Viewer(_cache, _accessor);
// …
appBranch.UseDoconut(new DoconutOptions { UnSafeMode = false, ShowDoconutInfo = false });현재 통합은 Doconut을 한 번 등록하고 의존성 주입으로부터 Viewer 를 받습니다:
builder.Services.AddDoconut(options =>
{
options.UnsafeMode = false; // 철자 변경을 확인하세요: UnSafeMode → UnsafeMode
options.ShowDoconutInfo = false;
options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // 세션 상태에 캐시가 필요합니다 (MVC/Razor Pages는 이미 하나를 추가합니다)
builder.Services.AddSession();
app.UseSession();
app.UseDoconutResources();
app.UseDoconut();Viewer 은 일시적인 서비스입니다. 문서 세션 관리자와 그 캐시는 특정 주입된 Viewer 인스턴스가 아니라, 더 오래 지속되는 문서 상태를 소유합니다.
전달해야 할 세 가지 사항:
new Viewer(cache, accessor)은 사라졌습니다. 컨트롤러에Doconut.Viewer를 주입하거나 Razor 뷰에서@inject Doconut.Viewer Viewer를 사용하십시오.UseDoconutResources()은 수동 연결app.UseMiddleware<EmbeddedResourceMiddleware>()을 대체하며, 문서 브랜치 이전에 실행되어야 합니다.UnSafeMode→UnsafeMode. 한 글자만 바꾸면 컴파일러가 감지합니다.
UnsafeMode 가 false 일 때, SDK는 세션 토큰을 원본 요청과 비교 검증하므로, AddSession() / UseSession() 은 여전히 파이프라인에 있어야 하며, 브랜치 이전에 UseSession() 가 필요합니다.
더 이상 존재하지 않는 메서드
| Before | Now |
|---|---|
viewer.OpenDocument(path, config, options) | await viewer.OpenDocumentAsync(path, config, options) |
viewer.InitCache() | removed — 수동으로 초기화할 것이 없습니다; 호출을 삭제하고 주변의 "이미 초기화했나요?" 플래그도 제거하십시오. |
viewer.ExportToPng(sharedPath) | §7을 참조하십시오 |
viewer.ExportToCloud(cloudConfig) | §7을 참조하십시오 |
using var v = new Viewer(...); v.CloseDocument(t) | viewer.CloseDocument(token) 를 주입된 인스턴스에 적용 |
4. 미들웨어 및 리소스 라우팅
UseDoconut() 은 이제 인수를 받지 않습니다. MapWhen 브랜치 형태 자체는 변경될 필요가 없으며, 내부의 미들웨어만 변경하면 됩니다:
app.UseDoconutResources(); // 브랜치 이전에
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconut());현재 파이프라인에서:
- 세션 보안이 활성화된 상태에서 Doconut 이전에
UseSession()를 호출합니다; UseDoconut()이전에UseDoconutResources()를 호출합니다;ResourcesPath, 생성된 리소스 URL, 그리고 클라이언트ResPath를 정렬된 상태로 유지합니다;- 매핑한 브랜치와 클라이언트
BasePath를 정렬된 상태로 유지합니다.
MiddlewarePath 은 검증된 구성이며, 자체적으로 ASP.NET Core 브랜치를 생성하지 않습니다.
5. 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 });
});반환된 토큰은 서버 측 문서 세션을 식별합니다. 이를 베어러
자격 증명으로 취급하십시오: 로그에 기록하거나, 영구 저장하거나, 분석에 사용하지 마세요.
6. 문서 열기 및 닫기
동기식 OpenDocument(...) 를 OpenDocumentAsync(...) 로 교체합니다:
// 현재 통합: Viewer는 DI에서 제공되며 문서 열기가 비동기식입니다.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });현재 오버로드는 파일 경로나 스트림, 선택적 포맷 구성, 선택적
DocOptions, 그리고 취소 토큰을 허용합니다. 브라우저가 더 이상 필요로 하지 않을 때
서버 세션을 명시적으로 종료하십시오:
viewer.CloseDocument(token);any InitCache() 호출과 이를 보호하는 플래그를 삭제하십시오 — 수동으로 준비할 것이
없습니다. 이전 라이브러리에서 발행된 토큰을 전환 후 재사용하지 마세요: 각 문서를
현재 API를 통해 다시 엽니다.
7. 웹 팜 → 분산: 가장 큰 변화
UseDoconutWebFarm 및 WebFarmOptions 은 더 이상 존재하지 않습니다. 앱이 이를 호출한다면,
이 섹션이 업그레이드 가이드가 됩니다; 호출하지 않으면 §8 로 건너뛰세요.
이전에는 하나의 미들웨어가 모든 작업을 수행했습니다: 공유 폴더에서 사전 렌더링된 이미지를 제공했으며,
다른 노드가 아직 이미지를 쓰고 있는 동안 폴링했습니다.
// 이전 통합 — 한 번의 호출, 파일 시스템을 통한 암시적 조정.
appBranch.UseDoconutWebFarm(new WebFarmOptions
{
Path = Path.Combine(env.WebRootPath, "webfarm"),
PageWaitTimeSeconds = 180,
StartWaitFromPage = 5,
});동일한 작업이 이제 두 개의 명시적인 절반으로 나뉩니다. 쓰기 측 — 문서를 여는
노드가 전체 아티팩트 세트(페이지, 문서 정보, 검색 인덱스,
메타데이터)를 공유에 게시합니다:
var result = await _publisher.PublishAsync( // DistributedDocumentPublisher, DI에서 주입됨
pathToFile,
new FileShareConfig
{
Location = CloudLocation.FileShare,
RootPath = @"\\fileserver\doconut", // 오늘 사용하는 동일한 폴더
UsePerTokenSubfolders = true,
},
config,
documentOptions,
new DistributedDocumentPublishOptions
{
CleanUpStagingDirectory = true,
FirstPagePriority = true,
});
return Content(result.Token);읽기 측 — 모든 노드가 공유에서 서비스를 제공합니다:
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch => branch.UseDoconutCloud<FileShareCloudHandler>(options =>
{
options.Location = CloudLocation.FileShare;
options.CloudUploadConfig = /* 위와 동일한 SAME FileShareConfig */;
}, "/"));| 이전 | 현재 |
|---|---|
WebFarmOptions.Path | FileShareConfig.RootPath |
PageWaitTimeSeconds / StartWaitFromPage | 없음 — 쓰기 측에서는 FirstPagePriority 로, 읽기 측에서는 FileShareConfig.ReadReadyPollMs 로 교체됩니다 |
viewer.OpenDocument(...) 그때 viewer.ExportToPng(share) | 하나의 PublishAsync(...) 호출 |
DocOptions.IsWebfarm / WebfarmPath | 여전히 존재하지만, IsWebFarm / WebFarmPath 로 표기됩니다 — 그러나 게시 경로에서는 필요하지 않습니다 |
토폴로지는 변경되지 않습니다. RootPath 를 동일한 UNC 공유에 지정하면 모든 노드가
오늘과 같은 방식으로 계속 작동합니다. 변경되는 점은 게시가
렌더링의 부수 효과가 아니라 호출하는 작업이라는 점입니다.
두 절반은 일치해야 합니다.
RootPath또는UsePerTokenSubfolders가 퍼블리셔와 핸들러 사이에서 다르면
다른 노드는 404 응답을 반환합니다. 하나의 헬퍼에서 설정을 구축하고
양쪽에서 호출하십시오.
PageWaitTimeSeconds = 180 은 "페이지가 나타날 때까지 최대 3분 동안 차단"을 의미했습니다.
대체 방법은 명시적입니다: FirstPagePriority = true 를 사용하면 1페이지는 즉시 제공 가능하고
이후 페이지는 HTTP 202 Accepted 응답을 받으며, 작성될 때까지 대기합니다. 번들된 뷰어는
retryOn409 가 설정되면 자동으로 재시도합니다. 재시도하지 않는 클라이언트는
여전히 렌더링 중인 페이지에 대해 깨진 타일을 표시합니다.
백그라운드 게시와 액세스 티켓을 포함한 전체 구성은 분산 배포에서 확인할 수 있습니다.
8. 변환은 플러그인이며, 훨씬 작다
플러그인을 등록하고, DocumentConverter 파사드를 주입합니다:
builder.Services.AddDoconut(o => o.AddPlugin<ConverterPlugin>());// 이전 통합
var converter = viewer.Converter.GetConverter();
var config = new WordConfigConverter { TargetFormat = WordConfigConverter.EnTargetFormat.PDF };
var result = converter.Convert(stream, SourceFormatConverter.DOCX, config);
// 현재 통합
var result = await _converter.ConvertAsync(stream, ".docx", ConversionTarget.Pdf, null, ct);대체되는 내용:
SourceFormatConverter— 사라짐. 파일 확장자를 문자열로 전달하세요, 점 포함.- 각 패밀리별
*ConfigConverter유형 (WordConfigConverter,ExcelConfigConverter, …), 각각 중첩된EnTargetFormat열거형을 가지고 있었으며 — 사라짐. 이제 모든 패밀리마다 하나의ConversionTarget열거형이 있습니다. viewer.Converter.GetConverter()— 사라짐.Doconut.DocumentConverter을 주입합니다.
ConvertAsync은 탐색 가능한 스트림을 반환하므로 return File(result, mime, name)이 직접 작동합니다
직접 — 기존 코드 복사에 필요한 MemoryStream은 불필요합니다. 배포된 샘플에서는 68가지 확장 스위치와 거의 동일한 10개의 컨트롤러가 삭제되었습니다.
전체 기능을 보려면 컨버터 플러그인을 확인하세요.
9. 클라우드 제공자
UseDoconutCloud이 일반화되었습니다. 제공자는 타입 인수이며, 대신에
Location 값이 미들웨어 내부에서 전환됩니다:
// 이전 통합
appBranch.UseDoconutCloud(new CloudOptions { Location = CloudLocation.CDN, ... });
// 현재 통합
branch.UseDoconutCloud<CDNCloudHandler>(options =>
{
options.Location = CloudLocation.CDN;
options.CloudUploadConfig = new CDNConfig { DoconutCdnUrl = "..." };
}, "/");구성 클래스는 네임스페이스 (Doconut.Configs.Cloud →
Doconut.Clouds)를 제외하고는 변경되지 않았습니다: AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig,
RedisConfig, CDNConfig, FTPConfig, 그리고 새로운 FileShareConfig. 핸들러는
<Provider>CloudHandler으로 명명됩니다.
CDN 핸들러는 읽기 전용이며 — CDN에 이미 있는 것을 제공하고, 업로드하지 않습니다.
10. 이름이 변경된 구성 객체
| 이전 | 현재 |
|---|---|
DoconutOptions.UnSafeMode | UnsafeMode |
DocOptions.IsWebfarm | IsWebFarm |
DocOptions.WebfarmPath | WebFarmPath |
DocOptions.ImageResolution | 여전히 존재하지만 구식 — 대신 포맷 구성에서 해상도를 설정하십시오 |
DocOptions도 IsSecured를 얻습니다.
현재 API는 이전보다 더 엄격하게 관심사를 분리하므로, 확인하십시오 각 설정이 이제 소유하는 객체에 있는지:
| 관심사 | 현재 유형 |
|---|---|
| 미들웨어 경로, 라이선스, 플러그인 등록 | DoconutOptions |
| 비밀번호, 타임아웃, 보안, 워터마크 | DocOptions |
| 포맷 렌더링 및 DPI | PdfConfig, WordConfig, ExcelConfig, 및 기타 BaseConfig 유형 |
| 브라우저 위젯 기본값 | ViewerConfig 또는 동등한 JavaScript 옵션 |
| 생성된 CSS 및 스크립트 | CssConfig and ScriptConfig |
| 공유 스토리지 및 클라우드 제공자 | FileShareConfig and the other Doconut.Clouds configs |
DocOptions.ImageResolution를 렌더링 제어로 사용하지 마십시오.
이는 구식입니다; 포맷별 구성에 BaseConfig.ImageResolution를 설정하십시오.
이전 구성과 동일한 동작을 가정하지 말고 모든 기본값을 검토하십시오.
11. 클라이언트 측 뷰어 — 조용히 실패하는 두 가지 변경 사항
이 두 가지 모두 서버가 완벽히 작동하도록 합니다. 문서는 렌더링되고, 페이지는 올바르게 보이며, 브라우저 콘솔에 아무 것도 나타나지 않습니다. C#이 처음에 컴파일되더라도 이 섹션을 읽으십시오.
뷰어 콜백은 이제 옵션이며, 전역 함수가 아닙니다
이전 뷰어는 핸들러를 이름으로 호출했으며, 전역 함수 이름을
컨테이너 ID에서 파생했습니다. 페이지에 function ctlDoc_OnViewerReady()를 선언하고
<div id="div_ctlDoc">만 있으면 충분했습니다. 현재 뷰어는 옵션 객체에 명시적인 콜백을 받아들이며,
더 이상 전역을 찾지 않습니다:
objctlDoc = $("#div_ctlDoc").docViewer({
// ... 기존 옵션 ...
onViewerBusy: ctlDoc_OnViewerBusy, // 이름으로 찾음
onViewerReady: ctlDoc_OnViewerReady, // 이름으로 찾음
onCopy: ctlDoc_Copy, // ctlDoc_Copy(text) 호출됨
onAutoLoadStatus: ctlDoc_AutoLoadStatus // ctlDoc_AutoLoadStatus(page) 호출됨
});왜 이것이 문제가 되는가: 이전 호출은 빈 catch로 감싸여 있었으며, 모든 것을 흡수했습니다.
이제 함수가 실행되지 않으며 오류가 보고되지 않습니다. 일반적인 증상은 멈추지 않는 로딩 스피너이며 — 그것을 숨긴 함수가
ctlDoc_OnViewerReady였기 때문입니다. 그 뒤의 문서는 정상입니다.
전체 옵션 목록은 onPageLoading, onPageLoaded, onThumbnailClicked,
onPageClicked, onDoubleClick, onViewerBusy, onViewerReady, onViewerError,
onCopy, onAnnSaved, onAnnSaveError, onAnnLoaded, onAnnClosed,
onAutoLoadStatus, onThumbsShown, 그리고 onError. 링크 클릭 콜백은 없습니다:
하이퍼링크 처리는 내장되어 있으며, showHyperlinks에 의해 구동됩니다.
ResPath 은(는) 리소스 접두사에 지정되어야 합니다
ResPath: '', // 이전 — 리소스가 애플리케이션 루트에서 제공되었습니다
ResPath: 'doconut-res/images', // 현재 — 접두사 UseDoconutResources()가 마운트됩니다DoconutOptions.ResourcesPath 를 통해 접두사를 변경한 경우, 그 값을 대신 사용하십시오.
12. 뷰어 툴바, 검색 및 주석
오래된 스크립트를 하나씩 마이그레이션하지 마십시오. 현재 레퍼런스 애플리케이션은 하나의 완전한 페이지 패키지를 구성합니다:
ReferenceCss로 뷰어 CSS와 라이선스가 부여된 검색/주석 CSS를 내보냅니다;- 애플리케이션이 소유한 뷰어 툴바를 렌더링합니다;
searchBarMount,annBarMount및 필수 뷰어 마운트를 렌더링합니다;ReferenceScripts로 뷰어 및 라이선스가 부여된 모듈 스크립트를 내보냅니다;- 애플리케이션 자체 툴바 헬퍼 스크립트를 로드합니다;
- 하나의
objViewer를 초기화합니다; - 라이선스가 부여된 검색 및 주석 리본을 초기화합니다;
- 각 리본에 대해
attach(objViewer)를 호출합니다; - 문서를 열고
objViewer.View(token)를 호출합니다.
검색 및 주석은 동일한 뷰어에 부착된 모듈이며, 독립적인 툴바가 아닙니다. 메인 툴바는 호스트 애플리케이션에 속하고, 검색 및 주석 리본은 임베드된, 기능에 따라 제한된 리소스입니다.
현재 페이지가 ReferenceCss 와 ReferenceScripts 로 내보낸 리소스로 정상 동작할 때만 documentLinks.js 및 docViewer.UI.js 와 같은 수동 복사 파일을 제거하십시오.
13. 플러그인 등록
정적 플러그인‑라이선스 메서드는 현재 플러그인을 등록하지 않습니다. 각 릴리스된 패키지를 명시적으로 설치하고 등록하십시오:
builder.Services.AddDoconut(options =>
{
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});AddDoconut() 은 시작 시 등록된 플러그인 기능을 검증합니다. Converter와 DICOM은 릴리스된 .NET Standard 플러그인입니다. 일반 검색 및 주석은 내장된 라이선스 기능이며, AddPlugin<TPlugin>() 패키지는 아닙니다.
14. 세션 및 문서 보안
현재 통합은 문서를 불투명 토큰 및 캐시된 세션에 바인딩합니다. 기본 UnsafeMode = false 를 사용하면, UseDoconut() 가 문서 접근 보안을 추가하고 호스트는 ASP.NET 세션을 구성해야 합니다:
builder.Services.AddDistributedMemoryCache(); // 세션 상태에 캐시가 필요합니다 (MVC/Razor Pages는 이미 하나를 추가합니다)
builder.Services.AddSession();
app.UseSession();검토된 설계에서 달리 요구되지 않는 한 DocOptions.IsSecured = true 를 유지하십시오. 단일 노드에서 마이그레이션 단축키로 UnsafeMode = true 를 절대 사용하지 마십시오. 토큰이 없거나, 형식이 잘못되었거나, 만료되었거나, 다른 브라우저 세션에서 온 토큰에 대한 요청을 테스트하십시오.
팜 환경에서는 페이지 요청이 처음 요청을 본 적이 없는 노드에 도달할 수 있어, 세션당 검사가 이를 거부하게 됩니다. 이것이 UnsafeMode = true 가 올바른 유일한 경우이며, 자체적으로 배포되지 않고 AddDoconutDistributedDocumentSecurity 를 통한 서명된 접근 티켓과 함께 사용되어야 합니다. 자세히 보려면 분산 배포를 참조하십시오.
명명 참고
모든 프레임워크에서 클래스는 Viewer 입니다. 오래된 스니펫이나 타사 기사에서 DocumentViewer 를 발견한다면, 해당 타입은 SDK에 존재하지 않았던 것입니다.
15. 권장 작업 순서
- 호스트 프레임워크가 netstandard2.1 을 사용할 수 있는지 확인하십시오. 사용할 수 없으면 중단하십시오.
- 패키지를 26.8.0 으로 올리고 빌드하십시오. 컴파일 오류를 해결하십시오 — 대부분은 §1 에 있는
using라인입니다. - 시작 코드를
AddDoconut()로 이동하고 미들웨어 호출을 새로운 순서대로 정렬하십시오 (§3, §4). Viewer를 구성하던 위치에 주입하고,OpenDocument를 비동기로 만들며,InitCache()를 삭제하십시오 (§5, §6).- 웹 팜을 사용하는 경우 §7 을 수행하십시오 — 이름 변경이 아니라 재설계가 필요한 유일한 부분입니다.
- 문서를 변환하는 경우 §8 을 수행하십시오.
- §11 — 클라이언트 측 변경을 수행하십시오. 이 변경은 스스로 알리지 않습니다.
- 브라우저에서 실제 문서를 열고 로딩 스피너를 관찰하십시오. 녹색 빌드가 여기서는 아무것도 증명하지 못합니다: 라이선스, 플러그인 등록, 리소스 경로 및 뷰어 콜백이 모두 런타임에만 실패합니다. 팜 환경에서는 한 노드가 발행한 문서가 다른 노드에 의해 제공되는지 확인하십시오.
마이그레이션 테스트
최소한 다음을 확인하십시오:
- 프로덕션 라이선스와 모든 등록 플러그인을 사용한 애플리케이션 시작;
- 선택된 경로 아래의 Viewer CSS/스크립트 및 모든 페이지‑이미지 요청;
- 문서 열기, 탐색, 줌, 썸네일, 인쇄 및 명시적 닫기;
- 텍스트가 포함된 문서에서 검색 및 이미지 전용 파일의 검색 불가 상태;
- 주석 로드, 저장, 내보내기 및 기능 제한;
- 변환기 대상 탐색, 출력, 다운로드 및 워터마크 상태;
- DICOM 페이지, 프레임 및 애니메이션; 이 패키지에서는 기술 메타데이터를 사용할 수 없습니다;
- 비밀번호 보호 문서, 사용자 정의 폰트, 비라틴 문자 텍스트 및 구성된 타임아웃;
- 세션 간 토큰 거부 및 세션 만료 동작;
- 팜의 경우: 한 노드에 게시하고 다른 노드에서 늦은 페이지를 요청한 뒤 확인합니다
뷰어가 깨진 타일을 표시하는 대신202응답을 재시도하는지; - 모바일, 다크 모드 및 프로덕션 리버스 프록시 경로.
롤백 계획
이전 배포 아티팩트, 일치하는 패키지, 라이선스 파일 및 복사된 브라우저
리소스를 함께 보관하십시오. 안전한 롤백은 전체 애플리케이션 세대를 전환합니다; 이는
이전 세대 서버와 현재 스크립트를 혼합하거나 현재 서버와 new Viewer(...) 호출 사이트를 혼합하지 않습니다.
전환 전, 다음을 문서화하십시오:
- 롤백에 사용된 배포 슬롯 또는 아티팩트;
- 공유 스토리지 영향(있는 경우) — 26.8.0에 의해 게시된 아티팩트는
이전 웹‑팜 미들웨어에서 사용되지 않습니다; - 활성 문서 세션이 어떻게 무효화될지;
- 롤백 결정을 위한 헬스 체크 및 스모크 문서;
- 누가 이전 패키지 세트와 구성을 복원할 수 있는지.
레거시 문서
번역된 이전 매뉴얼은 다음에서 계속 사용할 수 있습니다
Legacy .NET Standard setup.
Previous integration gateway 은 동일한
식별 신호를 설명하고 이 마이그레이션 가이드로 다시 연결합니다.
netstandard2.0 설치가 여전히 존재하는 동안 즐겨찾기와 지원 티켓에 역사적 URL을 유지하십시오. 이는 다른 세대를 문서화하며 현재 API로 리디렉션되지 않습니다.
이 페이지가 도움이 되었나요?