Register and enable the Doconut drop‑in converter widget in .NET 8

The drop‑in widget is Doconut’s ready‑made UI for uploading a file, running a conversion, and downloading the result.
Out of the box the widget’s three ?convert= endpoints return 404; they become active only when you register the Converter plugin and call AddConverterWidget() on DoconutOptions.

Below is a complete, copy‑paste‑ready startup configuration that satisfies both requirements.

---

1. Prerequisites – license and session support

• License – The Converter plugin requires a license that grants the Converter capability. Place the file (e.g., Doconut.Viewer.lic) somewhere reachable by the app and point DoconutOptions.LicensePath to it.
• Session state – Doconut’s security model stores document‑session tokens in ASP.NET Core session. Add a distributed cache and AddSession() before the middleware is wired.

builder.Services.AddDistributedMemoryCache();   // required for session
builder.Services.AddSession();                  // enables IDistributedCache‑backed session

---

2. Register the core Doconut services

AddDoconut() is the single entry point that injects the viewer, the license service, and the plugin registry.

builder.Services.AddDoconut(options =>
{
    // Tell Doconut where to find the license file.
    options.LicensePath = "Doconut.Viewer.lic";

    // Register the Converter plugin – this also validates the license capability.
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

If the license does not include the Converter capability, the call above throws InvalidOperationException and the application will not start. That fail‑fast behavior prevents you from deploying a mis‑licensed build.

---

3. Turn the widget on with AddConverterWidget

The widget is opt‑in. Calling AddConverterWidget() registers the three conversion endpoints (?convert=open, ?convert=run, ?convert=download) and wires a small amount of client‑side configuration (max upload size, base paths, etc.).

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

    // Enable the drop‑in UI and set the client‑side upload limit.
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // client pre‑check; server enforces its own limit
    });
});

Only the AddConverterWidget call creates the endpoints; the static JavaScript file (doconutConverter.js) is always served as an embedded resource, but it will fail to contact the server if the endpoints are missing.

---

4. Wire the middleware in the correct order

The middleware that serves static assets (UseDoconutResources) must run before the terminal viewer middleware (UseDoconut). Session middleware also needs to be placed earlier because Doconut validates the session on every request.

app.UseSession();           // must precede UseDoconut()
app.UseDoconutResources();  // serves JS, CSS, images
app.UseDoconut();           // handles ?convert= and document page requests

With this pipeline in place, a request to /doconut-res/doconutConverter.js succeeds, and the widget can call /doconut?convert=open, /doconut?convert=run, and /doconut?convert=download.

---

5. What the widget actually does

Phase	Server endpoint	Typical response
Open	?convert=open	Returns a JSON payload containing a token, page count, source extension, and the list of allowed target formats.
Run	?convert=run	Starts the conversion and returns a downloadToken, result page count, suggested filename, and a flag indicating whether the output is watermarked.
Download	?convert=download	Streams the converted file when the client follows the provided download URL.

Client‑side, the widget performs a pre‑upload size check against widget.MaxUploadMb. If the file exceeds that limit, the widget aborts the upload and fires the onError callback with phase = "open" and a friendly message. The server enforces its own limit and will answer 413 Payload Too Large if the request slips past the client check.

---

6. Hooking into widget events (C#‑side is not needed)

All callbacks (onReady, onSourceLoaded, onConverted, onError, etc.) are JavaScript functions supplied by the page that hosts the widget. Because the question focuses on the registration side, you do not need to write any additional C# code to handle those callbacks—the widget invokes them automatically once the endpoints are live.

---

7. Common pitfalls and how to avoid them

Symptom	Likely cause	Fix
404 on /doconut?convert=open	AddConverterWidget() was omitted.	Add the call as shown in section 3.
Application fails to start with InvalidOperationException about missing capability	License file does not grant Converter.	Obtain a license that includes the Converter capability.
Session‑related 500 error	UseSession() placed after UseDoconut() or missing cache registration.	Ensure app.UseSession() runs before app.UseDoconut() and that a cache service is registered.

---

8. Run the app and see the widget in action

1. Build and run the ASP.NET Core project.
2. Open a page that contains a <div id="doconut-convert"></div> element and includes the Doconut converter script (the script is served automatically from /doconut-res/doconutConverter.js).
3. Drag a supported file (PDF, DOCX, DWG, etc.) onto the drop area.
4. The widget will call ?convert=open, then ?convert=run, and finally present a Download link that points to ?convert=download.

If the three endpoints respond with JSON instead of 404, the widget is correctly registered and ready for production use.

---

Next step: Add the code snippets above to your Program.cs (or Startup.cs), verify that the license file is present, and launch the app. The drop‑in converter widget will be live without any further server‑side changes.