Implementacja zarządzania dokumentami z Doconut

Przebieg zarządzania dokumentami w portalu .NET zazwyczaj wymaga trzech rzeczy:

1. Sposobu ładowania plików PDF, Office, rysunków CAD lub obrazów bez pisania przeglądarki od podstaw.
2. Bezpiecznego tokenu, który powiąże załadowany dokument z bieżącą sesją przeglądarki.
3. Kroku czyszczenia, który zwalnia pamięć, gdy tylko użytkownik skończy.

Doconut zapewnia wszystkie trzy poprzez pojedynczą usługę Viewer, lekką sesję IMemoryCache oraz wywołania CloseDocument.

---

1. Zarejestruj przeglądarkę w kontenerze DI

Podczas uruchamiania aplikacji dodaj usługi Doconut do kontenera DI, wywołując metodę rejestracji Doconut opisaną w oficjalnej dokumentacji. Ten krok rejestruje przeglądarkę, obsługę licencji oraz pamięć podręczną w pamięci, która będzie przechowywać sesje dokumentów.

Rejestracja weryfikuje licencję przy starcie, więc brakująca lub nieprawidłowa licencja powoduje szybki błąd i znasz problem zanim pierwsze żądanie dotrze do serwera.

---

2. Wstaw middleware obsługujący obrazy stron, miniatury i dane adnotacji

Skonfiguruj middleware Doconut w potoku żądań, aby każde żądanie zawierające ciąg zapytania ?token= było obsługiwane przez Doconut. Middleware wymusza domyślny znacznik bezpieczeństwa (secure-{token}), gdy UnsafeMode jest false (wartość domyślna) i serwuje obrazy stron, miniatury oraz dane adnotacji.

Umieszczenie middleware na dedykowanej gałęzi pozostawia resztę potoku nietkniętą i umożliwia skalowanie poziome bez sesji przyklejonych.

---

3. Otwórz dokument i uzyskaj nieprzezroczysty token sesji

Utwórz pojedynczy punkt końcowy, który przyjmuje ścieżkę do pliku (lub strumień) i zwraca token. Token jest jedynym poświadczeniem, które widzi widget klienta.

app.MapPost("/api/open", async (Viewer viewer) =>
{
    // Token jest nieprzezroczysty — przekaż go do widgetu, nigdy nie loguj ani nie przechowuj go.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Contract.pdf");
    return Results.Ok(new { token });
});

Co się dzieje wewnątrz OpenDocumentAsync

1. Brama licencyjna – nieprawidłowa licencja natychmiast rzuca LicenseException.
2. Tworzenie sesji – Doconut wybiera odpowiednią przeglądarkę formatu (PDF, Word, DWG, …) i przechowuje silnik w IMemoryCache pod tokenem GUID.
3. Rejestracja bezpieczeństwa – przy użyciu UnsafeMode = false token jest powiązany z sesją ASP.NET wywołującego za pomocą znacznika secure-{token}. Tylko ta sesja przeglądarki może żądać stron.
4. Zwrócenie tokenu – klient otrzymuje token i używa go przy każdym kolejnym żądaniu (/DocImage.axd?token=…).

Domyślne wygasanie przesuwne wynosi 60 minut (konfigurowalne przez DocOptions.TimeOut). Każde żądanie strony resetuje licznik, więc nieaktywne sesje znikają automatycznie.

---

4. Renderuj dokument po stronie klienta

Z przeglądarki wywołujesz punkt końcowy, pobierasz token i przekazujesz go widgetowi Doconut:

fetch('/api/open', { method: 'POST' })
    .then(r => r.json())
    .then(d => {
        const token = d.token;
        objViewer.View(token);   // Widget JavaScript dostarczony przez Doconut
    });

Widget wewnętrznie wysyła żądania stron, miniatur, wyszukiwania i adnotacji, które wszystkie zawierają ten sam token. Ponieważ token jest powiązany z sesją po stronie serwera, złośliwy użytkownik nie może przejąć dokumentu innego użytkownika.

---

5. Zamknij dokument, gdy tylko użytkownik opuści przeglądarkę

W przypadku dużych plików PDF lub CAD należy natychmiast zwolnić silnik renderujący. Wywołaj CloseDocument z punktu końcowego po stronie serwera lub z zdarzenia „unload” widgetu.

// Punkt końcowy po stronie serwera
app.MapPost("/api/close", (Viewer viewer, string token) =>
{
    viewer.CloseDocument(token);
    return Results.Ok();
});

// Bezpośrednie wywołanie z widgetu (jeśli udostępnisz token backendowi)
viewer.CloseDocument(token);

CloseDocument usuwa sesję z pamięci podręcznej, zwalnia podlegający silnik dokumentu, usuwa znacznik secure-{token} i cofa przyznany dostęp. Wygasanie przesuwne ostatecznie zrobiłoby to samo, ale wyraźne zamknięcie gwarantuje, że pamięć zostaje odzyskana w momencie, gdy użytkownik skończy.

---

6. Opcjonalnie: Konwertuj dokument na serwerze

Jeśli Twój przepływ pracy wymaga eksportu PDF z przesłanego pliku Word, włącz wtyczkę Converter w konfiguracji Doconut (zobacz dokumentację). Po zarejestrowaniu wtyczki możesz wstrzyknąć DocumentConverter i wywołać jej metodę ConvertAsync. Konwersja odbywa się na serwerze, więc nigdy nie potrzebujesz Office zainstalowanego na serwerze www.

---

7. Rozważania dotyczące skalowania zarządzania dokumentami klasy enterprise

• Stateless front‑ends – Widget przeglądarki nigdy nie przechowuje danych dokumentu; całe ciężkie przetwarzanie pozostaje po stronie serwera.
• Distributed cache – Zastąp domyślną pamięć w‑memory rozproszonym dostawcą (Redis, NCache), jeśli uruchamiasz wiele węzłów farmy webowej. Mapowanie token‑sesja działa niezmienione, ponieważ middleware odczytuje z skonfigurowanego IMemoryCache.
• Background jobs – Możesz wstępnie otwierać dokumenty w tle, buforować token i przekazać go UI później. Pamiętaj, że każdy token jest jednorazowy na sesję; ponowne użycie wymaga nowego wywołania OpenDocumentAsync.

Te wzorce pozwalają zbudować platformę zarządzania dokumentami, która skaluje się od jednoserverowego portalu intranetowego po wieloregionalną usługę chmurową, bez przepisywania logiki przeglądarki.

---

8. Szybka lista kontrolna dla gotowej do produkcji implementacji

Krok	Działanie
1	Zarejestruj usługi Doconut w Program.cs (zweryfikuj licencję).
2	Dodaj middleware Doconut na dedykowanej gałęzi.
3	Udostępnij punkt końcowy /api/open, który wywołuje OpenDocumentAsync.
4	Przekaż zwrócony token do objViewer.View(token) po stronie klienta.
5	Wywołaj CloseDocument(token), gdy przeglądarka jest ukryta lub strona się rozładowuje.
6	(Opcjonalnie) Włącz ConverterPlugin, jeśli potrzebujesz konwersji po stronie serwera.
7	(Opcjonalnie) Zamień IMemoryCache na rozproszoną pamięć podręczną dla skalowania poziomego.

Postępuj zgodnie z listą, a uzyskasz kompletny, bezpieczny, wysokowydajny przepływ zarządzania dokumentami zbudowany na natywnej przeglądarce .NET od Doconut.