Sorun Giderme

Yaygın hataları teşhis edin

Aşağıdaki her mesaj, Doconut'un ürettiği tam metindir ve belirtiye 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 sırada olmalıdır.

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, BasePath'nin / ile başlamasıdır: '/doconut', //doconut/DocImage.axd haline gelir, başka bir ana bilgisayara yapılan istek. 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ını verdi: UseDoconut(), istemcinin BasePath'nin işaret ettiği yerde monte edilmemiş. app.Map("/doconut", branch => branch.UseDoconut()) ile istemci BasePath: 'doconut' kullanıyor.

HTTP 500 ile:

text
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 hatayı gösteren bir resim:

text
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 köken yapılandırması, SameSite politikası, çerez tutucu 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.

Bir hata resmi şu şekilde:

text
Document session not found. Please re-open document.

Token süresi doldu (kaydırmalı pencere, varsayılan 60 dakika — DocOptions.TimeOut) ya da oturum kapatıldı. Yeni bir token için belgeyi yeniden açın.

Bir belge açma başarısızlığı

LicenseException reddetme mesajı ile — lisans dosyası bulundu ancak reddedildi (geçersiz imza, değiştirilmiş, kara listeye alınmış veya lisansın sürüm/güncelleme penceresinin dışındaki bir yapı). Bu durum, belgeyi açmayı (hızlı başar) engeller, filigrana düşürmek yerine; nedeni için License.RejectionMessage okuyun.

LicenseException:

text
This document type requires the 'Dicom' plugin license.

Uzantı yalnızca bir eklenti (burada: DICOM) tarafından işlenir. Eklenti kaydedildi, ancak artık hiçbir lisans yeteneğini vermiyor — genellikle uygulama başladıktan sonra süresi dolmuş Geçici bir lisans. Yetki veren bir lisans kurun ve IsCapabilityGranted(LicenseCapability.Dicom)'i IDoconutLicenseService üzerinde doğrulayın. Eksik veya yetersiz geçici olmayan bir hak genellikle daha erken, AddDoconut() sırasında başarısız olur.

FormatNotSupportedException:

text
Document format '<extension>' is not supported.

Hiçbir görüntüleyici — yerleşik, eklenti ya da özel — bu uzantıyı talep etmiyor. 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:

text
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

DocumentConverter'i Converter eklentisini kaydetmeden çözdünüz.

Başlangıçta hatalar

InvalidOperationException, AddPlugin aracılığıyla kaydedilmiş bir eklentiden bahsediyor — mevcut geçici olmayan lisans bu eklenti yeteneğini vermiyor. Kaydı kaldırın veya bu yetkiyi veren bir lisans kurun. Eksik bir lisans ve eski bir TRIAL dosyası hiçbir eklenti yeteneği sağlamaz.

ArgumentException, AddDoconut() kaynağından:

text
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.

Hızlı hata ayıklama seçenekleri doğrulaması — hatalı yolu düzeltin.

Derleme / bağımlılık hataları

Derleyici hatası CS1705, veya bir belge açılırken çalışma zamanında:

text
Could not load file or assembly 'System.Text.Json, Version=8.0.0.0'

Projeniz, Doconut.NET8 tarafından bildirilen 8.0.x bağımlılıklarının altında System.Text.Json veya System.Text.Encodings.Web sürümünü sabitlemiş. Düşürmeyi kaldırın ve NuGet'in paket grafiğini (System.Text.Json 8.0.5 ve System.Text.Encodings.Web 8.0.0) geri yüklemesine izin verin.

Çıktı hatalı görünüyor

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 derleme filigranlı değildir: açma sırasında LicenseException hatası atılır. IDoconutLicenseService'i 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österir — kod sayfası kodlamaları .NET 8'de varsayılan olarak yüklenmez. Başlangıçta bir kez ekleyin:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Yanlış veya yerine konmuş yazı tipleri — sunucuda belgenin yazı tipleri yok. Bunları kurun veya FontFolders'i (WordConfig/PptConfig üzerinde) bu tipleri içeren bir klasöre yönlendirin. Linux'ta, aşağıya bakın.

Bir görüntü açıklaması görüntüleyicide gösterilir ancak dışa aktarımda "Image blocked" kutusu bulunur — görüntünün sunucusu özel veya döngüsel bir adrese sahiptir ve sunucu bunu almaya izin vermez. Bakınız Açıklamalar.

Linux

Herhangi bir belge açılırken şu hata oluşur:

text
The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Font yapılandırma kütüphanesini kurun: apt-get install -y libfontconfig1 (RHEL/Fedora üzerinde fontconfig). Bakınız Kurulum.

Herhangi bir belge açılırken şu hata oluşur:

text
The application uses a newer SkiaSharp than Doconut's native graphics library. Add the package SkiaSharp.NativeAssets.Linux at the same version as the application's SkiaSharp; see the Linux section of the Doconut documentation.

Uygulama, doğrudan ya da başka bir kütüphane aracılığıyla daha yeni bir SkiaSharp sürümüne referans veriyor. SkiaSharp.NativeAssets.Linux'i aynı sürümde ekleyin.

Herhangi bir belge açılırken şu hata oluşur:

text
The native graphics library for this platform was not found next to the application. Doconut supports Windows x64/x86 and glibc-based Linux x64 (Alpine/musl is not supported); see the Linux section of the Doconut documentation.

Ana makine desteklenen bir platform değil. Alpine ve diğer musl tabanlı dağıtımlar desteklenmez: Debian veya Ubuntu tabanlı bir görüntü kullanın.

Metin Windows'takinden daha geniş ya da dar, ya da satırlar farklı kırılıyor — belgenin yazı tipleri yüklü değil, bu yüzden Doconut en yakın yüklü yazı tipini kullanır. Metrik uyumlu yazı tiplerini kurun (fonts-liberation Arial, Times New Roman ve Courier New için; fonts-crosextra-carlito ve fonts-crosextra-caladea Calibri ve Cambria için), ya da kendi lisanslı yazı tiplerinizi /usr/share/fonts/'a kopyalayın ve fc-cache -f'i çalıştırın. Asya metni boş kutular olarak gösteriliyorsa fonts-noto-cjk gerekir.

Özellik değerlendirme aşamasında çalıştı, üretimde sessiz

Klasik canlı yayına geçiş sürprizi: aktif Geçici lisans her yeteneği 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. Yetersiz geçici olmayan lisansa sahip Kayıtlı Dönüştürücü veya DICOM eklentileri 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 (veya çok az)

  • Doğrudan bir PDF için, AllowSearch açılışta etkinleştirilmemişti. Word, Excel ve PowerPoint aynı anahtarı iç içe geçmiş PdfConfig aracılığıyla ortaya çıkar.
  • İçerik taranmış/görüntü‑only olduğundan, 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 ayarlayarak PDF projeksiyonu üzerinden yerel bir metin katmanı ile render edilmelerini sağlayın. Word, Excel, PowerPoint, TXT, Visio, e‑posta, EPUB ve MHT, katalog varsayılanlarında aranabilir.
  • objViewer.CanSearch(), başlatmadan sonra false durumundadı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ında, 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, belgeyi, Program.cs'inizi ve lisans tanı teşhis çıktısını destek birimine gönderin.

Bu sayfa yardımcı oldu mu?