Jak działa Viewer

Cykl życia żądania dokumentu

Doconut renderuje dokumenty jako obrazy podzielone na strony, serwowane przez middleware ASP.NET Core. Zrozumienie cyklu życia — otwarcie, token, żądania stron, zamknięcie — wyjaśnia prawie każde zachowanie, które możesz zaobserwować, w tym komunikaty o błędach.

Trzy współdziałające elementy

  • Viewer — publiczna usługa, którą wstrzykujesz. Otwiera dokumenty i zwraca tokeny sesji.
  • Sesja dokumentu — obiekt po stronie serwera przechowujący załadowany dokument, identyfikowany tokenem w IMemoryCache.
  • Middleware Doconut — dodany przez UseDoconut(); odpowiada na każde żądanie, które wysyła widget przeglądarki (pages, thumbnails, search, annotations, …), zawsze uwierzytelnione tokenem.

Viewer jest bezstanowy — z założenia

Viewer jest zamknięty, nie przechowuje stanu dokumentu per żądanie i celowo nie implementuje IDisposable. Sesje istnieją niezależnie w menedżerze sesji i są czyszczone przez wygaśnięcie pamięci podręcznej lub explicite CloseDocument(token).

Wstrzyknij go tam, gdzie jest potrzebny:

csharp
app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync($"files/{fileName}");
    return Results.Content(token, "text/plain");
});

Co się dzieje wewnątrz OpenDocumentAsync

  1. Bramka licencyjna. Odrzucona lub wygasła wersja licencji (czarna lista, zmodyfikowana, lub kompilacja poza oknem aktualizacji licencji) natychmiast rzuca LicenseException, z powodem odrzucenia jako komunikatem — otwarcie nigdy nie degraduje się cicho przy nieprawidłowej (w przeciwieństwie do nieobecnej) licencji. Licencja tymczasowa lub subskrypcyjna wygasła kalendarzowo jest wyjątkiem: nie rzuca wyjątku — degraduje do znaku wodnego.
  2. Tworzenie sesji. Fabryka podglądu wybiera odpowiedni podgląd formatu dla rozszerzenia pliku i ładuje dokument (zobacz Rendering Pipeline). Sesja jest przechowywana w IMemoryCache pod nowym tokenem GUID z przesuwanym wygaśnięciem — DocOptions.TimeOut minut, domyślnie 60. Każde żądanie strony resetuje licznik.
  3. Rejestracja bezpieczeństwa. Z UnsafeMode = false (domyślnie), token jest powiązany z sesją ASP.NET wywołującego: marker secure-{token} jest zapisywany w sesji, więc tylko sesja przeglądarki, która otworzyła dokument, może żądać jego stron.
  4. Token jest zwracany. To jedyne poświadczenie dla wszystkiego, co następuje.

Trzy przeciążenia różnią się jedynie wejściem: ścieżka do pliku, ścieżka do pliku plus konfiguracja per format (PdfConfig, WordConfig, …), lub Stream plus FileInfo, którego rozszerzenie określa wykrywanie formatu.

Jak widget pobiera strony

Widget kliencki wywołuje middleware Doconut z tokenem w ciągu zapytania. To, co robi middleware, zależy od żądania:

ZapytanieCel
?token=…&page=NWygenerowany obraz strony (PNG)
?token=…&page=N&thumb=1Miniatura
?token=…&zoom=…Renderowanie powiększonej strony
?token=…&search=termWyszukiwanie pełnotekstowe (z ograniczeniem licencyjnym)
?token=…&bookmarksStruktura dokumentu/zakładki
?token=…&copy / &showlinks / &fileFormatKopiowanie tekstu, hiperłącza i informacje o formacie
?token=…&metaMetadane techniczne DICOM; zwraca 501 dla sesji DICOM na .NET 6
?token=…&action=rotate/flip/closeAkcje strony i wyraźne zamknięcie
?token=…&AnnSave=… / &AnnLoadZapis/odczyt adnotacji

Każda z tych ścieżek jest najpierw walidowana:

  • Brak tokenu → middleware zwraca 404 (lub baner wersji, gdy ShowDoconutInfo = true).
  • Nieznany lub wygasły token → obraz błędu z Document session not found. Please re-open document.
  • Brak middleware sesji (z UnsafeMode = false) → HTTP 500 z Session middleware not configured. Call UseSession() before UseDoconut().
  • Token otwarty przez inną sesję przeglądarki → obraz błędu z You Are Not Authorized To View This Page.

Serwowanie stron ze współdzielonego magazynu zamiast z węzła otwierającego to zupełnie inny układ; zobacz Rozproszone wdrożenia.

Zamykanie dokumentu

csharp
viewer.CloseDocument(token);

CloseDocument usuwa sesję z pamięci podręcznej (co zwalnia podległy silnik dokumentu i natychmiast zwalnia jego pamięć), usuwa marker secure-{token} i odwołuje przyznany dostęp. Wywołanie jest opcjonalne — przesuwane wygaśnięcie wykonuje tę samą automatyczną czyszczenie — ale dla dużych dokumentów jest to uprzejmy sposób zwolnienia pamięci w momencie, gdy użytkownik skończy.

Najważniejsze wnioski

  • Jeden otwarty dokument = jedna sesja = jeden token. Tokeny są przypisane do sesji przeglądarki, nie do globalnych URL-i.
  • Token wygasa w oknie przesuwanym; podgląd pozostawiony bezczynny po DocOptions.TimeOut wymaga ponownego otwarcia.
  • Viewer może być wstrzykiwany i swobodnie współdzielony; sesje przenoszą cały stan.

Czy ta strona była pomocna?