Migrasi dari integrasi .NET 6 klasik

Pindahkan aplikasi Doconut.NET6 yang ada ke DI dan API async saat ini

Doconut memiliki dua integrasi .NET 6 yang berbeda. Mereka dapat menggunakan nama paket Doconut.NET6 yang sama, jadi identifikasi generasi dari API dalam aplikasi sebelum mengubah paket, startup, lisensi, atau sumber daya browser.

Integrasi .NET 6 mana yang Anda gunakan?

Jika proyek berisi…Generasi
app.MapWhen(... "DocImage.axd" ...)Klasik
new Viewer(_cache, _accessor, ...)Klasik
Viewer.DoconutLicense(...) atau Viewer.SetLicensePlugin(...)Klasik
Salinan manual docViewer.js, documentLinks.js, atau docViewer.UI.jsKlasik
builder.Services.AddDoconut(...)Integrasi saat ini
app.UseDoconutResources() dan app.UseDoconut()Integrasi saat ini
Viewer disediakan oleh dependency injectionIntegrasi saat ini
await viewer.OpenDocumentAsync(...)Integrasi saat ini

Jika kedua kolom muncul dalam aplikasi yang sama, anggap migrasi tidak lengkap. Jangan mengirim satu token dokumen melalui sumber daya atau middleware dari generasi lain.

Mengapa nama paket NuGet mungkin tidak memberi tahu Anda

Kedua generasi telah dirilis dengan ID paket Doconut.NET6. Referensi paket, file kunci, atau .nupkg yang di‑cache tidak mengidentifikasi API hosting dengan sendirinya. Catat versi paket yang tepat dan periksa Program.cs, konstruksi viewer, pembukaan dokumen, serta skrip browser secara bersamaan.

Rilis saat ini yang diaudit untuk panduan ini adalah Doconut.NET6 26.7.0. Paket publik opsionalnya adalah Doconut.NET6.Converter dan Doconut.NET6.Dicom, yang dipatok pada versi rilis yang sama dengan paket inti.

Sebelum Anda melakukan migrasi

  1. Buat cabang dan cadangan yang dapat dideploy dari aplikasi yang ada.
  2. Catat versi paket inti dan plugin yang tepat.
  3. Inventarisasi setiap pemetaan DocImage.axd, panggilan new Viewer(...), panggilan pemuatan lisensi, skrip Doconut yang disalin, aksi toolbar khusus, dan endpoint pembukaan dokumen.
  4. Pertahankan file .lic saat ini dan rahasia deployment di luar kontrol sumber.
  5. Ambil sekumpulan contoh PDF, Office, gambar, CAD, email, DICOM, yang dapat dicari, dilindungi kata sandi, dan dokumen beranotasi.
  6. Catat batas waktu sesi yang ada, perilaku keamanan, font, dan pengaturan platform.

Migrasikan satu lingkungan sebelum mengubah produksi. Integrasi saat ini mengubah masa pakai layanan, routing permintaan, kepemilikan sesi, dan pengiriman sumber daya klien.

Kompatibilitas paket dan lisensi

Ganti atau perbarui paket inti secara sengaja; jangan bergantung pada ID paket yang identik untuk memilih API baru. Perintah standar menginstal rilis stabil terbaru:

bash
dotnet add package Doconut.NET6

Untuk migrasi yang dapat direproduksi ke rilis yang diaudit oleh panduan ini, berikan versi sebagai opsi terpisah:

bash
dotnet add package Doconut.NET6 --version 26.9.0

Pertahankan setiap plugin Doconut pada versi yang sama dengan paket inti. Integrasi saat ini memuat lisensi sekali selama AddDoconut(), menggunakan prioritas ini:

text
LicenseStream > LicenseContent > LicensePath > automatic discovery

Penemuan otomatis mencari Doconut.Viewer.lic dan file pendamping Doconut.Viewer.<Capability>.lic. Panggilan klasik ke Viewer.DoconutLicense(...) atau Viewer.SetLicensePlugin(...) bukan mekanisme startup saat ini. Pindahkan lisensi ke DoconutOptions, pertahankan file pendamping bersama saat menggunakan penemuan otomatis, restart setelah mengubah lisensi, dan verifikasi kemampuan melalui IDoconutLicenseService.

Jangan mengasumsikan bahwa keberadaan lisensi plugin lama membuktikan hak untuk build plugin saat ini. Uji Viewer, Search, Annotation, Converter, dan DICOM secara terpisah dengan artefak rilis yang disetujui.

Startup dan injeksi dependensi

Aplikasi klasik membangun Viewer dengan cache ASP.NET dan dependensi request-accessor:

csharp
// Integrasi klasik — hanya untuk perbandingan; jangan mengompilasi ini dengan SDK saat ini.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

Integrasi saat ini mendaftarkan Doconut sekali dan menerima Viewer dari injeksi dependensi:

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

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

Viewer adalah layanan transient. Manajer sesi dokumen dan cache-nya memiliki status dokumen yang lebih lama, bukan instance Viewer yang disuntikkan secara khusus.

Middleware dan routing sumber daya

Hapus cabang klasik MapWhen yang mendeteksi DocImage.axd:

csharp
// Integrasi klasik — hapus selama cutover.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

Dalam pipeline saat ini:

  1. panggil UseSession() sebelum Doconut saat keamanan sesi diaktifkan;
  2. panggil UseDoconutResources() sebelum UseDoconut();
  3. pertahankan ResourcesPath, URL sumber daya yang dihasilkan, dan ResPath klien tetap selaras;
  4. ketika memetakan UseDoconut() ke sebuah cabang, pertahankan cabang tersebut dan BasePath klien tetap selaras.

MiddlewarePath adalah konfigurasi yang divalidasi; ia tidak membuat cabang ASP.NET Core secara mandiri. Gunakan pipeline sederhana dalam contoh kompilasi di atas atau pengaturan app.Map("/doconut", branch => branch.UseDoconut()) eksplisit yang digunakan secara konsisten oleh klien.

Konstruksi Viewer dan masa pakai

Hapus cache milik aplikasi untuk objek Viewer. Suntikkan Viewer ke dalam endpoint, halaman Razor, controller, atau layanan aplikasi berskala:

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

Token yang dikembalikan mengidentifikasi sesi dokumen sisi server. Perlakukan itu sebagai kredensial bearer: jangan mencatatnya, menyimpannya, atau menaruhnya dalam analitik.

Membuka dan menutup dokumen

Ganti OpenDocument(...) sinkron dengan OpenDocumentAsync(...):

csharp
// Integrasi .NET 6 saat ini: Viewer diambil dari DI dan pembukaan dokumen bersifat asinkron.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Overload saat ini menerima jalur file atau stream, konfigurasi format opsional, DocOptions opsional, dan token pembatalan. Tutup sesi server secara eksplisit ketika browser tidak lagi membutuhkannya:

csharp
viewer.CloseDocument(token);

Jangan gunakan kembali token klasik setelah peralihan. Buka kembali setiap dokumen melalui API saat ini.

Kelas konfigurasi

API saat ini memisahkan kepedulian:

AspekTipe saat ini
Jalur middleware, lisensi, pendaftaran pluginDoconutOptions
Kata sandi, batas waktu, keamanan, watermarkDocOptions
Rendering format dan DPIPdfConfig, WordConfig, ExcelConfig, dan tipe BaseConfig lainnya
Default widget browserViewerConfig atau opsi JavaScript yang setara
CSS dan skrip yang dihasilkanCssConfig dan ScriptConfig

Jangan bawa DocOptions.ImageResolution ke depan sebagai kontrol rendering. Itu sudah usang; atur BaseConfig.ImageResolution pada konfigurasi spesifik format. Tinjau semua default alih-alih mengasumsikan konfigurasi klasik memiliki perilaku yang sama.

Toolbar Viewer, Pencarian, dan Anotasi

Jangan migrasikan skrip lama satu per satu. Aplikasi referensi saat ini menyusun satu paket halaman lengkap:

  1. hasilkan CSS Viewer dan CSS Search/Annotation berlisensi dengan ReferenceCss;
  2. render toolbar Viewer milik aplikasi;
  3. render searchBarMount, annBarMount, dan mount Viewer yang diperlukan;
  4. hasilkan skrip Viewer dan modul berlisensi dengan ReferenceScripts;
  5. muat viewerToolbar.js milik aplikasi;
  6. inisialisasi satu objViewer;
  7. inisialisasi Ribbon Search dan Anotasi berlisensi;
  8. panggil attach(objViewer) pada setiap Ribbon;
  9. buka dokumen dan panggil objViewer.View(token).

Search dan Annotation adalah modul yang terpasang pada Viewer yang sama, bukan toolbar independen. Toolbar utama milik aplikasi host; Ribbon Search dan Annotation tersemat, sebagai sumber daya yang dibatasi kemampuan.

Hapus file klasik yang disalin secara manual seperti documentLinks.js dan docViewer.UI.js hanya setelah halaman saat ini berfungsi dengan sumber daya yang dihasilkan oleh ReferenceCss dan ReferenceScripts.

Pendaftaran Plugin

Metode lisensi plugin statis klasik tidak mendaftarkan plugin saat ini. Instal dan daftarkan setiap paket yang dirilis secara eksplisit:

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

AddDoconut() memvalidasi kemampuan plugin yang terdaftar saat startup. Converter dan DICOM adalah plugin .NET 6 yang dirilis. Pencarian Normal dan Anotasi adalah fitur berlisensi bawaan, bukan paket AddPlugin<TPlugin>().

Keamanan sesi dan dokumen

Integrasi saat ini mengikat dokumen ke token opak dan sesi yang di‑cache. Dengan UnsafeMode = false default, UseDoconut() menambahkan keamanan akses dokumen dan host harus mengonfigurasi sesi ASP.NET:

csharp
builder.Services.AddDistributedMemoryCache(); // status sesi membutuhkan cache (MVC/Razor Pages sudah menambahkan satu)
builder.Services.AddSession();
app.UseSession();

Pertahankan DocOptions.IsSecured = true kecuali desain yang ditinjau memerlukan sebaliknya. Jangan pernah menggunakan UnsafeMode = true sebagai jalan pintas migrasi. Uji permintaan tanpa token, token yang rusak, token yang kedaluwarsa, dan token dari sesi peramban yang berbeda.

Aplikasi referensi Distributed menambahkan tiket akses dan detail transportasi. API tersebut tidak diperlukan untuk migrasi node tunggal normal.

Menguji migrasi

Setidaknya, verifikasi:

  • startup aplikasi dengan lisensi produksi dan setiap plugin yang terdaftar;
  • CSS/script Viewer dan semua permintaan halaman‑gambar di bawah jalur yang dipilih;
  • membuka dokumen, navigasi, zoom, thumbnail, cetak, dan penutupan eksplisit;
  • Pencarian pada dokumen yang berisi teks dan keadaan tidak dapat dicari dari file yang hanya gambar;
  • pemuatan, penyimpanan, ekspor, dan pengaturan kemampuan Anotasi;
  • penemuan target Converter, output, unduhan, dan status watermark;
  • halaman, frame, dan animasi DICOM; metadata teknis .NET 6 tidak tersedia;
  • dokumen yang dilindungi kata sandi, font khusus, teks non‑Latin, dan batas waktu yang dikonfigurasi;
  • penolakan token lintas sesi dan perilaku sesi yang kedaluwarsa;
  • mode seluler, mode gelap, dan jalur reverse‑proxy produksi.

Rencana rollback

Pertahankan artefak penyebaran klasik, paket yang cocok, file lisensi, dan sumber daya peramban yang disalin bersama‑sama. Rollback yang aman mengganti seluruh generasi aplikasi; itu tidak mencampur server klasik dengan skrip saat ini atau server saat ini dengan panggilan DocImage.axd klasik.

Sebelum pemotongan, dokumentasikan:

  • slot atau artefak penyebaran yang digunakan untuk rollback;
  • dampak basis data/cache, jika ada;
  • bagaimana sesi dokumen aktif akan dibatalkan;
  • pemeriksaan kesehatan dan dokumen percobaan yang digunakan untuk memutuskan rollback;
  • siapa yang dapat mengembalikan set paket dan konfigurasi sebelumnya.

Dokumentasi warisan

Manual klasik yang diterjemahkan tetap tersedia di Setup .NET 6 Legacy. Gateway integrasi Klasik yang baru menjelaskan sinyal identifikasi yang sama dan menautkan kembali ke panduan migrasi ini.

Pertahankan URL historis dalam bookmark dan tiket dukungan selama instalasi klasik masih ada. Itu mendokumentasikan generasi yang berbeda dan tidak diarahkan ke API saat ini.

Apakah halaman ini membantu?