Zaregistrujte a povolte widget Doconut drop‑in converter v .NET 8

Widget drop‑in je připravené uživatelské rozhraní Doconut pro nahrání souboru, spuštění konverze a stažení výsledku.
Z krabice vrací tři koncové body widgetu ?convert= stav 404; aktivují se až po zaregistrování pluginu Converter a zavolání AddConverterWidget() na DoconutOptions.

Níže je kompletní konfigurace startu připravená ke kopírování, která splňuje oba požadavky.

---

1. Požadavky – licence a podpora relace

• Licence – Plugin Converter vyžaduje licenci, která poskytuje schopnost Converter. Umístěte soubor (např. Doconut.Viewer.lic) na místo přístupné aplikaci a nasměrujte DoconutOptions.LicensePath na něj.
• Stav relace – Bezpečnostní model Doconut ukládá tokeny dokument‑relace do ASP.NET Core session. Přidejte distribuovanou mezipaměť a AddSession() před zapojením middleware.

builder.Services.AddDistributedMemoryCache();   // vyžadováno pro relaci
builder.Services.AddSession();                  // povoluje IDistributedCache‑backed relaci

---

2. Zaregistrujte základní služby Doconut

AddDoconut() je jediný vstupní bod, který injektuje prohlížeč, licenční službu a registr pluginů.

builder.Services.AddDoconut(options =>
{
    // Řekněte Doconut, kde najít soubor licence.
    options.LicensePath = "Doconut.Viewer.lic";

    // Zaregistrujte plugin Converter – tím také ověříte licenční schopnost.
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Pokud licence neobsahuje schopnost Converter, výše uvedené volání vyhodí InvalidOperationException a aplikace se nespustí. Toto chování fail‑fast vás ochrání před nasazením nelegálního sestavení.

---

3. Aktivujte widget pomocí AddConverterWidget

Widget je volitelný. Zavolání AddConverterWidget() zaregistruje tři koncové body konverze (?convert=open, ?convert=run, ?convert=download) a připojí malou část konfigurace na straně klienta (maximální velikost nahrávání, základní cesty atd.).

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

    // Povolte UI drop‑in a nastavte limit nahrávání na straně klienta.
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // předběžná kontrola klienta; server vynutí svůj vlastní limit
    });
});

Pouze volání AddConverterWidget vytvoří koncové body; statický soubor JavaScript (doconutConverter.js) je vždy poskytován jako vložený zdroj, ale pokud koncové body chybí, selže při kontaktu se serverem.

---

4. Zapojte middleware ve správném pořadí

Middleware, který slouží statické soubory (UseDoconutResources), musí běžet před terminálním middleware pro prohlížeč (UseDoconut). Middleware pro relaci také musí být umístěn dříve, protože Doconut ověřuje relaci u každého požadavku.

app.UseSession();           // musí předcházet UseDoconut()
app.UseDoconutResources();  // slouží JS, CSS, obrázkům
app.UseDoconut();           // zpracovává ?convert= a požadavky na stránky dokumentu

S tímto pipeline v provozu úspěšně proběhne požadavek na /doconut-res/doconutConverter.js a widget může volat /doconut?convert=open, /doconut?convert=run a /doconut?convert=download.

---

5. Co widget ve skutečnosti dělá

Fáze	Serverový koncový bod	Typická odpověď
Otevření	?convert=open	Vrací JSON payload obsahující token, počet stránek, příponu zdroje a seznam povolených cílových formátů.
Spuštění	?convert=run	Spustí konverzi a vrátí downloadToken, počet výsledných stránek, navrhovaný název souboru a příznak, který udává, zda je výstup vodoznakem.
Stažení	?convert=download	Streamuje převedený soubor, když klient následuje poskytnutou URL pro stažení.

Na straně klienta widget provádí kontrolu velikosti před nahráním vůči widget.MaxUploadMb. Pokud soubor tento limit překročí, widget nahrávání přeruší a spustí callback onError s phase = "open" a přátelskou zprávou. Server vynutí svůj vlastní limit a odpoví 413 Payload Too Large, pokud požadavek projde kontrolou klienta.

---

6. Připojení k událostem widgetu (C#‑strana není potřeba)

Všechny callbacky (onReady, onSourceLoaded, onConverted, onError, atd.) jsou JavaScriptové funkce poskytnuté stránkou, která widget hostuje. Protože se otázka zaměřuje na registraci, nemusíte psát žádný další C# kód pro zpracování těchto callbacků – widget je automaticky vyvolá, jakmile jsou koncové body aktivní.

---

7. Časté úskalí a jak se jim vyhnout

Projev	Pravděpodobná příčina	Řešení
404 on /doconut?convert=open	AddConverterWidget() byl vynechán.	Přidejte volání, jak je ukázáno v sekci 3.
Aplikace se nespustí s InvalidOperationException o chybějící schopnosti	Licenční soubor neuděluje Converter.	Získejte licenci, která zahrnuje schopnost Converter.
Chyba související se session 500	UseSession() umístěn po UseDoconut() nebo chybí registrace cache.	Zajistěte, aby app.UseSession() běželo před app.UseDoconut() a aby byla registrována cache služba.

---

8. Spusťte aplikaci a podívejte se na widget v akci

1. Sestavte a spusťte projekt ASP.NET Core.
2. Otevřete stránku, která obsahuje element <div id="doconut-convert"></div> a zahrnuje skript Doconut converter (skript je automaticky poskytován z /doconut-res/doconutConverter.js).
3. Přetáhněte podporovaný soubor (PDF, DOCX, DWG atd.) do oblasti pro přetažení.
4. Widget zavolá ?convert=open, poté ?convert=run a nakonec zobrazí odkaz Stáhnout, který směřuje na ?convert=download.

Pokud tři koncové body odpoví JSON místo 404, widget je správně zaregistrován a připraven k produkčnímu použití.

Další krok: Přidejte výše uvedené úryvky kódu do vašeho Program.cs (nebo Startup.cs), ověřte, že licenční soubor je přítomen, a spusťte aplikaci. Widget Drop‑in converter bude aktivní bez dalších změn na straně serveru.