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ıç ayarlarını, lisansları veya tarayıcı kaynaklarını değiştirmeden önce uygulamadaki API'lerden nesli tanımlayın.

Hangi .NET 6 entegrasyonunu kullanıyorsunuz?

Her iki sütun aynı uygulamada görülüyorsa, geçişi eksik olarak değerlendirin. Bir neslin kaynakları veya ara katmanı üzerinden diğer neslin belge jetonunu göndermeyin.

NuGet paket adının size söyleyemeyebileceği şey

Her iki nesil de Doconut.NET6 paket kimliği altında dağıtılmıştır. Bir paket referansı, kilit dosyası veya önbelleğe alınmış .nupkg tek başına barındırma API'sini tanımlamaz. Tam paket sürümünü kaydedin ve Program.cs, viewer oluşturulması, belge açma ve tarayıcı betikleri 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ümde sabitlenmiştir.

Geçişten ö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 sırlarını kaynak kontrolünün dışına çıkarın.
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.

Üretime geçmeden önce bir ortamda 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ılavuzun denetlediği sürüme yeniden üretilebilir 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 yan dosya Doconut.Viewer.<Capability>.lic dosyalarını arar. Viewer.DoconutLicense(...) veya Viewer.SetLicensePlugin(...) çağrısı klasik bir başlangıç mekanizması değildir. Lisansı DoconutOptions içine taşıyın, otomatik keşif kullanıldığında yan 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, mevcut bir eklenti derlemesi için hak sağladığını varsaymayın. Viewer, Search, Annotation, Converter ve DICOM'u onaylı 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:

// Klasik entegrasyon — sadece karşılaştırma; bunu mevcut SDK'ye karşı derlemeyin.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

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

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 geçici bir hizmettir. Belge oturum yöneticisi ve önbelleği, daha uzun ömürlü belge durumunu, belirli enjekte edilmiş Viewer örneği yerine, kendileri sahiplenir.

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

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

// Klasik entegrasyon — geçiş sırasında kaldırın.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

Mevcut işlem hattında:

1. Oturum güvenliği etkinken Doconut'tan önce UseSession() çağırın;
2. UseDoconut()'dan önce UseDoconutResources() çağırın;
3. ResourcesPath, oluşturulan kaynak URL'leri ve istemci ResPath'i hizalı tutun;
4. UseDoconut()'ı bir dala eşlerken, o dalı ve istemci BasePath'i hizalı 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ı şekilde kullanılan 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ç nokta, Razor sayfası, denetleyici veya kapsamlı 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önen token, sunucu tarafı bir belge oturumunu tanımlar. Bunu bir taşıyıcı kimlik bilgisi gibi davranın: kaydetmeyin, kalıcı hale getirmeyin ve analizlerde kullanmayın.

Belgeleri açma ve kapama

Eşzamanlı OpenDocument(...) yerine OpenDocumentAsync(...) kullanın:

// Mevcut .NET 6 entegrasyonu: Viewer DI'dan gelir ve belge açma asenkron olur.
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ı artık buna ihtiyaç duymadığında sunucu oturumunu açıkça kapatın:

viewer.CloseDocument(token);

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

Yapılandırma sınıfları

Mevcut API sorumlulukları ayırır:

DocOptions.ImageResolution'ı render kontrolü olarak ileriye taşımayın. 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. Viewer CSS ve lisanslı Arama/Açıklama CSS'ini ReferenceCss ile yayınlayın;
2. uygulama sahipliğindeki Viewer araç çubuğunu render edin;
3. searchBarMount, annBarMount ve gerekli Viewer bağlamasını render edin;
4. Viewer ve lisanslı modül betiklerini ReferenceScripts ile 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. attach(objViewer)'ı her Şeritte ç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‑kontrollü kaynaklardır.

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

Eklenti kaydı

Classic 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 .NET 6'da yayınlanan eklentilerdir. Normal Arama ve Açıklama 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.AddDistributedMemoryCache(); // oturum durumu bir önbelleğe ihtiyaç duyar (MVC/Razor Pages zaten bir tane ekler)
builder.Services.AddSession();
app.UseSession();

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

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

Geçişi test etme

En azından, doğrulayın:

• üretim lisansı ve tüm kayıtlı eklentilerle uygulama başlangıcı;
• 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;
• Açıklama (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;
• şifre 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;
• veritabanı/önbellek etkisi, varsa;
• 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 deneme belgesi;
• kimlerin önceki paket setini ve yapılandırmayı geri yükleyebileceği.

Eski belgeler

Çevrilmiş klasik kılavuz şu adreste mevcuttur: Eski .NET 6 kurulumu. 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 taleplerinde tutun. Bu, farklı bir nesli belgelemektedir ve mevcut API'ye yönlendirilmez.