Plugin pro konverzi

Plugin Converter promění Doconut na službu pro převod dokumentů. Poskytuje motor za veřejnou fasádou DocumentConverter a — volitelně — vložitelný widget se svým vlastním HTTP kontraktem, takže můžete převádět dokumenty z C#, z widgetu nebo z frontendové aplikace, kterou si sami napíšete.

Instalace balíčku

Nainstalujte nejnovější stabilní verzi pluginu Converter:

dotnet add package Doconut.NET8.Converter

Pro připnutí pluginu k aktuálnímu vydání 26.7.0 předejte verzi samostatně:

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

Udržujte balíček Converter ve stejné verzi jako Doconut.NET8. Identifikátor balíčku je Doconut.NET8.Converter; .26.7.0 se objeví jen v název staženého souboru .nupkg.

Registrace pluginu

Neexistuje metoda AddConverter() — model pluginů Doconut je jednotný. Každý plugin, včetně Converter, se registruje stejným způsobem: zavolejte AddPlugin<TPlugin>() uvnitř AddDoconut(). ConverterPlugin je součástí vlastního NuGet balíčku Doconut.NET8.Converter, který se nainstaluje spolu se základním balíčkem vieweru.

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

Toto volání vyvolá výjimku při startu, pokud chybí licence, starý soubor TRIAL nebo ne‑dočasná licence, která nepřiděluje schopnost Converter — InvalidOperationException vyvolaná uvnitř AddDoconut(), ještě před tím, než aplikace začne obsluhovat požadavky. Dočasné Demo/NFR licence jsou akceptovány; po jejich kalendářním vypršení je převod nadále dostupný, ale s vodoznakem. Tichý bezplatný tarif neexistuje. Viz Nastavení licence pro způsob načítání licencí.

Převod z C#

Každý převod vrací vyhledávatelný MemoryStream nastavený na pozici 0, připravený k čtení nebo kopírování okamžitě. Získejte DocumentConverter z DI kdekoliv, kde jej potřebujete — je bezstavový, takže jedna instance je bezpečná pro opakované použití napříč požadavky.

// 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);

Dvě detaily, které se snadno přehlédnou: sourceExtension u přetížení pro stream musí obsahovat úvodní tečku (".xlsx", ne "xlsx" ) — konvertor ji porovnává s katalogem formátů a samotná přípona by se jinak nerozpoznala. A ačkoliv název napovídá, WordToHtmlAsync vrací Task<Stream>, nikoli Task<string> — získáte HTML dokument (obrázky vložené jako Base64) jako stream, stejně jako výsledek každého jiného převodu.

Cílové formáty

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

Ne každý zdroj lze převést na každý cíl — plugin mapuje rodinu formátů zdroje (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, webový dokument) na vlastní pevně danou sadu povolených cílů. Nepište tento enum přímo do UI jako pevný seznam: ?convert=open vrací skutečné allowedTargets pro právě nahraný soubor a právě to by mělo napájet výběrový seznam.

Vložitelný widget

Endpointy widgetu ?convert=open|run|download jsou volitelné a výchozí jsou zakázané — bezpečné z výchozího nastavení. Povolit je můžete na serveru při registraci pluginu:

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>

Bez AddConverterWidget() vrací tři endpointy ?convert= chybu 404 — ale samotný JS soubor je i tak servírován (je to prostý vložený statický zdroj; jen endpointy, ke kterým se odkazuje, jsou omezené). AddConverterWidget() stále vyžaduje, aby byl registrován plugin Converter a aby licence udělovala Converter — sama o sobě nepřiděluje práva k převodu.

Přizpůsobení widgetu

Inicializační možnosti předávané do Doconut.convert(selector, options):

Callbacky:

Doconut.convert() vrací samotnou instanci widgetu — uchovejte ji, pokud chcete widget ovládat programově:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // zpět na nečinnou/drop obrazovku; nevyvolá znovu onReady
conv.loadFile(file);  // spustí tok s objektem File; neudělá nic, pokud není v idle stavu
conv.destroy();       // odstraní posluchače, vyprázdní montáž; instance po tomto není použitelná

Vytvořte si vlastní frontend

Widget je jen klient pro tento HTTP kontrakt — postavte si vlastní frontend přímo proti němu pro odlišný UX. Všechny tři cesty leží pod ASP.NET větví, kde je UseDoconut() namontováno (obvykle /doconut):

Nahrané bajty zdroje jsou uloženy na serveru s TTL 30 minut; po uplynutí tohoto okna vrátí run chybu 404 a soubor je třeba znovu otevřít. Převodní výsledek žije ve stejném úložišti — downloadToken získá vlastní čerstvé 30‑minutové okno po dokončení převodu — zatímco resultToken je obyčejný token relace vieweru, jehož životnost následuje cache relace vieweru, nezávisle na úložišti.

sourceExt v odpovědi open nemá úvodní tečku (např. "docx" ) — opačný konvence oproti parametru sourceExtension metody DocumentConverter.ConvertAsync, který tečku vyžaduje.

Režimy selhání, seskupené podle cesty

Vlastnictví zdrojů

Konvertor vrací vyhledávatelný MemoryStream nastavený na nulu. Volající vlastní tento stream a měl by jej uvolnit po zkopírování nebo vrácení obsahu. Služba DocumentConverter je bezstavová a získává se z dependency injection; nesnažte se ji konstruovat ani ručně uvolňovat.

Pro webový widget mají úložiště nahrávání a stahování nezávislé TTL 30 minut. Token resultToken vieweru následuje životnost relace vieweru. Uzavření výsledku vieweru nesmaže stále platné úložiště ke stažení a resetování widgetu v prohlížeči neprodlouží žádný z TTL.

Řešení problémů

Vodoznakování

S registrovaným ConverterPlugin je licence hostitele v jednom ze tří stavů:

Oba cesty výpočtu flagu používají stejný pravidlo: C# fasáda DocumentConverter interně odvozuje stav z licence (IsViewerLicensed a IsTemporary), a widgetův handler ?convert=run provádí ekvivalentní kontrolu (IsViewerLicensed && !IsTrial && !IsTemporary) pro naplnění pole watermarked. Integraci lze postavit a otestovat end‑to‑end na evaluační licenci před zakoupením — mění se jen výstupní bajty.