Jak działa przeglądarka
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 zaobserwujesz, w tym komunikaty o błędach.
Trzy elementy składowe
Viewer— publiczna usługa, którą wstrzykujesz. Otwiera dokumenty i zwraca tokeny sesji.- Sesja dokumentu — obiekt po stronie serwera przechowujący załadowany dokument, indeksowany 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 po wygaśnięciu pamięci podręcznej lub po wywołaniu explicite CloseDocument(token).
Nie tworzysz go już ręcznie. AddDoconut() rejestruje go jako usługę przejściową; wstrzykuj go tam, gdzie jest potrzebny:
app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
var token = await viewer.OpenDocumentAsync($"files/{fileName}");
return Results.Content(token, "text/plain");
});W aplikacji MVC przyjmij go jako parametr konstruktora; w widoku Razor użyj @inject Doconut.Viewer Viewer. Pamięci podręczne zarządzane przez aplikację dla instancji Viewer nie są już potrzebne — i nie są już prawidłowe, ponieważ nie przechowują niczego wartego buforowania.
Co się dzieje wewnątrz OpenDocumentAsync
- Bramka licencyjna. Odrzucona lub przeterminowana licencja (na czarnej liście, zmodyfikowana lub wersja poza oknem aktualizacji licencji) natychmiast rzuca
LicenseException, z powodem odrzucenia jako komunikatem — otwieranie nigdy nie degraduje się cicho przy nieprawidłowej (w przeciwieństwie do nieobecnej) licencji. Licencja tymczasowa lub subskrypcyjna, której termin kalendarzowy wygasł, jest wyjątkiem: nie rzuca wyjątku — przechodzi do znaku wodnego. - Tworzenie sesji. Fabryka przeglądarki wybiera odpowiedni podgląd formatu dla rozszerzenia pliku i ładuje dokument (zobacz Rendering Pipeline). Sesja jest przechowywana w
IMemoryCachepod nowym tokenem GUID z przesuwanym wygaśnięciem —DocOptions.TimeOutminut, domyślnie 60. Każde żądanie strony resetuje licznik. - Rejestracja bezpieczeństwa. Z
UnsafeMode = false(domyślnie), token jest powiązany z sesją ASP.NET wywołującego: znaczniksecure-{token}jest zapisywany w sesji, tak że tylko sesja przeglądarki, która otworzyła dokument, może żądać jego stron. - Token jest zwracany. To jedyne poświadczenie dla wszystkiego, co następuje.
Nie ma osobnego kroku rozgrzewki. Poprzednia biblioteka udostępniała InitCache() w tym celu; nie istnieje już i nic go nie zastę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:
| Zapytanie | Cel |
|---|---|
?token=…&page=N | Obraz renderowanej strony (PNG) |
?token=…&page=N&thumb=1 | Miniatura |
?token=…&zoom=… | Renderowanie powiększonej strony |
?token=…&search=term | Wyszukiwanie pełnotekstowe (z bramką licencyjną) |
?token=…&bookmarks | Zarys dokumentu/zakładki |
?token=…© / &showlinks / &fileFormat | Kopiowanie tekstu, hiperłącza i informacje o formacie |
?token=…&meta | Metadane techniczne DICOM; zwraca 501 dla sesji DICOM w tym pakiecie |
?token=…&action=rotate/flip/close | Akcje strony i wyraźne zamknięcie |
?token=…&AnnSave=… / &AnnLoad | Zapis/odczyt adnotacji |
Każda z tych ścieżek najpierw przechodzi walidację:
- 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 zSession 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.
Gdzie zamontowany jest middleware
UseDoconut() odpowiada na żądania niosące token, gdziekolwiek go zamontujesz. Typowa konfiguracja zachowuje historyczny kształt żądania DocImage.axd na gałęzi MapWhen, tak aby istniejący klient nadal wywoływał URL, którego zawsze używał. Niezależnie od wyboru, BasePath klienta musi się z tym zgadzać — zobacz Konfiguracja przeglądarki.
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
viewer.CloseDocument(token);CloseDocument usuwa sesję z pamięci podręcznej (co zwalnia podległy silnik dokumentu i natychmiast zwalnia jego pamięć), usuwa znacznik secure-{token} i cofa 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 zakończył.
Jest wywoływany na wstrzykniętym Viewer. Poprzedni wzorzec — tworzenie krótkotrwałego Viewer w bloku using wyłącznie w celu zamknięcia tokenu — nie ma odpowiednika i nie jest potrzebny.
Najważniejsze wnioski
- Jeden otwarty dokument = jedna sesja = jeden token. Tokeny są przypisane do sesji przeglądarki, nie do globalnych URL.
- Token wygasa w przesuwanym oknie; przeglądarka pozostawiona bezczynna dłużej niż
DocOptions.TimeOutwymaga ponownego otwarcia. Viewermoże być wstrzyknięty i współdzielony dowolnie; sesje przenoszą cały stan.
Czy ta strona była pomocna?