Zarejestruj i włącz widget konwertera Doconut Drop‑in w .NET 8

Widget drop‑in to gotowy interfejs użytkownika Doconut do przesyłania pliku, uruchamiania konwersji i pobierania wyniku.
Domyślnie trzy endpointy widgetu ?convert= zwracają 404; stają się aktywne dopiero po zarejestrowaniu wtyczki Converter i wywołaniu AddConverterWidget() na DoconutOptions.

Poniżej znajduje się kompletny, gotowy do skopiowania kod konfiguracji startowej, spełniający oba wymagania.

---

1. Wymagania wstępne – licencja i obsługa sesji

• Licencja – Wtyczka Converter wymaga licencji, która przyznaje możliwość Converter. Umieść plik (np. Doconut.Viewer.lic) w miejscu dostępnym dla aplikacji i wskaż DoconutOptions.LicensePath na niego.
• Stan sesji – Model bezpieczeństwa Doconut przechowuje tokeny sesji dokumentu w sesji ASP.NET Core. Dodaj rozproszoną pamięć podręczną i AddSession() przed podłączeniem middleware.

builder.Services.AddDistributedMemoryCache();   // wymagane dla sesji
builder.Services.AddSession();                  // włącza sesję opartą na IDistributedCache

---

2. Zarejestruj podstawowe usługi Doconut

AddDoconut() jest jedynym punktem wejścia, który wstrzykuje przeglądarkę, usługę licencji i rejestr wtyczek.

builder.Services.AddDoconut(options =>
{
    // Powiedz Doconut, gdzie znaleźć plik licencji.
    options.LicensePath = "Doconut.Viewer.lic";

    // Zarejestruj wtyczkę Converter – to także weryfikuje uprawnienia licencyjne.
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Jeśli licencja nie zawiera możliwości Converter, powyższe wywołanie rzuca InvalidOperationException i aplikacja nie uruchomi się. To zachowanie fail‑fast zapobiega wdrożeniu nieprawidłowo licencjonowanej wersji.

---

3. Włącz widget przy użyciu AddConverterWidget

Widget wymaga włączenia. Wywołanie AddConverterWidget() rejestruje trzy endpointy konwersji (?convert=open, ?convert=run, ?convert=download) i podłącza niewielką konfigurację po stronie klienta (maksymalny rozmiar przesyłanego pliku, ścieżki bazowe itp.).

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();

    // Włącz interfejs drop‑in i ustaw limit przesyłania po stronie klienta.
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // wstępna kontrola po stronie klienta; serwer wymusza własny limit
    });
});

Tylko wywołanie AddConverterWidget tworzy endpointy; statyczny plik JavaScript (doconutConverter.js) jest zawsze serwowany jako zasób wbudowany, ale nie uda się połączyć z serwerem, jeśli endpointy są nieobecne.

---

4. Podłącz middleware w właściwej kolejności

Middleware obsługujący zasoby statyczne (UseDoconutResources) musi działać przed końcowym middleware przeglądarki (UseDoconut). Middleware sesji również musi być umieszczony wcześniej, ponieważ Doconut weryfikuje sesję przy każdym żądaniu.

app.UseSession();           // musi poprzedzać UseDoconut()
app.UseDoconutResources();  // serwuje JS, CSS, obrazy
app.UseDoconut();           // obsługuje ?convert= oraz żądania stron dokumentu

Przy tak skonfigurowanym potoku, żądanie do /doconut-res/doconutConverter.js kończy się sukcesem, a widget może wywołać /doconut?convert=open, /doconut?convert=run i /doconut?convert=download.

---

5. Co tak naprawdę robi widget

Faza	Endpoint serwera	Typowa odpowiedź
Otwórz	?convert=open	Zwraca ładunek JSON zawierający token, liczbę stron, rozszerzenie źródła oraz listę dozwolonych formatów docelowych.
Uruchom	?convert=run	Rozpoczyna konwersję i zwraca downloadToken, liczbę stron wyniku, sugerowaną nazwę pliku oraz flagę wskazującą, czy wyjście jest oznaczone znakiem wodnym.
Pobierz	?convert=download	Strumieniuje przekonwertowany plik, gdy klient podąża za podanym adresem URL pobrania.

Po stronie klienta widget wykonuje wstępną kontrolę rozmiaru względem widget.MaxUploadMb. Jeśli plik przekracza ten limit, widget przerywa przesyłanie i wywołuje callback onError z phase = "open" oraz przyjaznym komunikatem. Serwer egzekwuje własny limit i zwróci 413 Payload Too Large, jeśli żądanie obejdzie kontrolę po stronie klienta.

---

6. Podpinanie zdarzeń widgetu (strona C# nie jest wymagana)

Wszystkie callbacki (onReady, onSourceLoaded, onConverted, onError, itp.) są funkcjami JavaScript dostarczanymi przez stronę, na której znajduje się widget. Ponieważ pytanie koncentruje się na stronie rejestracji, nie musisz pisać dodatkowego kodu C# obsługującego te callbacki — widget wywołuje je automatycznie, gdy endpointy są aktywne.

---

7. Typowe pułapki i jak ich unikać

Objaw	Prawdopodobna przyczyna	Rozwiązanie
404 na /doconut?convert=open	Pominięto AddConverterWidget().	Dodaj wywołanie jak pokazano w sekcji 3.
Aplikacja nie uruchamia się z InvalidOperationException o brakującej możliwości	Plik licencji nie przyznaje Converter.	Uzyskaj licencję, która zawiera możliwość Converter.
Błąd 500 związany z sesją	UseSession() umieszczono po UseDoconut() lub brak rejestracji pamięci podręcznej.	Upewnij się, że app.UseSession() działa przed app.UseDoconut() i że usługa pamięci podręcznej jest zarejestrowana.

---

8. Uruchom aplikację i zobacz widget w działaniu

1. Zbuduj i uruchom projekt ASP.NET Core.
2. Otwórz stronę zawierającą element <div id="doconut-convert"></div> i zawierającą skrypt konwertera Doconut (skrypt jest serwowany automatycznie z /doconut-res/doconutConverter.js).
3. Przeciągnij obsługiwany plik (PDF, DOCX, DWG, itp.) na obszar upuszczania.
4. Widget wywoła ?convert=open, potem ?convert=run i w końcu wyświetli link Download, który prowadzi do ?convert=download.

Jeśli trzy endpointy odpowiadają JSON-em zamiast 404, widget jest poprawnie zarejestrowany i gotowy do użycia w produkcji.

---

Kolejny krok: Dodaj powyższe fragmenty kodu do swojego Program.cs (lub Startup.cs), zweryfikuj, że plik licencji jest obecny, i uruchom aplikację. Widget konwertera drop‑in będzie dostępny bez dalszych zmian po stronie serwera.