Rozwiązywanie problemów

Diagnozowanie typowych błędów

Każda wiadomość poniżej to dosłowny tekst generowany przez Doconut, uporządkowany według objawów. Znajdź swój błąd, zastosuj rozwiązanie.

Podgląd nie wyświetla nic

Pusty obszar podglądu, konsola przeglądarki pełna 404 dla /doconut-res/...
UseDoconutResources() jest brakujący lub umieszczony po UseDoconut(). Musi być pierwszy w potoku.

Podgląd zgłasza The viewer handler could not be reached (no response).
Żądanie nigdy nie otrzymało odpowiedzi. Częstą przyczyną jest BasePath, który zaczyna się od /: '/doconut' staje się //doconut/DocImage.axd, żądanie do innego hosta. Napisz je bez początkowego ukośnika (BasePath: 'doconut').

Podgląd zgłasza Please make sure your middleware is configured.
Punkt końcowy strony odpowiedział 404: UseDoconut() nie jest zamontowany tam, gdzie wskazuje BasePath klienta. Z app.Map("/doconut", branch => branch.UseDoconut()), klient używa BasePath: 'doconut'.

HTTP 500 z:

text
Session middleware not configured. Call UseSession() before UseDoconut().

Bezpieczeństwo tokenów Doconut (włączone domyślnie) wymaga stanu sesji ASP.NET. Dodaj builder.Services.AddSession() i app.UseSession() przed gałęzią pośrednika Doconut. Stan sesji wymaga również pamięci podręcznej: w aplikacji minimal-API dodaj builder.Services.AddDistributedMemoryCache(), albo aplikacja zatrzyma się przy uruchamianiu z Unable to resolve service for type 'IDistributedCache' (aplikacje MVC i Razor Pages rejestrują już jedną).

Obraz błędu w obszarze strony z napisem:

text
You Are Not Authorized To View This Page.

Token został otwarty w innej sesji przeglądarki. Typowe przyczyny: ciasteczko sesji nie dociera do żądań strony (konfiguracja cross-origin, polityka SameSite, klient API bez pojemnika na ciasteczka), lub aplikacja została ponownie uruchomiona (nowe klucze sesji). To warstwa bezpieczeństwa działa zgodnie z przeznaczeniem — zobacz Podstawowe pojęcia → Sesje i bezpieczeństwo. Odrzucenie jest obrazem serwowanym ze statusem 200, więc monitor sprawdzający tylko kody statusu liczy go jako stronę.

Obraz błędu z napisem:

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

Token wygasł (przesuwane okno, domyślnie 60 minut — DocOptions.TimeOut) lub sesja została zamknięta. Otwórz ponownie dokument, aby uzyskać nowy token.

Otwieranie dokumentu nie powiodło się

LicenseException z komunikatem odrzucenia — plik licencji został znaleziony, ale odrzucony (nieprawidłowy podpis, naruszony, na czarnej liście lub kompilacja poza oknem wersji/aktualizacji licencji). Ten stan blokuje otwieranie (szybkie niepowodzenie) zamiast degradacji do znaku wodnego; przeczytaj License.RejectionMessage, aby poznać przyczynę.

LicenseException:

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

Rozszerzenie jest obsługiwane wyłącznie przez wtyczkę (tutaj: DICOM). Wtyczka jest zarejestrowana, ale żadna licencja nie przyznaje już jej możliwości — zazwyczaj tymczasowa licencja, która wygasła po uruchomieniu aplikacji. Zainstaluj licencję, która to umożliwia i zweryfikuj IsCapabilityGranted(LicenseCapability.Dicom) na IDoconutLicenseService. Brak lub niewystarczające uprawnienie nie‑tymczasowe zazwyczaj kończy się niepowodzeniem podczas AddDoconut().

FormatNotSupportedException:

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

Żaden podgląd — wbudowany, wtyczka ani niestandardowy — nie obsługuje tego rozszerzenia. Sprawdź listę obsługiwanych formatów; dla własnych formatów DoconutOptions.RegisterViewer może dodać nowy.

InvalidDataException — zawartość pliku jest uszkodzona lub nie pasuje do jego rozszerzenia (np. plik został przemianowany). Zweryfikuj przesyłane pliki przed otwarciem.

InvalidOperationException:

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

Rozwiązałeś DocumentConverter bez rejestracji wtyczki Converter.

Niepowodzenia uruchamiania

InvalidOperationException wspominający wtyczkę zarejestrowaną przez AddPlugin — bieżąca licencja nie‑tymczasowa nie przyznaje tej możliwości wtyczki. Usuń rejestrację lub zainstaluj licencję, która to umożliwia. Brak licencji oraz starszy plik TRIAL nie przyznają żadnych możliwości wtyczki.

ArgumentException z AddDoconut():

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.

Błędy kompilacji / zależności

Błąd kompilatora CS1705, lub w czasie wykonywania przy otwieraniu dokumentu:

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

Twój projekt przypiął System.Text.Json lub System.Text.Encodings.Web poniżej zależności 8.0.x zadeklarowanych przez Doconut.NET6. Usuń obniżenie wersji i pozwól NuGet przywrócić graf pakietów (System.Text.Json 8.0.6 i System.Text.Encodings.Web 8.0.0 jak zadeklarowano w pakiecie).

Wyjście wygląda nieprawidłowo

Strony zawierają znak wodny — aplikacja jest w stanie ewaluacyjnym: nie znaleziono pliku licencji, wygasła tymczasowa licencja lub nieprawidłowa domena. Przy aktywnej tymczasowej licencji tylko wyjście wtyczki jest znakowane. Kompilacja wydana po dacie subskrypcji płatnej licencji nie jest znakowana: otwarcie zgłasza LicenseException. Sprawdź IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — odnośnik IDoconutLicenseService na stronie Licencjonowania pokazuje gotowy punkt końcowy.

Starsze dokumenty wyświetlają zniekształcony tekst — kodowanie stron kodowych nie jest ładowane domyślnie w .NET 6. Dodaj raz przy uruchamianiu:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Nieprawidłowe lub zastąpione czcionki — serwer nie posiada czcionek dokumentu. Zainstaluj je lub skieruj FontFolders (na WordConfig/PptConfig) do folderu, który je zawiera. W systemie Linux, zobacz poniżej.

Adnotacja obrazu wyświetla się w przeglądarce, ale eksport zawiera pole „Obraz zablokowany” — host obrazu ma prywatny lub adres loopback, który serwer odmawia pobrania. Zobacz Adnotacje.

Linux

Otwieranie dowolnego dokumentu kończy się błędem:

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.

Zainstaluj bibliotekę konfiguracyjną czcionek: apt-get install -y libfontconfig1 (fontconfig na RHEL/Fedora). Zobacz Instalacja.

Otwieranie dowolnego dokumentu kończy się błędem:

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.

Aplikacja odwołuje się do nowszej wersji SkiaSharp, bezpośrednio lub przez inną bibliotekę. Dodaj SkiaSharp.NativeAssets.Linux w tej samej wersji co ten SkiaSharp.

Otwieranie dowolnego dokumentu kończy się błędem:

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.

Host nie jest obsługiwaną platformą. Alpine i inne dystrybucje oparte na musl nie są wspierane: użyj obrazu opartego na Debianie lub Ubuntu.

Tekst jest szerszy lub węższy niż w systemie Windows, lub podziały wierszy różnią się — czcionki dokumentu nie są zainstalowane, więc Doconut używa najbliższej dostępnej czcionki. Zainstaluj czcionki kompatybilne metrycznie (fonts-liberation dla Arial, Times New Roman i Courier New; fonts-crosextra-carlito i fonts-crosextra-caladea dla Calibri i Cambria), lub skopiuj własne licencjonowane czcionki do /usr/share/fonts/ i uruchom fc-cache -f. Azjatycki tekst wyświetlany jako puste pola wymaga fonts-noto-cjk.

Funkcja działała w wersji ewaluacyjnej, cicha w produkcji

Klasyczna niespodzianka przy uruchomieniu: aktywna tymczasowa licencja zapewnia każdą możliwość; Twoja zakupiona licencja zapewnia tylko to, co kupiłeś. Pakiety wyszukiwania i adnotacji mogą zniknąć, gdy ich możliwości są nieobecne. Zarejestrowany Converter lub wtyczki DICOM z niewystarczającą licencją nie‑tymczasową zawodzą podczas AddDoconut(). Porównaj IsCapabilityGranted(...) ze wszystkimi funkcjami, które włączasz przed wdrożeniem.

Wyszukiwanie nie znajduje nic (lub zbyt mało)

  • Dla bezpośredniego PDF, AllowSearch nie był włączony w momencie otwarcia. Word, Excel i PowerPoint udostępniają ten sam przełącznik poprzez ich zagnieżdżone PdfConfig.
  • Treść jest zeskanowana/tylko obraz, więc zwykłe Search nie ma warstwy tekstowej do dopasowania. Użyj źródła zawierającego tekst lub projekcji PDF zachowującej tekst.
  • HTML i MS Project (MPP) nie są przeszukiwalne w ustawieniach domyślnych — ustaw DefaultRender = false, aby renderowały się poprzez projekcję PDF z natywną warstwą tekstową. Word, Excel, PowerPoint, TXT, Visio, e‑mail, EPUB i MHT są przeszukiwane w swoich domyślnych ustawieniach katalogu.
  • objViewer.CanSearch() jest false po inicjalizacji — rozpoznany format nie ma standardowej ścieżki wyszukiwania. Ten werdykt jest oddzielny od licencji Search; zweryfikuj oba.
  • Strona odczytuje wartość zwracaną przez objViewer.Search(...) — liczba przychodzi w jego trzecim argumencie, jako callback.

Wciąż utknąłeś?

Izoluj problem względem minimalnej aplikacji Quick Start; jeśli wystąpi tam ponownie, skontaktuj się z pomocą techniczną, podając dokument, swój Program.cs oraz wynik diagnostyki licencji.

Czy ta strona była pomocna?