Konverteringsplugin

Converter‑pluginet förvandlar Doconut till en dokumentkonverteringstjänst. Det bidrar med motorn bakom den offentliga DocumentConverter‑fasaden, och — på begäran — en drop‑in‑widget med eget HTTP‑kontrakt, så att du kan konvertera dokument från C#, från widgeten, eller från ett frontend du själv skriver.

Installera paketet

Installera den senaste stabila Converter‑pluginen:

dotnet add package Doconut.NET6.Converter

För att låsa pluginet till den aktuella versionen 26.7.0, ange versionen separat:

dotnet add package Doconut.NET6.Converter --version 26.7.0

Håll Converter‑paketet på samma version som Doconut.NET6. Paket‑ID:t är Doconut.NET6.Converter; .26.7.0 visas endast i den nedladdade .nupkg‑filnamnet.

Registrera pluginet

Det finns ingen AddConverter()‑metod — Doconut:s plugin‑modell är enhetlig. Varje plugin, inklusive Converter, registreras på samma sätt: anropa AddPlugin<TPlugin>() inuti AddDoconut(). ConverterPlugin levereras i sitt eget NuGet‑paket, Doconut.NET6.Converter, installerat tillsammans med bas‑viewer‑paketet.

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

Detta anrop kastar ett undantag vid start om licensen saknas, en gammal TRIAL‑fil, eller en icke‑tillfällig licens som inte ger Converter‑kapacitet — ett InvalidOperationException som höjs inifrån AddDoconut(), innan appen börjar svara på förfrågningar. Tillfälliga Demo/NFR‑registreringar accepteras; efter deras kalenderutgång är konvertering fortfarande tillgänglig med vattenstämpel i resultatet. Det finns ingen tyst gratisnivå. Se Licensinställning för hur licenser laddas.

Konvertera från C#

Varje konvertering returnerar en sökbar MemoryStream placerad på 0, redo att läsas eller kopieras omedelbart. Hämta DocumentConverter från DI där du än behöver den — den är stateless av design, så en enda instans är säker att återanvända över förfrågningar.

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension includes the leading dot. password is null unless the document is protected.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Två detaljer som är lätta att missförstå: sourceExtension på ström‑overloaden måste inkludera den inledande punkten (".xlsx", inte "xlsx" ) — konverteraren matchar mot formatkatalogen och en ensam förlängning utan punkt löser inte upp. Och trots namnet returnerar WordToHtmlAsync Task<Stream>, inte Task<string> — du får HTML‑dokumentet (bilder inbäddade som Base64) som en ström, precis som alla andra konverteringsresultat.

Målformat

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

Inte varje källa kan konverteras till varje mål — pluginet mappar varje källas formatfamilj (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, webbdokument) till sin egen fasta uppsättning tillåtna mål. Hardkoda inte denna enum som UI‑listans mål: ?convert=open returnerar de faktiska allowedTargets för den fil som just laddats upp, och det är vad som bör driva en väljare.

Drop‑in‑widget

Widgetens ?convert=open|run|download‑ändpunkter är på begäran och inaktiverade från början — säkra som standard. Aktivera dem på serversidan, tillsammans med plugin‑registreringen:

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

<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

Utan AddConverterWidget() svarar de tre ?convert=‑ändpunkterna med 404 — men JS‑filen själv levereras ändå (det är en ren inbäddad statisk resurs; endast de ändpunkter den pratar med är låsta). AddConverterWidget() kräver fortfarande att Converter‑pluginet är registrerat och en licens som ger Converter — den ger inte konverteringsrättigheter på egen hand.

Anpassa widgeten

Init‑alternativ som skickas till Doconut.convert(selector, options):

Callbacks:

Doconut.convert() returnerar själva widget‑instansen — behåll den för att programatiskt styra widgeten:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // tillbaka till idle/drop‑skärmen; avfyrar inte onReady igen
conv.loadFile(file);  // startar flödet med ett File‑objekt; ingen effekt om den inte är idle
conv.destroy();       // tar bort lyssnare, tömmer mount‑punkten; instansen är oanvändbar efter detta

Bygg ditt eget frontend

Widgeten är bara en klient för detta HTTP‑kontrakt — bygg ditt eget frontend direkt mot det för en annan UX. Alla tre rutter ligger under den ASP.NET‑gren där UseDoconut() är monterad (vanligtvis /doconut):

Uppladdade källbytes lagras på servern med en TTL på 30 minuter; när detta fönster löper ut svarar run med 404 och filen måste öppnas på nytt. Det konverterade resultatet ligger i samma lagring — downloadToken får sin egen fräscha 30‑minutersperiod när konverteringen är klar — medan resultToken är en vanlig viewer‑sessions‑token vars livslängd följer viewer‑sessionens cache, oberoende av lagringen.

sourceExt i open‑svaret har ingen inledande punkt (t.ex. "docx" ) — motsatt konvention jämfört med parametern sourceExtension på DocumentConverter.ConvertAsync, som kräver en punkt.

Fel‑lägen, grupperade per rutt:

Resurshantering

Konverteraren returnerar en sökbar MemoryStream placerad på noll. Anroparen äger den strömmen och bör disponera den efter kopiering eller återlämnande av dess innehåll. DocumentConverter‑tjänsten själv är stateless och hämtas via dependency injection; bygg inte själv eller disponera tjänsten manuellt.

För webb‑widgeten har uppladdnings‑ och nedladdnings‑lagren oberoende 30‑minuters TTL. En viewer‑resultToken följer viewer‑sessionens livstid istället. Att stänga ett viewer‑resultat tar inte bort ett fortfarande giltigt nedladdnings‑lagring, och att återställa webbläsar‑widgeten förlänger inte någon av TTL‑erna.

Felsökning

Vattenstämpling

Med ConverterPlugin registrerad är värdens licens i ett av tre tillstånd:

Båda anropsvägarna beräknar flaggan med samma regel: DocumentConverter‑C#‑fasaden härleder den internt från licensens IsViewerLicensed och IsTemporary‑status, och widgetens ?convert=run‑handler gör motsvarande kontroll (IsViewerLicensed && !IsTrial && !IsTemporary) för att fylla i fältet watermarked som den returnerar. En integration kan byggas och testas end‑to‑end på en utvärderingslicens innan köp — endast byteströmmen förändras.