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

Görünüm alanı boş, tarayıcı konsolu /doconut-res/... için 404 hatalarıyla dolu
UseDoconutResources() eksik, ya da UseDoconut()'den sonra yer alıyor. Boru hattında ilk olarak 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'dır: '/doconut', başka bir ana bilgisayara yapılan bir istek olan //doconut/DocImage.axd haline gelir. 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:

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 başlangıçta Unable to resolve service for type 'IDistributedCache' ile 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 gösteriyor:

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

Token süresi doldu (kayma penceresi, 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ız oluyor

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ı hata) engeller, su işaretiyle bozulmaktan ziyade; 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 yeteneğini veren bir lisans yok — genellikle uygulama başladıktan sonra süresi dolan Geçici bir lisans. Yetki veren bir lisans kurun ve IDoconutLicenseService üzerindeki IsCapabilityGranted(LicenseCapability.Dicom)'yi doğrulayın. Eksik veya yetersiz geçici olmayan bir hak, genellikle AddDoconut() sırasında başarısız olur.

FormatNotSupportedException:

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

Yerleşik, eklenti ya da özel bir görüntüleyici 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 kaydedilen bir eklentiden bahsediyor — mevcut geçici olmayan lisans bu eklenti yeteneğini vermiyor. Kaydı kaldırın veya bunu sağlayan bir lisans yükleyin. Eksik bir lisans ve eski bir TRIAL dosyası hiçbir eklenti yeteneği sağlamaz.

ArgumentException, AddDoconut() tarafı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ı

CS1705 derleyici hatası, ya da 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.NET6 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 geri yüklemesine izin verin (paket tarafından bildirildiği gibi System.Text.Json 8.0.6 ve System.Text.Encodings.Web 8.0.0).

Çı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ı. Etkin bir Geçici lisans altında yalnızca eklenti çıktısı filigranlanır. Ücretli bir lisansın abonelik tarihinden sonra yayınlanan bir derleme filigranlanmaz: açma işlemi LicenseException hatası verir. 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ı .NET 6'da 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. Yükleyin veya FontFolders (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örünüyor ancak dışa aktarma "Image blocked" kutusu gösteriyor — görüntünün sunucusu özel veya döngüsel bir adrese sahip, bu yüzden sunucu getirmeyi reddediyor. Bakınız Açıklamalar.

Linux

Herhangi bir belge açma şu hatayla başarısız olur:

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.

Yazı tipi yapılandırma kütüphanesini yükleyin: apt-get install -y libfontconfig1 (RHEL/Fedora'da fontconfig). Bakınız Kurulum.

Herhangi bir belge açma şu hatayla başarısız olur:

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 daha yeni bir SkiaSharp sürümüne, doğrudan ya da başka bir kütüphane aracılığıyla başvuruyor. SkiaSharp.NativeAssets.Linux'i aynı sürümde ekleyin.

Herhangi bir belge açma şu hatayla başarısız olur:

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 imaj 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ıyor. Ölçü uyumlu yazı tiplerini yükleyin (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 çalıştırın. Asya metni boş kutular olarak gösteriliyorsa fonts-noto-cjk gerekir.

Değerlendirme aşamasında çalışan özellik, üretimde sessiz

Klasik canlıya geçiş sürprizi: bir aktif Geçici lisans her yeteneği verir; satın aldığınız lisans sadece 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 lisansla AddDoconut() sırasında başarısız olur. Dağıtımdan ö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 sunar.
  • İçerik taranmış/görüntü‑only olduğundan, normal Arama eşleşecek bir metin katmanına sahip değildir. Kullanın
    metin‑taşıyan bir kaynak veya metni koruyan bir PDF projeksiyonu.
  • 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ğrıda gelir.

Hâlâ takıldı 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?