Di chuyển

Trang này đề cập đến việc nâng cấp một ứng dụng ASP.NET hiện có từ Doconut.NETFramework 26.8.0 hoặc cũ hơn (.NET Framework 4.7) lên 26.9.0 và các phiên bản sau (.NET Framework 4.7.2). Gói mẫu Doconut chứa hướng dẫn di chuyển đầy đủ và các mẫu cổ điển đã được chuyển sang API mới — MVC 5, một web farm và Web Forms. So sánh ứng dụng của bạn với mẫu mà nó bắt đầu từ là cách nhanh nhất.

Một gói, hai phiên bản

Cả hai thư viện đều được phát hành dưới cùng một ID gói, Doconut.NETFramework. Phiên bản phân biệt chúng:

Cập nhật gói là việc nâng cấp. Không có gói riêng để cài đặt và không có lớp tương thích: 26.9.0 có bề mặt API khác, vì vậy hãy chuẩn bị cho các lỗi biên dịch sau khi cập nhật — phần còn lại của trang này. Dòng .NET Framework 4.7 đã ngừng và 26.8.0 là bản phát hành cuối cùng của nó. Bạn có thể tiếp tục sử dụng nó — không có bản vá bảo mật nào ở đây mà bạn sẽ bỏ lỡ — nhưng các bản phát hành mới, plugin, chế độ phân phối và các widget dạng drop‑in chỉ xuất hiện trên 26.9.0 và các phiên bản sau.

1. Đặt lại mục tiêu và cập nhật gói

Đặt lại mục tiêu dự án web sang .NET Framework 4.7.2 trước: một dự án vẫn nhắm tới 4.7 không thể cài đặt 26.9.0, và NuGet từ chối cập nhật. Sau đó cập nhật Doconut.NETFramework và thêm các gói plugin bạn sử dụng (Doconut.NETFramework.Converter, Doconut.NETFramework.Dicom, …). Mỗi plugin cần một giấy phép cho phép nó.

Nếu dự án sử dụng packages.config, quá trình cập nhật sẽ chạy bước gỡ cài đặt của phiên bản trước, loại bỏ trình xử lý DocImage khỏi Web.config, và 26.9.0 không thêm lại nó. Đăng ký lại như được chỉ ra ở bước 3; cho đến khi bạn làm điều đó, DocImage.axd trả về 404 và không có trang nào được vẽ.

2. Không gian tên: hầu hết mọi thứ đã được chuyển lên root

Tên kiểu không thay đổi: WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, FileShareConfig và phần còn lại vẫn còn. Trong hầu hết các tệp, toàn bộ chỉnh sửa chỉ là xóa các dòng using.

3. Khởi động: DoconutHost.Initialize và hai mục Web.config

Gói classic tạo trình xem của nó cho mỗi yêu cầu, với các tùy chọn là thuộc tính của thể hiện đó. Gói mới có một composition root, được xây dựng một lần trong Application_Start, và trình xem là một dịch vụ bạn giải quyết:

// Trước - Doconut.NETFramework 26.8.0 và các phiên bản trước, theo yêu cầu
var viewer = new Viewer
{
    ID = "ctlDoc",
    IncludeJQuery = true,
    BasePath = "/",
    FitType = "width"
};

// Doconut.NETFramework 26.9.0\u002B - Viewer được giải quyết từ DoconutHost, giấy phép được cấu hình một lần trong DoconutHost.Initialize()
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
var token  = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

DoconutHost.Initialize đi vào Application_Start và DoconutHost.Shutdown trong Application_End, và Web.config nhận trình xử lý DocImage.axd và mô-đun tài nguyên — cả hai đều có trong Cài đặt. Các cài đặt hiển thị per-page (FitType, FixedZoom, ShowHyperlinks, …) đã được chuyển từ thể hiện trình xem sang tùy chọn của widget, hoặc sang một ViewerConfig được truyền vào Viewer.RenderViewer (xem ViewerConfig). new Viewer() vẫn biên dịch được một khi DoconutHost.Initialize đã chạy, vì vậy mã phía sau đã di chuyển có thể giữ dòng đó trong khi bạn di chuyển các cài đặt.

Bảo mật hoạt động như trước. Mở một tài liệu cho phép phiên ASP.NET hiện tại truy cập các trang của nó, và DocImage.axd từ chối mọi người khác. Cài đặt ứng dụng DoconutUnSafeMode đã tắt tính năng này hiện nay là options.UnsafeMode trong DoconutHost.Initialize — để nó false. Xem Phiên làm việc & Bảo mật.

Lỗi khởi động khiến toàn bộ site ngừng hoạt động. Một plugin đã đăng ký mà khả năng không được cấp phép sẽ ném ra lỗi trong Application_Start, và ứng dụng sau đó trả về một 500 trống cho mọi yêu cầu — không có trang lỗi, không có gì trong nhật ký IIS, chỉ có một mục trong nhật ký sự kiện Windows (nguồn ASP.NET). Các giấy phép được đọc từ wwwroot dưới thư mục gốc của site và không ở nơi nào khác, và base Doconut.Viewer.lic phải tồn tại hoặc các giấy phép plugin bên cạnh nó sẽ không được đọc. Xem Cài đặt giấy phép.

4. Web farm: từ một cờ đến chế độ phân tán

Mô hình cổ điển là viewer.IsWebfarm = true cộng ExportToPng(path). Mô hình mới được đăng ký một lần: mọi nút chia sẻ một kho lưu và một khóa ký, và một vé đã ký gắn với trình duyệt thay thế “nút nào trả lời”:

Doconut.DoconutHost.Initialize(
    options => options.UnsafeMode = false,
    services => services.AddDoconutDistributed(d =>
    {
        d.Store             = CloudLocation.FileShare;
        d.FileShareRootPath = @"\\fileserver\doconut-shared";   // WebfarmPath là một bí danh
        d.SigningKey        = farmKey;                           // >= 32 byte, giống nhau trên mọi nút
    }));

Sau đó mở tài liệu bình thường, gắn trình duyệt (DocOptions.BrowserId = DoconutFarmBinding.EnsureBrowserId(...)) và truyền viewer.AccessToken cho widget cùng token. Phiên làm việc & Bảo mật có các bước; mẫu web-farm là một nút hoàn chỉnh. IsWebfarm và WebfarmPath vẫn biên dịch, nhưng chúng không còn bật bất kỳ thứ gì nữa.

Hai điều trông giống như thành công nhưng không phải: DistributedDocumentPublisher.PublishAsync ghi các tệp đã render của tài liệu nhưng không mở phiên, vì vậy một trình xem trỏ tới token đã xuất bản sẽ nhận được hình lỗi ~2 KB với trạng thái 200; và một client kiểm thử không có cookie doconut-client sẽ nhận cùng hình ảnh đó, không phải 401. Phân biệt trang thực với hình lỗi bằng kích thước.

5. Chuyển đổi là một plugin, và nhỏ hơn nhiều

Enum SourceFormatConverter, mười hai lớp *ConfigConverter, và các enum mục tiêu lồng nhau của chúng được thay thế bằng một enum, ConversionTarget, và một lời gọi:

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

// Giả sử DoconutHost đã được khởi tạo và một CancellationToken có tên ct đã sẵn sàng.
var provider = DoconutHost.Services;
var converter = (DocumentConverter)provider.GetService(typeof(DocumentConverter));
Stream source = /* luồng đầu vào của bạn */;
var result = await converter.ConvertAsync(source, ".dwg", ConversionTarget.Pdf, null, ct);

Định dạng nguồn được lấy từ phần mở rộng bạn truyền. Không có shim tương thích: mọi tham chiếu SourceFormatConverter là lỗi biên dịch mà bạn phải giải quyết bằng cách xóa nó. Các đối tượng tùy chọn theo định dạng không tồn tại nữa — WordConfigConverter.HtmlOptions và CadConfigConverter.CadOptions.ShowColor không có tương đương qua ConvertAsync. Trong Web Forms, không bao giờ chặn trên ConvertAsync — xem Plugin Chuyển đổi.

6. Lưu trữ đám mây: truy cập như một thư mục chia sẻ

Các kiểu cấu hình đám mây được chuyển sang Doconut.Clouds không thay đổi. Các trình xử lý yêu cầu đám mây, tuy nhiên, là các thành phần ASP.NET Core, và một ứng dụng cổ điển không có pipeline để chạy chúng. Từ một site System.Web, truy cập lưu trữ đám mây như một thư mục chia sẻ — trên Azure, một Azure Files share được gắn vào mỗi nút — được truy cập qua FileShareConfig.

7. Các thay đổi phía client mà thất bại âm thầm

Mỗi mục dưới đây biên dịch, chạy, không ghi log, và làm sai:

Ba điều nữa: trình xem không vẽ thanh công cụ của riêng nó (trang của bạn nối Zoom, Next, GotoPage và phần còn lại vào các nút của nó); một trình xem được tạo bên trong một modal Bootstrap ẩn có kích thước 0×0 và không vẽ gì cho tới khi bạn đặt chiều cao rõ ràng cho container và điều chỉnh lại trên shown.bs.modal; và AllowSearch mặc định là false cho PDF, vì vậy tài liệu được render hoàn hảo trong khi mọi tìm kiếm không trả về gì.

8. Những gì biến mất

Thứ tự công việc đề xuất

1. Nhắm lại, đổi gói, và cho Global.asax biên dịch với DoconutHost.Initialize và hai đăng ký Web.config. Trang web nên khởi động.
2. Một trang trình xem: lấy một tài liệu để hiển thị, sau đó làm việc qua mục 7 cho đến khi thanh công cụ, tìm kiếm và chú thích hoạt động. Xác minh trong trình duyệt thực — không có gì trong mục đó gây lỗi.
3. Chuyển đổi (mục 5): cơ bản, và hầu hết các lỗi biên dịch.
4. Các trang còn lại, sử dụng các mẫu đã chuyển như mục tiêu so sánh.
5. Môi trường web (mục 4), nếu bạn có. Kiểm tra với hai nút và một trình duyệt, hoặc một client giữ cookie.