Klasik .NET 6 entegrasyonundan geçiş

Doconut iki ayrı .NET 6 entegrasyonuna sahiptir. Aynı Doconut.NET6 paket adını kullanabilirler, bu yüzden paketleri, başlangıcı, lisansları veya tarayıcı kaynaklarını değiştirmeden önce uygulamadaki API'lerden nesli belirleyin.

Hangi .NET 6 entegrasyonunu kullanıyorsunuz?

Her iki sütun aynı uygulamada bulunuyorsa, geçişi eksik olarak değerlendirin. Bir belge token'ını diğer nesilden gelen kaynaklar veya ara katman üzerinden göndermeyin.

NuGet paket adının size söyleyemeyebileceği neden

Her iki nesil de Doconut.NET6 paket kimliği altında dağıtıldı. Bu nedenle bir paket referansı, kilit dosyası veya önbelleğe alınmış .nupkg tek başına barındırma API'sını tanımlamaz. Tam paket sürümünü kaydedin ve Program.cs, viewer oluşturulması, belge açma ve tarayıcı betiklerini birlikte inceleyin.

Bu kılavuz için denetlenen mevcut sürüm Doconut.NET6 26.7.0'dır. İsteğe bağlı genel paketleri Doconut.NET6.Converter ve Doconut.NET6.Dicom olup, çekirdek paketle aynı sürüme sabitlenmiştir.

Geçiş yapmadan önce

1. Mevcut uygulamanın bir dalını ve dağıtılabilir bir yedeğini oluşturun.
2. Tam çekirdek ve eklenti paket sürümlerini kaydedin.
3. Her DocImage.axd eşlemesini, new Viewer(...) çağrısını, lisans yükleme çağrısını, kopyalanmış Doconut betiğini, özel araç çubuğu eylemini ve belge açma uç noktasını envantere alın.
4. Mevcut .lic dosyalarını ve dağıtım gizli anahtarlarını kaynak kontrolünün dışında koruyun.
5. PDF, Office, görüntü, CAD, e-posta, DICOM, aranabilir, şifre korumalı ve açıklamalı belgelerden temsili bir set yakalayın.
6. Mevcut oturum zaman aşımını, güvenlik davranışını, yazı tiplerini ve platform ayarlarını kaydedin.

Üretimi değiştirmeden önce bir ortamı geçiş yapın. Güncel entegrasyon hizmet ömrünü, istek yönlendirmesini, oturum sahipliğini ve istemci kaynak teslimini değiştirir.

Paket ve lisans uyumluluğu

Çekirdek paketi kasıtlı olarak değiştirin veya güncelleyin; yeni API'yi seçmek için aynı paket kimliğine güvenmeyin. Varsayılan komut en son kararlı sürümü kurar:

dotnet add package Doconut.NET6

Bu kılavuz tarafından denetlenen sürüme tekrarlanabilir bir geçiş için sürümü ayrı bir seçenek olarak geçirin:

dotnet add package Doconut.NET6 --version 26.7.0

Her Doconut eklentisini çekirdek paketle aynı sürümde tutun. Güncel entegrasyon lisansları AddDoconut() sırasında bir kez yükler ve şu önceliği kullanır:

LicenseStream > LicenseContent > LicensePath > automatic discovery

Otomatik keşif Doconut.Viewer.lic ve yardımcı Doconut.Viewer.<Capability>.lic dosyalarını arar. Viewer.DoconutLicense(...) veya Viewer.SetLicensePlugin(...) klasik çağrısı güncel bir başlangıç mekanizması değildir. Lisansı DoconutOptions'a taşıyın, otomatik keşif kullanırken yardımcı dosyaları birlikte tutun, bir lisans değişikliğinden sonra yeniden başlatın ve yetenekleri IDoconutLicenseService aracılığıyla doğrulayın.

Eski bir eklenti lisansının varlığının, güncel bir eklenti derlemesi için hak sağladığını varsaymayın. Viewer, Search, Annotation, Converter ve DICOM'u onaylanmış sürüm artefaktlarıyla ayrı ayrı test edin.

Başlangıç ve bağımlılık enjeksiyonu

Klasik uygulamalar, Viewer'ı ASP.NET önbelleği ve istek erişimcisi bağımlılıklarıyla oluşturur:

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

Mevcut entegrasyon, Doconut'u bir kez kaydeder ve bağımlılık enjeksiyonundan Viewer alır:

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

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

Viewer geçici bir hizmettir. Belge oturum yöneticisi ve önbelleği, belirli enjekte edilmiş Viewer örneği yerine, daha uzun ömürlü belge durumunun sahibidir.

Ara Katman Yazılımı ve kaynak yönlendirme

DocImage.axd'yi algılayan klasik MapWhen dalını kaldırın:

// Classic integration — remove during the cutover.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

Mevcut işlem hattında:

1. UseSession()'ı Doconut'tan önce, oturum güvenliği etkinken çağırın;
2. UseDoconutResources()'ı UseDoconut()'dan önce çağırın;
3. ResourcesPath, oluşturulan kaynak URL'lerini ve istemci ResPath'i uyumlu tutun;
4. UseDoconut()'ı bir dala eşlerken, o dalı ve istemci BasePath'i uyumlu tutun.

MiddlewarePath doğrulanmış bir yapılandırmadır; tek başına bir ASP.NET Core dalı oluşturmaz. Yukarıdaki derleme örneğindeki basit işlem hattını ya da istemci tarafından tutarlı bir şekilde kullanılan açık bir app.Map("/doconut", branch => branch.UseDoconut()) düzenlemesini kullanın.

Viewer oluşturma ve ömür süresi

Viewer nesnelerinin uygulama sahipliğindeki önbelleklerini kaldırın. Viewer'ı bir uç noktaya, Razor sayfasına, denetleyiciye veya kapsamlı bir uygulama hizmetine enjekte edin:

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

Döndürülen token, sunucu tarafı bir belge oturumunu tanımlar. Bunu bir taşıyıcı kimlik bilgisi gibi ele alın: kaydetmeyin, kalıcı hale getirmeyin veya analizlerde kullanmayın.

Belgeleri açma ve kapama

Eşzamanlı OpenDocument(...)'ı OpenDocumentAsync(...) ile değiştirin:

// Current .NET 6 integration: Viewer comes from DI and document opening is asynchronous.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Mevcut aşırı yüklemeler bir dosya yolu veya akışı, isteğe bağlı bir format yapılandırması, isteğe bağlı DocOptions ve bir iptal token'ı kabul eder. Tarayıcı buna artık ihtiyaç duymadığında sunucu oturumunu açıkça kapatın:

viewer.CloseDocument(token);

Geçiş sonrası klasik bir token'ı yeniden kullanmayın. Her belgeyi mevcut API üzerinden tekrar açın.

Yapılandırma sınıfları

Mevcut API, endişeleri ayırır:

DocOptions.ImageResolution'ı render kontrolü olarak ilerletmeyin. Bu artık kullanılmamaktadır; format‑spesifik yapılandırmada BaseConfig.ImageResolution'ı ayarlayın. Klasik bir yapılandırmanın aynı davranışı gösterdiğini varsaymak yerine tüm varsayılanları gözden geçirin.

Viewer araç çubuğu, Arama ve Açıklama

Eski betikleri tek tek taşımayın. Mevcut referans uygulamaları tek bir tam sayfa paketi oluşturur:

1. ReferenceCss ile Viewer CSS ve lisanslı Arama/Açıklama CSS'sini yayınlayın;
2. uygulama sahipliğindeki Viewer araç çubuğunu render edin;
3. searchBarMount, annBarMount ve gerekli Viewer montajını render edin;
4. ReferenceScripts ile Viewer ve lisanslı modül betiklerini yayınlayın;
5. uygulamanın kendi viewerToolbar.js dosyasını yükleyin;
6. bir objViewer başlatın;
7. lisanslı Arama ve Açıklama Şeritlerini başlatın;
8. her Şerit üzerinde attach(objViewer) çağırın;
9. belgeyi açın ve objViewer.View(token) çağırın.

Arama ve Açıklama, aynı Viewer'a eklenen modüllerdir, bağımsız araç çubukları değildir. Ana araç çubuğu ana uygulamaya aittir; Arama ve Açıklama Şeritleri gömülü, yetenek‑kısıtlamalı kaynaklardır.

documentLinks.js ve docViewer.UI.js gibi manuel kopyalanmış klasik dosyaları, yalnızca mevcut sayfa ReferenceCss ve ReferenceScripts tarafından yayınlanan kaynaklarla çalıştıktan sonra kaldırın.

Eklenti kaydı

Klasik statik eklenti‑lisans yöntemleri mevcut eklentileri kaydetmez. Her yayınlanan paketi açıkça kurun ve kaydedin:

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

AddDoconut() başlatmada kayıtlı eklenti yeteneklerini doğrular. Converter ve DICOM, yayınlanmış .NET 6 eklentileridir. Normal Search ve Annotation, yerleşik lisanslı özelliklerdir, AddPlugin<TPlugin>() paketleri değildir.

Oturum ve belge güvenliği

Mevcut entegrasyon belgeleri opak token'lara ve önbelleğe alınmış oturumlara bağlar. Varsayılan UnsafeMode = false ile, UseDoconut() belge erişim güvenliğini ekler ve ana bilgisayar ASP.NET oturumunu yapılandırmalıdır:

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

DocOptions.IsSecured = true değerini, gözden geçirilmiş bir tasarım aksi gerektirmedikçe tutun. Geçiş kısayolu olarak UnsafeMode = true asla kullanmayın. Token olmayan, hatalı biçimlendirilmiş, süresi dolmuş ve farklı bir tarayıcı oturumundan gelen token'ları içeren istekleri test edin.

Dağıtık referans uygulaması erişim biletleri ve taşıma detayları ekler. Bu API'lar normal tek düğüm geçişi için gerekli değildir.

Geçişi test etme

En azından, şunları doğrulayın:

• üretim lisansı ve tüm kayıtlı eklentilerle uygulama başlatma;
• Viewer CSS/skriptleri ve seçilen yollar altındaki tüm sayfa‑görüntü istekleri;
• belge açma, gezinme, yakınlaştırma, küçük resimler, yazdırma ve açıkça kapatma;
• metin içeren bir belgede Arama ve yalnızca görüntü dosyasının aranamaz durumu;
• Annotation yükleme, kaydetme, dışa aktarma ve yetenek kısıtlaması;
• Converter hedef keşfi, çıktı, indirme ve filigran durumu;
• DICOM sayfaları, çerçeveler ve animasyon; .NET 6 teknik meta verileri mevcut değil;
• parola korumalı belgeler, özel yazı tipleri, Latin dışı metin ve yapılandırılmış zaman aşımı;
• oturumlar arası token reddi ve süresi dolmuş oturum davranışı;
• mobil, karanlık mod ve üretim ters proxy yolu.

Geri dönüş planı

Klasik dağıtım artefaktını, eşleşen paketleri, lisans dosyalarını ve kopyalanmış tarayıcı kaynaklarını birlikte tutun. Güvenli bir geri dönüş, tüm uygulama neslini değiştirir; klasik bir sunucuyu mevcut skriptlerle veya mevcut bir sunucuyu klasik DocImage.axd çağrılarıyla karıştırmaz.

Geçişten önce, belgeleyin:

• geri dönüş için kullanılan dağıtım yuvası veya artefakt;
• varsa veritabanı/önbellek etkisi;
• aktif belge oturumlarının nasıl geçersiz kılınacağı;
• geri dönüş kararını vermek için kullanılan sağlık kontrolü ve test belgesi;
• önceki paket setini ve yapılandırmayı kimlerin geri yükleyebileceği.

Eski belgeler

Çevrilmiş klasik kılavuz, Eski .NET 6 kurulumu adresinde hâlâ mevcuttur. Yeni Klasik entegrasyon geçidi aynı tanımlama sinyallerini açıklar ve bu geçiş kılavuzuna geri bağlanır.

Klasik kurulumlar hâlâ mevcutken tarihsel URL'yi yer imlerinde ve destek biletlerinde tutun. Bu, farklı bir nesli belgeler ve mevcut API'ye yönlendirilmez.