Konverteringsplugin

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

Installera paketet

Installera den senaste stabila Converter‑pluginet:

dotnet add package Doconut.NETStandard.Converter

För att låsa pluginet till den aktuella 26.8.0‑utgåvan, ange versionen separat:

dotnet add package Doconut.NETStandard.Converter --version 26.8.0

Håll Converter‑paketet på samma version som Doconut.NETStandard. Paket‑ID:t är Doconut.NETStandard.Converter; .26.8.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>() inom AddDoconut(). ConverterPlugin levereras i sitt eget NuGet‑paket, Doconut.NETStandard.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 en licens saknas, en äldre TRIAL‑fil, eller en icke‑tillfällig licens som inte ger Converter‑kapaciteten — ett InvalidOperationException som höjs inifrån AddDoconut(), innan appen hanterar förfrågningar. Tillfälliga Demo/NFR‑registreringar accepteras; efter deras kalenderutgång är konvertering fortfarande tillgänglig med vattenstämpel på 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.

viewer.Converter.GetConverter() finns inte här. Konvertering nås inte längre via viewer‑instansen: injicera Doconut.DocumentConverter istället.

// 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 i ström‑överladdningen måste inkludera den inledande punkten (".xlsx", inte "xlsx") — konverteraren matchar den mot formatkatalogen och en ensam filändelse löser sig inte. 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 varje annat konverteringsresultat.

Målformat

ConversionTarget (namnrymd Doconut.Configs.Conversion) har 45 medlemmar:

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp, Msg, Eml, Emlx, Mhtml,
Xlsm, Xlsb, Ppt, Docm, Dot, Dotx, Dotm, Vsdx, Vssx, Vstx, Vsdm, Vssm, Vstm,
Vdx, Vsx, Vtx, Ico

Detta enum täcker varje källfamilj. Det tidigare biblioteket hade en typ per familj *ConfigConverter — WordConfigConverter, ExcelConfigConverter och så vidare — var och en med sitt eget inbäddade EnTargetFormat‑enum, samt ett SourceFormatConverter‑enum för indata. Alla dessa är borta; se migrationsguide.

Inte varje källa konverteras till varje mål — pluginet mappar varje källformatsfamilj (Word, Excel, PowerPoint, PDF, CAD, Bild, E‑post, Diagram, Projekt/Uppgift, PSD, webb‑dokument) till sin egen fasta uppsättning tillåtna mål. Hardkoda inte detta enum som din UI:s mållista: ?convert=open returnerar de faktiska allowedTargets för den fil som just har laddats upp, och det är vad som bör styra en väljare.

Inbäddningswidget

Widgetens ?convert=open|run|download-endpunkter är valfria 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=-endpunkterna med 404 — men JS-filen levereras ändå (det är en enkel inbäddad statisk resurs; endast de endpunkter den kommunicerar med är begränsade). AddConverterWidget() kräver fortfarande att Converter‑pluginet är registrerat och en licens som beviljar Converter — den ger inte konverteringsrättigheter på egen hand.

Anpassa widgeten

Initieringsalternativ som skickas till Doconut.convert(selector, options):

Callback-funktioner:

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

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // tillbaka till den inaktiva/släppskärmen; utlöser 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 gränssnitt mot det direkt för en annan användarupplevelse. 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 lever i samma lagring — downloadToken får sitt eget fräscha 30‑minutersfönster när konverteringen är klar — medan resultToken är en vanlig visningssession‑token vars livslängd följer visningssessionens 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.

Felmoder, grupperade efter rutt:

Resursägande

Konverteraren returnerar en sökbar MemoryStream som är placerad på noll. Anroparen äger den strömmen och bör avvisa den efter att ha kopierat eller returnerat dess innehåll. DocumentConverter‑tjänsten i sig är tillståndslös och hämtas via beroendeinjektion; bygg inte själv eller avvisa tjänsten manuellt.

För webbwidgeten har uppladdnings‑ och nedladdningslagren oberoende TTL på 30 minuter. En visnings‑resultToken följer i stället visningssessionens livstid. Att stänga ett visningsresultat tar inte bort ett fortfarande giltigt nedladdningslager, och att återställa webbläsarwidgeten förlänger inte någon av TTL:erna.

Felsökning

Vattenmärkning

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

Båda anropsvägarna beräknar flaggan utifrån samma regel: DocumentConverter C#‑fasaden härleder den internt från licensens IsViewerLicensed‑ och IsTemporary‑tillstånd, och widgetens ?convert=run‑hanterare 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 bytes i utdata förändras.