Rozwiązywanie problemów

Diagnozowanie typowych błędów

Poniżej znajdują się dosłowne komunikaty Doconut, uporządkowane według objawów. Znajdź swój błąd i zastosuj poprawkę.

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, żądaniem 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(), w przeciwnym razie aplikacja zatrzyma się przy uruchamianiu z Unable to resolve service for type 'IDistributedCache' (aplikacje MVC i Razor Pages rejestrują ją już domyślnie).

Obrazek 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 zamierzeniami — zobacz Podstawowe koncepcje → Sesje i bezpieczeństwo. Odrzucenie jest obrazkiem zwróconym ze statusem 200, więc monitor sprawdzający tylko kody statusu liczy go jako stronę.

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

Serwer działa prawidłowo, ale strona zachowuje się niepoprawnie — bez żadnych błędów

To są tryby awaryjne, które należy rozważyć jako pierwsze po przeniesieniu aplikacji. Wszystkie trzy pozostawiają serwer w pełni sprawnym, prawidłowo renderują dokument i nie zgłaszają nic w konsoli przeglądarki.

Wskaźnik ładowania, który nigdy się nie zatrzymuje.
Twoje wywołania zwrotne podglądu są zadeklarowane jako globalne funkcje nazwane po identyfikatorze kontenera — ctlDoc_OnViewerReady() i podobne. Poprzedni podgląd wyszukiwał te nazwy; ten nie. Obsługa, która miałaby ukryć wskaźnik, po prostu nigdy się nie uruchamia. Przekaż funkcje jako opcje zamiast tego:

javascript
function ctlDoc_OnViewerBusy() { /* pokaż swój wskaźnik zajętości */ }
function ctlDoc_OnViewerReady() { /* ukryj go */ }
function ctlDoc_Copy(text) { /* użyj skopiowanego tekstu */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* raportuj postęp */ }

const objViewer = $('#div_ctlDoc').docViewer({
    // ... twoje istniejące opcje ...
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

Dokument za wskaźnikiem jest w porządku. Pełna lista opcji znajduje się w ViewerConfig.

Brak ikon podglądu lub obramowania, pozostałe strony poprawne.
ResPath jest pusty lub wskazuje na korzeń aplikacji — poprawne w poprzedniej bibliotece, niepoprawne tutaj. Musi podawać prefiks, który UseDoconutResources() montuje:

javascript
ResPath: 'doconut-res/images'   // lub '<your ResourcesPath>/images'

Uszkodzone kafelki na późniejszych stronach przy serwowaniu z współdzielonego magazynu.
Strony, które są jeszcze zapisywane, odpowiadają 202 Accepted. Klient bez retryOn409: true traktuje to jako nieudaną grafikę. Zobacz Distributed Deployments.

Otwieranie dokumentu nie powiodło się

LicenseException z komunikatem odrzucenia — plik licencji został znaleziony, ale odrzucony (nieprawidłowy podpis, zmodyfikowany, na czarnej liście lub wersja poza oknem wersji/aktualizacji licencji). Ten stan blokuje otwieranie (szybkie niepowodzenie) zamiast degradacji do znaku wodnego; przeczytaj License.RejectionMessage po wyjaśnienie.

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 powoduje błąd wcześniej, podczas AddDoconut().

FormatNotSupportedException:

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

Brak podglądu — wbudowanego, wtyczki ani niestandardowego — który obsługuje to rozszerzenie. Sprawdź listę obsługiwanych formatów; dla własnych formatów DoconutOptions.RegisterViewer może dodać jeden.

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.

Uruchamianie nie powiodło się

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

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.

Walidacja opcji szybkie‑niepowodzenie — napraw nieprawidłową ścieżkę.

Błędy budowania / zależności

Pakiet nie zostanie zainstalowany wcale — Doconut.NETStandard celuje w netstandard2.1, więc NuGet odrzuca projekt .NET Framework. To nie jest naprawialny błąd przywracania: .NET Framework nie może konsumować netstandard2.1. Użyj pakietu Doconut.NETFramework zamiast tego.

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

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

Twój projekt przypiął System.Text.Json lub System.Text.Encodings.Web poniżej wersji 9.0.x zależności zadeklarowanych przez Doconut.NETStandard. Usuń downgrade i pozwól NuGet przywrócić graf pakietów (System.Text.Json 9.0.0 i System.Text.Encodings.Web 9.0.0 zgodnie z deklaracją pakietu).

Ściana błędów kompilacji zaraz po podniesieniu wersji pakietu — to jest oczekiwane.
26.8.0 ma inną powierzchnię API niż 26.7.0, nie jest kompatybilną aktualizacją. Większość błędów to linie using, które przeniesiono do głównej przestrzeni nazw Doconut; przejdź przez Migracja do .NET Standard 2.1 zamiast naprawiać je pojedynczo.

TypeInitializationException w pierwszym pliku prezentacji:

text
Could not load ... System.Drawing.Common, Version=6.0.0.0

Silnik prezentacji wymaga twardo System.Drawing.Common 6.0.0 (zadeklarowane przez pakiet). Nie usuwaj ani nie nadpisuj tej zależności — każde otwarcie PPT/PPTX/PPS/POT/ODP zakończy się niepowodzeniem bez niej.

Wyjście wygląda niepoprawnie

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

Starsze dokumenty wyświetlają zniekształcony tekst — kodowania stron kodowych nie są ładowane domyślnie. Dodaj raz przy uruchomieniu:

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, w którym się znajdują.

Adnotacja obrazu wyświetla się w podglądzie, ale eksport ma pole „Image blocked” — host obrazu ma prywatny lub lokalny adres, który serwer odrzuca pobranie. Zobacz Adnotacje.

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

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

Wyszukiwanie nie znajduje nic (lub za 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.
  • Zawartość jest skanowana/tylko obraz, więc zwykłe Wyszukiwanie nie ma warstwy tekstowej do dopasowania. Użyj źródła zawierającego tekst lub projekcji PDF, która zachowuje 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 wyszukują w swoich domyślnych katalogach.
  • 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 trzecim argumencie, jako callback.

Nadal utknąłeś?

Izoluj problem przy minimalnej aplikacji Quick Start; jeśli tam się odtworzy, skontaktuj się z pomocą techniczną, podając dokument, Twój Program.cs oraz wynik diagnostyki licencji.

Czy ta strona była pomocna?