Rozwiązywanie problemów – Doconut Dokumentacja

Wiele błędów System.Web nie generuje widocznych wyjątków: strona zwraca pusty 500, ikona zwraca 404 lub żądanie nigdy nie powraca. Ta strona jest uporządkowana według tego, co obserwujesz. Cytowane komunikaty to dosłowny tekst generowany przez Doconut.

Objawy w skrócie

Co widzisz	Najprawdopodobniej przyczyna	Rozwiązanie
Każde żądanie zwraca pusty `500`	Wyjątek w `Application_Start`: wtyczka bez licencji, nieprawidłowa opcja, niekompletna konfiguracja farmy — lub przekierowanie wiązania wskazujące wersję, której nie ma w `bin\`	Dziennik zdarzeń Windows, Aplikacja, źródło ASP.NET. Zobacz Błędy uruchamiania
Niektóre strony MVC zwracają pusty `500`	Razor kompiluje widoki w czasie działania: fasada `netstandard` brakująca w `<compilation>`, lub widok używa C# nowszego niż 5 (`?.`, `$"..."`, `nameof`)	Dodaj fasadę (Instalacja); przenieś logikę z widoku do kontrolera
Strony wyświetlają `â€”`, `â€¦` lub podobne zamiast myślników i akcentów	Pliki stron bez znacznika kolejności bajtów są odczytywane przy użyciu domyślnej strony kodowej ANSI serwera	`<globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />`
Konsola przeglądarki wyświetla `404` dla `HEAD /DocImage.axd?...&page=1`	Obsługa jest zarejestrowana bez czasownika `HEAD`	`verb="GET,HEAD,POST"` w obsłudze
Dokument jest renderowany, ale ikony paska narzędzi i wskaźnik ładowania są nieobecne	`ResPath` wskazuje na korzeń zasobów lub zaczyna się od `/`	`ResPath: 'doconut-res/images'`
Żądania `/doconut-res/...` zwracają `404`	Moduł zasobów nie jest zarejestrowany, `runAllManagedModulesForAllRequests` jest wyłączony, lub routing MVC przechwytuje ścieżkę	Wpis `<modules>` i `routes.IgnoreRoute("doconut-res/{*pathInfo}")`
Przeglądarka zgłasza `The viewer handler could not be reached (no response).`	`BasePath` zaczyna się od `/` (`'/myapp'` staje się `//myapp/…`, inny host)	`BasePath: '/'` w katalogu głównym witryny; `'myapp'` w katalogu wirtualnym
Przeglądarka zgłasza `Please make sure your middleware is configured.`	`DocImage.axd` odpowiedział `404`: obsługa nie znajduje się w `Web.config`, routing MVC przechwycił to, lub `BasePath` wskazuje gdzie indziej	Wpis `<handlers>`, `routes.IgnoreRoute("{resource}.axd/{*pathInfo}")` i `BasePath`
Każda strona wyświetla `You Are Not Authorized To View This Page.`	Dokument został otwarty w żądaniu bez stanu sesji, stan sesji jest wyłączony, lub ciasteczko sesji nie dociera do `DocImage.axd`	Zobacz Brak autoryzacji
Konwersja Web Forms nigdy nie zwraca	Strona blokuje się na `ConvertAsync` — zakleszczenie	`Async="true"` + `RegisterAsyncTask` (Wtyczka konwertera)
Każda strona zawiera znak wodny oceny	Nie znaleziono licencji — nie znajduje się w `<site root>\wwwroot`	Ustawienia licencji
Widżet ładuje się, ale jego pierwsza akcja zwraca `404`	Widżet nie jest włączony, lub jego `basePath` nie jest `'/DocImage.axd'`	`options.Add…Widget()` i `basePath: '/DocImage.axd'`
Pierwszy dokument po uruchomieniu lub recyklingu witryny zajmuje minutę lub dłużej; późniejsze są szybkie	Silniki dokumentów ładują się przy pierwszym otwarciu, a skanowanie antywirusowe w czasie rzeczywistym skanuje je podczas ładowania	Rozgrzej witrynę i utrzymuj pulę działającą — zobacz Pierwszy dokument po uruchomieniu
Duże przesyłanie wyświetla stronę błędu IIS	Przesyłanie przekracza `maxRequestLength` (KB) lub `maxAllowedContentLength` (bajtów)	Podnieś oba limity powyżej największego pliku lub limitu widżetu

Błędy uruchamiania

Wyjątek rzucony w Application_Start nie dociera do przeglądarki: każde żądanie zwraca pusty 500, a dziennik IIS nie pokazuje nic przydatnego. Wyjątek znajduje się w Windows event log (Podgląd zdarzeń → Dzienniki systemu Windows → Aplikacja, źródło ASP.NET). Typowe:

Wtyczka bez licencji:

text

The Converter plugin is registered via AddPlugin but no active license grants Converter.
Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

Doconut.Viewer.<Capability>.lic wtyczki musi znajdować się w wwwroot, obok Doconut.Viewer.lic. Brak licencji i starszy plik TRIAL nie zapewniają żadnych możliwości wtyczki.

Nieprawidłowe opcje:

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.

Zestaw, który nie może się załadować.

ASP.NET ładuje każdy zestaw w bin\ przy uruchamianiu aplikacji, więc przekierowanie wiązania w Web.config, które wskazuje wersję nieobecną w bin\, zatrzymuje całą witrynę. Skopiuj przekierowania wygenerowane przez NuGet (dla projektu w stylu SDK, z bin\<YourApp>.dll.config) zamiast edytować je ręcznie i skopiuj je ponownie po aktualizacjach pakietów.

Nie masz uprawnień do wyświetlenia tej strony.

Strona jest odrzucana, ponieważ żądana sesja ASP.NET nigdy nie otrzymała dokumentu. Sprawdź w kolejności:

Otwieranie działało ze stanem sesji. Kontrolery MVC i strony Web Forms go mają. Niestandardowy IHttpHandler otwierający dokumenty musi implementować System.Web.SessionState.IRequiresSessionState, w przeciwnym razie nie ma sesji do przyznania.
Stan sesji jest włączony. <sessionState mode="Off" /> odrzuca każdą stronę.
Plik cookie dociera do obsługi. Żądania tego samego pochodzenia z widgetu niosą ASP.NET_SessionId; skrypt, wywołanie serwer‑do‑serwera lub strona z innego pochodzenia bez ciasteczek tego nie robi.
Web farm: otwarcie powiązało przeglądarkę (DocOptions.BrowserId) i strona przekazuje bilet (objViewer.View(token, access)); każdy węzeł używa tego samego klucza podpisującego.

Odrzucenie to obraz serwowany ze statusem 200, o rozmiarze około 2 KB. Monitor sprawdzający tylko kody statusu liczy go jako stronę.

Nie znaleziono sesji dokumentu. Proszę ponownie otworzyć dokument.

Token wygasł (przesuwane okno, DocOptions.TimeOut, domyślnie 60 minut), dokument został zamknięty lub — na pojedynczym serwerze — pula aplikacji została zrecyklingowana. Recykling odbywa się zgodnie z harmonogramem, przy każdej edycji Web.config oraz po upływie czasu bezczynności puli (domyślnie 20 minut w IIS). Otwórz dokument ponownie, aby uzyskać nowy token.

Nie udało się otworzyć dokumentu

LicenseException z powodu odrzucenia — plik licencji został znaleziony, ale odrzucony (nieprawidłowy podpis, manipulacja, czarna lista lub kompilacja poza zakresem wersji licencji). Otwieranie jest blokowane zamiast znakowane znakiem wodnym.

LicenseException:

text

This document type requires the 'Dicom' plugin license.

Rozszerzenie jest obsługiwane wyłącznie przez wtyczkę (tutaj DICOM), której możliwości nie zostały przyznane.

FormatNotSupportedException — żaden podgląd (wbudowany, wtyczka lub niestandardowy) nie obsługuje tego rozszerzenia. DoconutOptions.RegisterViewer może dodać taki podgląd dla własnych formatów.

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

InvalidOperationException:

text

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

DocumentConverter został rozwiązany bez rejestracji wtyczki Converter.

Wynik wygląda niepoprawnie

Strony mają znak wodny — nie znaleziono licencji, wygasła lub nie obejmuje tej wersji. W IIS licencja musi znajdować się w wwwroot pod katalogiem głównym witryny (AppContext.BaseDirectory\wwwroot), a nie w bin\. Sprawdź IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, License.RejectionMessage).

Starsze dokumenty wyświetlają zniekształcony tekst — zarejestruj kodowanie stron kodowych raz, przy uruchamianiu:

csharp

// Global.asax.cs, Application_Start - przed DoconutHost.Initialize.
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Nieprawidłowe lub zastąpione czcionki — serwer nie posiada czcionek dokumentu. Windows Server bez Office ma znacznie mniej czcionek niż maszyna deweloperska. Zainstaluj czcionki lub skieruj FontFolders (na WordConfig i PptConfig) do folderu, w którym się znajdują.

Adnotacja obrazu wyświetla się w podglądzie, ale eksport zawiera komunikat „Obraz zablokowany” — host obrazu ma prywatny lub adres zwrotny, którego serwer odmawia pobrania. Zobacz Adnotacje.

Funkcja działała w wersji ewaluacyjnej, jest wyciszona w produkcji

Aktywna tymczasowa licencja przyznaje wszystkie możliwości; zakupiona licencja przyznaje tylko to, co zostało zakupione. Brak określonej możliwości powoduje, że pliki wyszukiwania lub adnotacji nie są generowane, a zarejestrowana wtyczka zatrzymuje witrynę przy uruchamianiu. Porównaj IsCapabilityGranted(...) ze wszystkimi funkcjami, których używasz przed wdrożeniem.

Wyszukiwanie nie znajduje nic (lub znajduje zbyt mało)

Dla PDF, AllowSearch nie został włączony podczas otwierania dokumentu — domyślnie jest ustawiony na false. Word, Excel i PowerPoint udostępniają ten sam przełącznik.
Zawartość jest zeskanowana lub tylko obrazowa, więc nie ma warstwy tekstowej do dopasowania.
HTML i Microsoft Project (MPP) nie są przeszukiwalne w ustawieniach domyślnych: ustaw DefaultRender = false, aby renderowały się przez projekcję PDF z tekstem.
objViewer.CanSearch() jest false po inicjalizacji: rozpoznany format nie ma ścieżki wyszukiwania. To jest oddzielne od licencji Search; sprawdź oba.
Strona odczytuje wartość zwracaną przez objViewer.Search(...) — liczba przychodzi w trzecim argumencie, jako wywołanie zwrotne.

Wciąż utknąłeś?

Odtwórz problem przy użyciu minimalnej konfiguracji z Szybki start. Jeśli wystąpi tam ponownie, skontaktuj się z pomocą techniczną, podając dokument, swój Global.asax.cs, części Doconut z Web.config oraz wpis w dzienniku zdarzeń Windows, jeśli taki istnieje.