Sorun Giderme
Yaygın hataları teşhis edin
Aşağıdaki her mesaj, Doconut'un ürettiği tam metindir ve semptomlara göre düzenlenmiştir. Hatanızı bulun, düzeltmeyi uygulayın.
Görüntüleyici hiçbir şey göstermiyor
Boş görüntüleyici alanı, tarayıcı konsolu /doconut-res/... için 404 hatalarıyla dolu
UseDoconutResources() eksik, ya da UseDoconut()'den sonra yer alıyor. İşlem hattında ilk gelmelidir.
Görüntüleyici The viewer handler could not be reached (no response). rapor ediyor
İstek hiçbir zaman yanıt almadı. Yaygın bir neden, / ile başlayan bir BasePath'dir: '/doconut', başka bir ana bilgisayara istek olan //doconut/DocImage.axd'e dönüşür. Başındaki eğik çizgi olmadan yazın (BasePath: 'doconut').
Görüntüleyici Please make sure your middleware is configured. rapor ediyor
Sayfa uç noktası 404 yanıtı verdi: UseDoconut(), istemcinin BasePath'nin işaret ettiği yerde monte edilmemiş. app.Map("/doconut", branch => branch.UseDoconut()) ile istemci BasePath: 'doconut' kullanır.
HTTP 500 ile:
Session middleware not configured. Call UseSession() before UseDoconut().Doconut'un token güvenliği (varsayılan olarak açıktır) ASP.NET oturum durumuna ihtiyaç duyar. Doconut ara katman dalından önce builder.Services.AddSession() ve app.UseSession() ekleyin. Oturum durumu ayrıca bir önbellek gerektirir: minimal-API uygulamasında builder.Services.AddDistributedMemoryCache() ekleyin, ya da uygulama Unable to resolve service for type 'IDistributedCache' ile başlatmada durur (MVC ve Razor Pages uygulamaları zaten birini kaydeder).
Sayfa alanında şu metni gösteren bir hata resmi:
You Are Not Authorized To View This Page.Token farklı bir tarayıcı oturumu tarafından açıldı. Yaygın nedenler: oturum çerezi sayfa isteklerine ulaşmıyor (çapraz kaynak ayarı, SameSite politikası, çerez kavanozu olmayan bir API istemcisi), ya da uygulama yeniden başlatıldı (yeni oturum anahtarları). Bu, tasarlandığı gibi çalışan güvenlik katmanıdır — Core Concepts → Sessions & Security bölümüne bakın. Reddetme, durum 200 ile sunulan bir resimdir, bu yüzden yalnızca durum kodlarını kontrol eden bir izleyici bunu bir sayfa olarak sayar.
Şu metni gösteren bir hata resmi:
Document session not found. Please re-open document.Token süresi doldu (kayma penceresi, varsayılan 60 dakika — DocOptions.TimeOut) ya da oturum kapandı. Yeni bir token için belgeyi yeniden açın.
Sunucu iyi çalışıyor ama sayfa hatalı davranıyor — hiçbir yerde hata yok
Bunlar, bir uygulamayı ilerletirken ilk şüphelenmeniz gereken hata modlarıdır. Üçü de sunucunun mükemmel çalışmasını, belgenin doğru şekilde render edilmesini sağlar ve tarayıcı konsolunda hiçbir şey raporlamaz.
Asla durmayan bir dönen yükleme göstergesi. Görüntüleyici geri çağırmalarınız, konteyner kimliğinin adıyla aynı olan global fonksiyonlar olarak tanımlanmıştır — ctlDoc_OnViewerReady() ve arkadaşları. Önceki görüntüleyici bu adları arıyordu; bu sürüm aramıyor. Yükleme göstergesini gizleyecek işleyici hiç çalışmaz. Bunun yerine fonksiyonları seçenek olarak geçirin:
function ctlDoc_OnViewerBusy() { /* meşgul göstergenizi göster */ }
function ctlDoc_OnViewerReady() { /* gizle */ }
function ctlDoc_Copy(text) { /* kopyalanan metni kullan */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* ilerlemeyi bildir */ }
const objViewer = $('#div_ctlDoc').docViewer({
// ... mevcut seçenekleriniz ...
onViewerBusy: ctlDoc_OnViewerBusy,
onViewerReady: ctlDoc_OnViewerReady,
onCopy: ctlDoc_Copy,
onAutoLoadStatus: ctlDoc_AutoLoadStatus
});Yükleme göstergesinin arkasındaki belge iyidir. Tam seçenek listesi ViewerConfig içinde.
Eksik görüntüleyici simgeleri veya çerçeve, diğer sayfalar doğru. ResPath boş ya da uygulama köküne işaret ediyor — önceki kütüphanede doğru, burada yanlış. UseDoconutResources()'nin monte ettiği önek adını belirtmelidir:
ResPath: 'doconut-res/images' // veya '<your ResourcesPath>/images'Paylaşımlı depolamadan hizmet verirken sonraki sayfalarda bozuk döşemeler. Henüz yazılmakta olan sayfalar 202 Accepted yanıtını verir. retryOn409: true olmayan bir istemci bunu başarısız bir resim olarak değerlendirir. Bkz. Distributed Deployments.
Belge açma hatası
LicenseException ile bir reddetme mesajı — lisans dosyası bulundu ancak reddedildi (geçersiz imza, değiştirilmiş, kara listeye alınmış veya lisansın sürüm/güncelleme penceresi dışındaki bir yapı). Bu durum, bir filigran yerine (fail-fast) açmayı engeller; nedeni için License.RejectionMessage okuyun.
LicenseException:
This document type requires the 'Dicom' plugin license.Uzantı yalnızca bir eklenti (burada: DICOM) tarafından işlenir. Eklenti kaydedilmiş, ancak artık hiçbir lisans bu yeteneği vermemektedir — genellikle uygulama başladıktan sonra süresi dolmuş bir Geçici lisans. Yetki veren bir lisans kurun ve IsCapabilityGranted(LicenseCapability.Dicom)'yi IDoconutLicenseService üzerinde doğrulayın. Eksik veya yetersiz geçici olmayan bir yetki genellikle daha önce, AddDoconut() sırasında başarısız olur.
FormatNotSupportedException:
Document format '<extension>' is not supported.Hiçbir görüntüleyici — yerleşik, eklenti veya özel — bu uzantıyı talep etmez. Desteklenen formatlar listesini kontrol edin; kendi formatlarınız için DoconutOptions.RegisterViewer bir tane ekleyebilir.
InvalidDataException — dosya içeriği bozuk veya uzantısıyla eşleşmiyor (ör. yeniden adlandırılmış bir dosya). Açmadan önce yüklemeleri doğrulayın.
InvalidOperationException:
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().DocumentConverter'i Dönüştürücü eklentisini kaydetmeden çözdünüz.
Başlatma hatası
InvalidOperationException, AddPlugin aracılığıyla kaydedilen bir eklentiden bahsediyor — mevcut geçici olmayan lisans o eklentinin yeteneğini vermiyor. Kaydı kaldırın veya yetki veren bir lisans kurun. Eksik bir lisans ve eski bir TRIAL dosyası hiçbir eklenti yeteneği sağlamaz.
ArgumentException, AddDoconut()'dan:
DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.Fail-fast seçenek doğrulaması — hatalı yolu düzeltin.
Derleme / bağımlılık hataları
Paket hiç kurulamaz — Doconut.NETStandard hedefler
netstandard2.1, bu yüzden NuGet bir .NET Framework projesini reddeder. Bu çözülebilir bir geri yükleme hatası değildir: .NET Framework netstandard2.1'i tüketemez. Bunun yerine
Doconut.NETFramework paketini kullanın.
Derleyici hatası CS1705, ya da bir belge açılırken çalışma zamanında:
Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'Projeniz System.Text.Json veya System.Text.Encodings.Web sürümünü Doconut.NETStandard tarafından bildirilen 9.0.x bağımlılıklarının altına sabitlemiş. Düşürmeyi kaldırın ve NuGet'in paket grafiğini geri yüklemesine izin verin (System.Text.Json 9.0.0 ve System.Text.Encodings.Web 9.0.0 olarak paket tarafından belirtilen).
Paketi yükselttikten hemen sonra bir dizi derleme hatası — bu beklenendir.
26.8.0, 26.7.0'dan farklı bir API yüzeyine sahiptir, uyumlu bir güncelleme değildir. Hataların çoğu, kök Doconut ad alanına taşınan using satırlarıdır; tek tek yamalamak yerine .NET Standard 2.1'e Geçiş bağlantısını kullanarak ilerleyin.
TypeInitializationException, ilk sunum dosyasında:
Could not load ... System.Drawing.Common, Version=6.0.0.0Sunum motoru, paket tarafından bildirilen System.Drawing.Common 6.0.0 sürümünü kesinlikle gerektirir. Bu bağımlılığı kaldırmayın veya geçersiz kılmayın — her PPT/PPTX/PPS/POT/ODP açma işlemi onsuz başarısız olur.
Çıktı hatalı
Sayfalar bir filigran taşıyor — uygulama değerlendirme modunda: lisans dosyası bulunamadı, süresi dolmuş Geçici lisans veya geçersiz bir alan adı. Aktif bir Geçici lisans altında, yalnızca eklenti çıktısı filigranlıdır. Ücretli bir lisansın abonelik tarihinden sonra yayınlanan bir yapı filigranlı değildir: açma sırasında LicenseException fırlatılır. IDoconutLicenseService'ı inceleyin (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — Lisanslama sayfasının IDoconutLicenseService referansı hazır bir uç nokta gösterir.
Eski belgeler bozuk metin gösteriyor — kod sayfası kodlamaları varsayılan olarak yüklenmez. Başlangıçta bir kez ekleyin:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);Yanlış veya yerine konmuş yazı tipleri — sunucuda belgenin yazı tipleri yok. Onları kurun veya FontFolders'ı (WordConfig/PptConfig üzerinde) bu yazı tiplerini içeren bir klasöre yönlendirin.
Görüntü ek açıklaması görüntüleyicide görünür ancak dışa aktarma "Image blocked" kutusu gösterir — görüntünün sunucusu özel veya döngüsel bir adrese sahiptir ve sunucu bunu almaya izin vermez. Bakınız Ek Açıklamalar.
Özellik değerlendirme aşamasında çalışıyor, üretimde sessiz
Klasik canlı geçiş sürprizi: bir aktif Geçici lisans tüm yetenekleri verir; satın aldığınız lisans yalnızca satın aldıklarınızı verir. Arama ve açıklama paketleri, yetenekleri eksik olduğunda kaybolabilir. Kayıtlı Dönüştürücü veya DICOM eklentileri yetersiz geçici olmayan bir lisansla AddDoconut() sırasında başarısız olur. Dağıtıma başlamadan önce etkinleştirdiğiniz her özelliğe karşı IsCapabilityGranted(...)'yi karşılaştırın.
Arama hiçbir şey bulamıyor (ya da çok az)
- Doğrudan bir PDF için,
AllowSearchaçılışta etkinleştirilmemişti. Word, Excel ve PowerPoint aynı anahtarı iç içe geçmişPdfConfigaracılığıyla ortaya çıkar. - İçerik taranmış/görüntü‑only olduğu için normal Arama eşleşecek bir metin katmanına sahip değildir. Metin içeren bir kaynak ya da metni koruyan bir PDF projeksiyonu kullanın.
- HTML ve MS Project (MPP) varsayılan ayarlarında aranabilir değildir —
DefaultRender = false'yi, PDF projeksiyonu aracılığıyla yerel bir metin katmanı ile render edecek şekilde ayarlayın. Word, Excel, PowerPoint, TXT, Visio, e‑posta, EPUB ve MHT, katalog varsayılanlarında aranabilir. objViewer.CanSearch(), başlatmadan sonrafalsedurumundadır — çözülen formatın standart bir arama yolu yoktur. Bu karar, Arama lisansından ayrı olup, ikisini de doğrulayın.- Sayfa,
objViewer.Search(...)'nin dönüş değerini okur — sayı, üçüncü argümanı olan bir geri çağırmada gelir.
Hâlâ takıldınız mı?
Sorunu minimal Quick Start uygulamasıyla izole edin; eğer orada da tekrarlanıyorsa, belge, Program.cs ve lisans tanı teşhis çıktısı ile destek birimine başvurun.
Bu sayfa yardımcı oldu mu?