Registrera och aktivera Doconut drop‑in konverteringswidget i .NET 8

Drop‑in‑widgeten är Doconut’s färdiga UI för att ladda upp en fil, köra en konvertering och ladda ner resultatet.
Som standard returnerar widgetens tre ?convert=‑endpoints 404; de blir aktiva först när du registrerar Converter‑pluginet och anropar AddConverterWidget() på DoconutOptions.

Nedan följer en komplett, klar‑för‑kopiering startkonfiguration som uppfyller båda kraven.

---

1. Förutsättningar – licens och sessionsstöd

• Licens – Converter‑pluginet kräver en licens som ger Converter‑kapaciteten. Placera filen (t.ex. Doconut.Viewer.lic) någonstans som appen kan nå och peka DoconutOptions.LicensePath på den.
• Sessionsstatus – Doconut’s säkerhetsmodell lagrar dokument‑sessionstoken i ASP.NET Core‑session. Lägg till en distribuerad cache och AddSession() innan middleware‑kedjan är konfigurerad.

builder.Services.AddDistributedMemoryCache();   // krävs för session
builder.Services.AddSession();                  // aktiverar IDistributedCache‑stödd session

---

2. Registrera Doconut‑kärntjänsterna

AddDoconut() är den enda ingångspunkten som injicerar visaren, licenstjänsten och plugin‑registret.

builder.Services.AddDoconut(options =>
{
    // Berätta för Doconut var licensfilen finns.
    options.LicensePath = "Doconut.Viewer.lic";

    // Registrera Converter‑pluginet – detta validerar också licensfunktionaliteten.
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Om licensen inte inkluderar Converter‑kapaciteten, kastar anropet ovan InvalidOperationException och applikationen startar inte. Detta fail‑fast‑beteende förhindrar att du distribuerar en fellicensierad version.

---

3. Aktivera widgeten med AddConverterWidget

Widgeten är valfri. Genom att anropa AddConverterWidget() registreras de tre konverterings‑endpoints (?convert=open, ?convert=run, ?convert=download) och en liten mängd klient‑konfiguration (maximal uppladdningsstorlek, basvägar, osv.) kopplas in.

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

    // Aktivera drop‑in‑UI och sätt den klient‑sidiga uppladdningsgränsen.
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // klient‑förkontroll; servern upprätthåller sin egen gräns
    });
});

Endast AddConverterWidget‑anropet skapar endpoints; den statiska JavaScript‑filen (doconutConverter.js) levereras alltid som en inbäddad resurs, men den kommer att misslyckas med att kontakta servern om endpoints saknas.

---

4. Koppla middleware i rätt ordning

Middleware som levererar statiska resurser (UseDoconutResources) måste köras före den terminala visarmiddleware (UseDoconut). Sessions‑middleware måste också placeras tidigare eftersom Doconut validerar sessionen på varje begäran.

app.UseSession();           // måste föregå UseDoconut()
app.UseDoconutResources();  // serverar JS, CSS, bilder
app.UseDoconut();           // hanterar ?convert= och förfrågningar om dokumentsidor

Med denna pipeline på plats lyckas en begäran till /doconut-res/doconutConverter.js, och widgeten kan anropa /doconut?convert=open, /doconut?convert=run och /doconut?convert=download.

---

5. Vad widgeten faktiskt gör

Fas	Server‑endpoint	Typiskt svar
Öppna	?convert=open	Returnerar en JSON‑payload som innehåller en token, sidantal, källfilens filändelse och listan över tillåtna målformat.
Kör	?convert=run	Startar konverteringen och returnerar en downloadToken, resultat‑sidantal, föreslaget filnamn och en flagga som indikerar om resultatet är vattenmärkt.
Ladda ner	?convert=download	Strömmar den konverterade filen när klienten följer den angivna nedladdnings‑URL:en.

På klientsidan utför widgeten en för‑uppladdningsstorlekskontroll mot widget.MaxUploadMb. Om filen överskrider den gränsen avbryter widgeten uppladdningen och utlöser onError‑callbacken med phase = "open" och ett vänligt meddelande. Servern upprätthåller sin egen gräns och svarar med 413 Payload Too Large om begäran passerar klientens kontroll.

---

6. Ansluta till widget‑händelser (C#‑sidan behövs inte)

Alla callbacks (onReady, onSourceLoaded, onConverted, onError, osv.) är JavaScript‑funktioner som levereras av sidan som hostar widgeten. Eftersom frågan fokuserar på registrerings‑sidan behöver du inte skriva någon extra C#‑kod för att hantera dessa callbacks – widgeten anropar dem automatiskt när endpoints är aktiva.

---

7. Vanliga fallgropar och hur man undviker dem

Symtom	Trolig orsak	Åtgärd
404 på /doconut?convert=open	AddConverterWidget() utelämnades.	Lägg till anropet som visas i avsnitt 3.
Applikationen misslyckas att starta med InvalidOperationException om saknad kapacitet	Licensfilen ger inte Converter.	Skaffa en licens som inkluderar Converter‑kapaciteten.
Session‑relaterat 500‑fel	UseSession() placerad efter UseDoconut() eller saknad cache‑registrering.	Säkerställ att app.UseSession() körs före app.UseDoconut() och att en cache‑tjänst är registrerad.

---

8. Kör appen och se widgeten i aktion

1. Bygg och kör ASP.NET Core‑projektet.
2. Öppna en sida som innehåller ett <div id="doconut-convert"></div>‑element och inkluderar Doconut‑konverteringsskriptet (skriptet levereras automatiskt från /doconut-res/doconutConverter.js).
3. Dra en stödd fil (PDF, DOCX, DWG, osv.) till dropp‑området.
4. Widgeten kommer att anropa ?convert=open, sedan ?convert=run, och slutligen visa en Download‑länk som pekar på ?convert=download.

Om de tre endpoints svarar med JSON istället för 404, är widgeten korrekt registrerad och klar för produktionsbruk.

---

Nästa steg: Lägg till kodsnuttarna ovan i din Program.cs (eller Startup.cs), verifiera att licensfilen finns, och starta appen. Drop‑in‑konverteringswidgeten kommer att vara aktiv utan ytterligare server‑sidiga ändringar.