Plugin pro převod

Převádějte dokumenty do 45 cílových formátů

Plugin Converter promění Doconut na službu pro převod dokumentů. Poskytuje engine za veřejnou DocumentConverter fasádou a — volitelně — vložitelný widget poskytovaný DocImage.axd, takže můžete převádět dokumenty z C#, z widgetu nebo z frontendu, který si vytvoříte.

RozhraníKdy použít
DocumentConverter (C#)Převádíte na serveru, bez zapojení prohlížeče
Drop-in widget (doconutConverter.js)Chcete připravenou obrazovku pro nahrání, převod a stažení ve své stránce
HTTP endpoints on DocImage.axd (?convert=open|run|download)Vytvoříte si vlastní UI pro převod podle dokumentovaného serverového kontraktu

Instalace balíčku

powershell
Install-Package Doconut.NETFramework.Converter

Pro připnutí pluginu k verzi, kterou tato dokumentace popisuje:

powershell
Install-Package Doconut.NETFramework.Converter -Version 26.10.0

Udržujte balíček Converter ve stejné verzi jako Doconut.NETFramework.

Licenční soubor pluginu, Doconut.Viewer.Converter.lic, umístěte do stejné složky jako Doconut.Viewer.lic; je načten spolu s licencí prohlížeče.

Registrace pluginu

Každý plugin se registruje stejným způsobem: AddPlugin<TPlugin>() v DoconutHost.Initialize, voláno z Application_Start.

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

To je vše, co potřebuje C# fasáda. Widget a jeho HTTP koncové body jsou samostatná volitelná funkce, AddConverterWidget() (viz Widget pro vložení).

Plugin potřebuje licenci, která poskytuje schopnost Converter. Bez ní DoconutHost.Initialize vyvolá výjimku z Application_Start:

text
The Converter plugin is registered via AddPlugin but no active license grants Converter. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

V System.Web to znamená, že každá žádost vrátí prázdný 500 a důvod je zaznamenán pouze v protokolu událostí Windows (zdroj ASP.NET). Vyvolá výjimku při chybě licence, starém souboru TRIAL, licenci bez Converter a placené licenci použití mimo její časové okno. Dočasné licence Demo/NFR jsou akceptovány. Viz Nastavení licence.

Licencování a vodoznak

Stav licenceSpuštěníVýstup převodu
Placená licence pro prohlížeč poskytující Converter, v rámci jejího časového oknaSpouštíČistý — watermarked: false
Aktivní dočasná (Demo/NFR) licenceSpouštíPřevádí, s evaluačním vodoznakem — watermarked: true
Expirující dočasná (Demo/NFR) licenceSpouštíPřevádí, s evaluačním vodoznakem — watermarked: true
Žádná licence, starý soubor TRIAL, licence bez Converter, nebo placená licence mimo její časové oknoApplication_Start vyvolá výjimku; každá žádost vrátí prázdný 500—

Fasáda DocumentConverter a handler ?convert=run widgetu používají stejné pravidlo. Integraci lze postavit a otestovat od začátku do konce na evaluační licenci před nákupem — mění se jen výstupní bajty.

Zdroj DICOM (.dcm, .ima) také potřebuje schopnost Dicom. Bez ní ConvertAsync vyvolá LicenseException (Converting '.dcm' requires the Dicom capability license.) a handler widgetu open odpovídá 403.

Použití z C#

Každý převod vrací seekovatelný MemoryStream nastavený na 0. DocumentConverter je bezstavový: získáte jej z DoconutHost.Services kdekoliv ho potřebujete a můžete jej volně znovu použít.

csharp
// Získejte DocumentConverter z DoconutHost.Services; jeho konstruktor je interní, takže jej nikdy `new` nevolejte.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);
csharp
// sourceExtension zahrnuje úvodní tečku. password je null, pokud dokument není chráněn.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);
csharp
Stream html = await converter.WordToHtmlAsync("report.docx", ct);
csharp
// html: Stream obsahující HTML, které se má převést zpět na dokument Word, například výsledek WordToHtmlAsync.
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Dva detaily, které se snadno špatně pochopí: sourceExtension u přetížení streamu musí obsahovat úvodní tečku (".xlsx", ne "xlsx"), jinak se nevyřeší. A navzdory názvu WordToHtmlAsync vrací Task<Stream>, ne Task<string> — HTML dokument (obrázky vložené jako Base64) přichází jako stream, stejně jako každý jiný výsledek.

Volající vlastní MemoryStream, který převod vrátí, a měl by jej uvolnit po zkopírování nebo vrácení (MVC File(stream, …) jej uvolní za vás). Nevytvářejte ani neuvolňujte DocumentConverter sami — jeho konstruktor je interní.

V MVC 5 kontroleru

Udělejte akci asynchronní a await konverzi:

csharp
[HttpPost]
public async Task<ActionResult> ToPdf(HttpPostedFileBase file)
{
    var converter = Doconut.DoconutHost.Services.GetRequiredService<DocumentConverter>();
    Stream pdf = await converter.ConvertAsync(
        file.InputStream, Path.GetExtension(file.FileName), ConversionTarget.Pdf,
        password: null, ct: Response.ClientDisconnectedToken);
    return File(pdf, "application/pdf", Path.GetFileNameWithoutExtension(file.FileName) + ".pdf");
}

Ve Web Forms: nikdy neblokujte konverzi

Stránka Web Forms běží v jednovláknovém kontextu požadavku. ConvertAsync pokračuje v tomto kontextu, když dokončí, takže stránka, která na něj čeká synchronně — .Result, .Wait(), .GetAwaiter().GetResult() — drží právě vlákno, které konverze potřebuje k dokončení. Požadavek se nikdy nevrátí. Prohlížeč stále otáčí, IIS nic neukazuje v logu a zbytek webu funguje, takže to vypadá jako pomalá konverze spíše než deadlock.

Označte stránku Async="true" a spusťte konverzi jako asynchronní úlohu stránky:

aspx
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>
csharp
// Web Forms: směrnice @Page vyžaduje Async="true" a konverze běží jako asynchronní úloha stránky.
// Blokování na to místo toho (.Result, .Wait(), .GetAwaiter().GetResult()) způsobí zablokování požadavku:
// nikdy se nevrátí a nic se nezaznamená.
protected void Page_Load(object sender, EventArgs e)
{
    if (!IsPostBack) return;

    RegisterAsyncTask(new PageAsyncTask(async ct =>
    {
        var converter = Doconut.DoconutHost.Services.GetRequiredService<DocumentConverter>();

        using (var pdf = await converter.ConvertAsync(
                   Server.MapPath("~/App_Data/contract.docx"), ConversionTarget.Pdf, ct: ct))
        using (var ms = new MemoryStream())
        {
            if (pdf.CanSeek) pdf.Position = 0;
            await pdf.CopyToAsync(ms);

            Response.ContentType = "application/pdf";
            Response.AddHeader("Content-Disposition", "attachment; filename=contract.pdf");
            Response.BinaryWrite(ms.ToArray());
            // Context, ne HttpContext.Current: po await může být ten druhý null.
            Context.ApplicationInstance.CompleteRequest();
        }
    }));
}

Bez Async="true" v direktivě @Page je RegisterAsyncTask tiše ignorováno. Po await použijte Context stránky; HttpContext.Current může být tam null.

Cílové formáty

ConversionTarget (namespace Doconut.Configs.Conversion) má 45 členů:

text
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

Ne každý zdroj se převádí na každý cíl: každá rodina formátů zdroje (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project, PSD, webový dokument, DICOM) má vlastní sadu povolených cílů. Převod DICOM zdroje (.dcm, .ima) také vyžaduje licenci, která poskytuje schopnost Dicom; jeho cíle jsou Pdf, Png, Jpeg, Bmp, Tiff a Gif. Nezakódujte tento výčet pevně jako seznam cílů ve vašem UI: ?convert=open vrací allowedTargets pro nahraný soubor, a to je to, co by mělo řídit výběr.

Vkládací widget

Povolit koncové body

Koncové body widgetu ?convert=open|run|download jsou poskytovány DocImage.axd a jsou ve výchozím nastavení vypnuté. Povolit je vedle registrace pluginu:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;
    });
});
// System.Web načte celý upload předtím, než ho Doconut vidí: udržujte maxRequestLength (KB) a
// maxAllowedContentLength (bytes) v souboru Web.config nad MaxUploadMb widgetu.

AddConverterWidget() bez argumentu povolí widget s výchozími hodnotami (MaxUploadMb = 25). Samotné nepřiděluje práva k převodu: potřebuje AddPlugin<ConverterPlugin>(), nebo DoconutHost.Initialize vyhodí výjimku:

text
AddConverterWidget() was called but the Converter plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() (the widget needs it), or remove the AddConverterWidget() call.

Dvě věci ke kontrole, když widget nefunguje správně:

  • basePath: '/DocImage.axd'. Výchozí nastavení widgetu, /doconut, je koncový bod ASP.NET Core. V tomto balíčku jsou koncové body obsluhovány DocImage.axd handlerem z Web.config.
  • Skript a koncové body jsou nezávislé. Modul zdrojů poskytuje doconutConverter.js bez ohledu na to, zda je widget povolen. Bez AddConverterWidget() se widget načte, vykreslí svou oblast pro přetažení a vypadá naprosto správně — a jeho první akce odpovídá 404.

Limity nahrávání

ASP.NET načte celé tělo požadavku před tím, než se spustí DocImage.axd. Nahrání nad MaxUploadMb, ale pod limity hostitele, získá vlastní JSON widgetu 413 (File is too large.). Nahrání nad limity hostitele je nejprve odmítnuto IIS, s chybovou stránkou, kterou widget nemůže přečíst. Udržujte oba limity hostitele v Web.config nad limitem widgetu:

xml
<system.web>
  <httpRuntime maxRequestLength="30720" />           <!-- KILOBAJTY: 30 MB -->
</system.web>
<system.webServer>
  <security>
    <requestFiltering>
      <requestLimits maxAllowedContentLength="31457280" />  <!-- BAJTY: 30 MB -->
    </requestFiltering>
  </security>
</system.webServer>

Vložte jej

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

Doconut.convert(selectorOrElement, options) přijímá CSS selektor nebo element, vyhodí výjimku, pokud není montáž nalezena, a vrací handle. Widget nahrává soubor, zobrazuje náhled první stránky, umožňuje uživateli vybrat jeden z allowedTargets, převádí, náhled výsledku zobrazí, když může, a nabízí stažení.

Možnosti

MožnostTypVýchozíPoznámky
basePathstring/doconutURL koncového bodu. Nastavte '/DocImage.axd' na tento balíček
resPathstring/doconut-resPřijato pro konzistenci s ostatními Doconut widgety; konverzní widget nevybuduje žádnou URL z toho
maxUploadMbnumber25Pouze předběžná kontrola na klientovi; server vynutí svůj vlastní limit
licenseUrlstring | nullnullPřemění upozornění na vodoznak na výsledkové obrazovce na odkaz
labelsobject{}Přepíše libovolnou podmnožinu anglických řetězců widgetu

Zpětné volání

CallbackSpustí se, kdyžData
onReady()Widget vykreslil svou obrazovku pro přetažení—
onSourceLoaded({ token, pages, sourceExt, allowedTargets })?convert=open úspěšně proběhneZdrojový token, počet stránek, přípona zdroje (bez úvodní tečky), povolené cíle
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target })?convert=run úspěšně proběhneOdpověď běhu plus požadovaný target
onDownload({ downloadName, downloadToken })Uživatel klikne na StáhnoutSpustí se spolu s vlastním stažením prohlížeče
onError({ phase, message })Požadavek na otevření nebo spuštění selžephase je 'open' nebo 'run'; message je sanitizovaná chyba serveru

Callback, který vyhodí výjimku, je zachycen a zalogován; nikdy neporuší tok widgetu.

Imperativní handle

Doconut.convert() vrací instanci widgetu:

javascript
const conv = Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd' });
const file = document.querySelector('#picker').files[0]; // File z vašeho vlastního <input type="file" id="picker">
conv.reset();         // zpět na obrazovku pro upuštění; nespustí znovu onReady
conv.loadFile(file);  // spustí tok s File; nečinné, pokud widget není na své obrazovce pro upuštění
conv.destroy();       // odstraní posluchače, vyprázdní mount; instance je po tomto nepoužitelná

Štítky

Každý řetězec má výchozí anglickou verzi; labels přepíše libovolnou podmnožinu a zbytek zůstane anglický. Fragmenty, které se mění za běhu, používají {placeholders}, například uploading: 'Uploading {name}…' a pages: '{n} pages'.

KlíčAnglický výchozí
dropPromptDrag & drop a document here
dropHintPDF, Word, Excel, PowerPoint, images and more
chooseFileChoose file
uploadingUploading {name}…
page / pages1 page / {n} pages
noTargetsNo conversion targets are available for this file.
convertTo / convertConvert to / Convert
convertingConverting to {target}…
readyToDownloadReady to download
download / convertAnotherDownload / Convert another
watermarkNoticeOutput is watermarked — get a license to remove it.
retryRetry
genericErrorSomething went wrong. Please try again.
sizeLimitThat file is larger than the {mb} MB upload limit. Please choose a smaller file.
serverErrorThe server could not process this request. Please try again.
networkErrorCould not reach the server. Please check your connection and try again.

Další klíče pokrývají aria-label drop zóny (dropAriaLabel), texty náhledu alt (previewAlt, resultAlt), propojenou formu upozornění na vodoznak používanou s licenseUrl (watermarkNoticePrefix, watermarkNoticeLink, watermarkNoticeSuffix), nečitelné odpovědi (badResponse) a oznámení aria-live (annReady, annUploading, annLoaded, annLoadedNoTargets, annConverting, annDone, annError).

JSON chyba ze serveru je zobrazena tak, jak ji server napsal; serverError se používá jen když selhávající odpověď neobsahuje JSON chybu, například 404 zakázaného widgetu.

Tématizace

Widget přidá třídu dcw k elementu, do kterého je připojen, a načte jeho barvy, poloměr a písmo z vlastních CSS vlastností, takže jej můžete tematizovat, aniž byste zasahovali do jeho vnitřní struktury:

css
#doconut-convert.dcw {
  --dcw-accent: #6b46c1;
  --dcw-radius: 12px;
  --dcw-font: "Inter", system-ui, sans-serif;
}

Výchozí hodnoty: --dcw-accent: #2b6cb0, --dcw-bg: #ffffff, --dcw-fg: #1a202c, --dcw-muted: #718096, --dcw-border: #cbd5e0, --dcw-radius: 8px a systémové UI písmo pro --dcw-font.

Vytvořte si vlastní frontend

Widget je klientem pro tuto HTTP smlouvu na DocImage.axd. Trasy odpovídají 404, dokud není zavoláno AddConverterWidget(). Chyby nesou JSON tělo, { "error": "..." }, kromě případů, kdy tabulka uvádí „pouze stav“. Neznámá hodnota ?convert= odpovídá 400.

TrasaÚčelÚspěšná odpověď
POST /DocImage.axd?convert=open (multipart, one file)Nahrát a otevřít zdrojový dokument200 — { token, pages, sourceExt, allowedTargets }
POST /DocImage.axd?token=<token>&convert=run&target=<ext>Převést nahraný zdroj na target200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET /DocImage.axd?convert=download&token=<downloadToken>Streamovat převedený soubor200 — soubor, Content-Disposition: attachment, Cache-Control: no-store

sourceExt v odpovědi open nemá úvodní tečku ("docx") — naopak než parametr sourceExtension u ConvertAsync. allowedTargets uvádí názvy cílů malými písmeny ("pdf", "html", …); předáte jeden z nich jako target, který se porovnává bez ohledu na velikost písmen. open používá první soubor v multipart těle.

resultToken je null a resultPages je 0, když výsledek nelze náhlednout. downloadName je název zdrojového souboru s příponou cíle.

Náhledové obrázky používají standardní trasu pro obrázek prohlížeče, /DocImage.axd?token={token}&page=1&thumb=1&width={px}, s token z open nebo resultToken z run. Widget požaduje width=240.

Nahrané zdroje jsou uchovávány po dobu 30 minut od posledního čtení; poté run odpovídá 404 a soubor je nutné znovu otevřít. downloadToken získá vlastní 30‑minutové okno po dokončení převodu. resultToken je běžný token prohlížeče pro náhled výsledku; když lze výsledek náhlednout, má stejnou hodnotu jako downloadToken.

TrasaStavKdyTělo
libovolná404Widget není povolen (AddConverterWidget() nebyl nikdy zavolán)pouze stav
libovolná405Špatná metoda (open/run vyžadují POST, download vyžaduje GET)pouze stav
open400Není multipart nahráníExpected a multipart file upload.
open400Žádný soubor, nebo prázdnýNo file uploaded.
open400Typ, který nelze převéstThis file type cannot be converted.
open403Typ souboru vyžaduje funkci, kterou licence neposkytuje (DICOM soubor bez Dicom)Converting this file type requires the Dicom capability license.
open413Nahrání překračuje MaxUploadMb (ale ne limity IIS)File is too large.
run400Poškozený token (není GUID)Invalid token.
run400target, který se nedá parsovat na ConversionTargetUnknown target format.
run400Cíl není v allowedTargetsThat target format is not available for this file.
run404Nahrání vypršelo nebo nebylo nikdy otevřenoUpload expired — please re-open the file.
open, run500Zpracování selhaloOčistěná zpráva
download400 / 404Poškozený, neznámý nebo vypršelý token ke staženípouze stav

Kompletní cyklus s fetch:

javascript
// file: soubor k převodu, například z <input type="file">.
async function convertFile(file) {
  const base = '/DocImage.axd';

  // 1. open: nahrát soubor
  const form = new FormData();
  form.append('file', file, file.name);
  const openResp = await fetch(base + '?convert=open', { method: 'POST', body: form });
  if (!openResp.ok) throw new Error((await openResp.json()).error);
  const opened = await openResp.json();

  // 2. run: převést do PDF, pokud je to povoleno, jinak na první povolený cíl
  const target = opened.allowedTargets.includes('pdf') ? 'pdf' : opened.allowedTargets[0];
  const runResp = await fetch(base + '?token=' + encodeURIComponent(opened.token) +
    '&convert=run&target=' + target, { method: 'POST' });
  if (!runResp.ok) throw new Error((await runResp.json()).error);
  const converted = await runResp.json();

  // 3. download: prostý GET, který může prohlížeč následovat
  window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}

Endpointy jsou same-origin: tato verze nemá podporu CORS. Servírujte své UI a skript widgetu ze stejného původu jako Doconut, nebo použijte reverse-proxy pro obslužný program a cesty zdrojů pod původem vašeho UI.

V produkci

  1. Nainstalujte plugin vedle hlavního balíčku, ve stejné verzi: Install-Package Doconut.NETFramework.Converter.
  2. Přidejte licenční soubor. Umístěte Doconut.Viewer.Converter.lic do stejné složky jako Doconut.Viewer.lic.
  3. Nastavte limity nahrávání. MaxUploadMb v AddConverterWidget je limit, který Doconut vynucuje; udržujte maxRequestLength a maxAllowedContentLength v Web.config nad ním (viz Limity nahrávání), a maxUploadMb widgetu rovný tomuto limitu.
  4. Nikdy neblokujte konverzi ve Web Forms (viz Ve Web Forms).
  5. Uvolněte výsledky konverze. Proud ConvertAsync, který se vrací, je sdílený; jeho uvolněním se vrátí jeho buffery do fondu.

Webové farmy

Widget uchovává každé nahrání a jeho výsledek v paměti na serveru, který obsloužil open. Za load balancerem bez sticky sessions může pozdější run, download nebo požadavek na náhled dorazit na jiný server a nahrání nenajít. Zaregistrujte sdílené, šifrované úložiště widgetu pomocí druhého argumentu funkce DoconutHost.Initialize:

csharp
byte[] farmKey = Convert.FromBase64String(System.Configuration.ConfigurationManager.AppSettings["Doconut:FarmKey"]);

Doconut.DoconutHost.Initialize(
    options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
        options.AddConverterWidget();
    },
    services => services.AddDoconutDistributedWidgets(store =>
    {
        store.RootPath = @"\\fileshare\doconut";   // složka, kterou může každý server číst i zapisovat
        store.FarmKey = farmKey;                   // alespoň 32 bajtů, identické na každém serveru
        // store.Ttl = TimeSpan.FromMinutes(30);   // jak dlouho je nahrání uchováno (výchozí)
    }));
  • Jeden server nepotřebuje nic: bez tohoto volání se používá paměťové úložiště.
  • Nahrání a výsledky jsou v klidu na sdíleném úložišti šifrovány (AES-256, encrypt-then-MAC) a každý soubor je svázán se svým tokenem, takže jeden token nikdy nemůže číst soubor jiného tokenu.
  • Na sdíleném úložišti je nahrání nebo výsledek uchován po dobu Ttl po jeho zápisu; čtení neprodlouží toto období.
  • FarmKey musí mít alespoň 32 bajtů a být stejný na každém serveru. Načtěte jej z tajného úložiště; nikdy jej nezakódujte přímo. Registrace vyhodí ArgumentException, když RootPath chybí nebo je FarmKey kratší než 32 bajtů.
  • Nastavte RootPath na stejné sdílené umístění, které používá distribuovaný prohlížeč.

Referenční API

Fasáda a možnosti widgetu jsou v jmenném prostoru Doconut; ConversionTarget je v Doconut.Configs.Conversion. ConverterPlugin je v Doconut.Plugins.Converter.

DocumentConverter

csharp
public sealed class DocumentConverter
{
    public Task<Stream> ConvertAsync(
        string filePath, ConversionTarget target,
        string? password = null, CancellationToken ct = default);

    public Task<Stream> ConvertAsync(
        Stream source, string sourceExtension, ConversionTarget target,
        string? password = null, CancellationToken ct = default);

    public Task<Stream> WordToHtmlAsync(string filePath, CancellationToken ct = default);

    public Task<Stream> HtmlToWordAsync(
        Stream htmlSource, ConversionTarget outputFormat = ConversionTarget.Docx,
        CancellationToken ct = default);
}

Vyřešeno z DoconutHost.Services; konstruktor je interní. sourceExtension zahrnuje úvodní tečku. HtmlToWordAsync zapisuje soubor .doc, když je outputFormat ConversionTarget.Doc, a soubor .docx pro jakoukoli jinou hodnotu.

ConversionTarget

45 výstupních formátů uvedených v Formáty cíle.

ConverterWidgetOptions

csharp
public sealed class ConverterWidgetOptions
{
    public int MaxUploadMb { get; set; } = 25;
}

Nastavuje se přes DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null), který vrací DoconutOptions, takže lze volání řetězit.

Odstraňování potíží

SymptomPříčinaOprava
Každý požadavek vrací prázdný 500 po přidání pluginu; Windows event log (source ASP.NET) ukazuje The Converter plugin is registered via AddPlugin but no active license grants Converter.Žádná licence, soubor TRIAL, licence bez Converter, nebo placená licence mimo její časové okno verzeNainstalujte licenci, která poskytuje Converter, nebo odstraňte AddPlugin<ConverterPlugin>()
Každý požadavek vrací prázdný 500; protokol událostí ukazuje AddConverterWidget() was called but the Converter plugin is not registered.Widget je povolen bez svého pluginuPřidejte options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>()
Řešení DocumentConverter vyvolá No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().ConverterPlugin není registrovánPřidejte AddPlugin<ConverterPlugin>() do DoconutHost.Initialize
Konverze Web Forms nikdy nevracíStránka blokuje na ConvertAsyncPoužijte Async="true" a RegisterAsyncTask
Převod proudu uvádí, že formát není podporovánsourceExtension nemá úvodní tečkuPředávejte ".xlsx", ne "xlsx"
ConvertAsync vyvolá Converting '.dcm' requires the Dicom capability license.Zdroj DICOM a licence neposkytuje DicomPoužijte licenci, která poskytuje Dicom
Výstup je opatřen vodoznakemLicence je dočasná (Demo/NFR)Použijte placenou licenci, která poskytuje Converter
Widget se načte, ale jeho požadavky vrací 404AddConverterWidget() nebyl zavolán, nebo basePath není '/DocImage.axd'Zavolejte AddConverterWidget(); nastavte basePath: '/DocImage.axd'
Velký upload zobrazuje stránku chyby IIS místo zprávy widgetumaxRequestLength / maxAllowedContentLength jsou pod MaxUploadMbZvyšte limity Web.config nad MaxUploadMb
open odpovídá 403 Converting this file type requires the Dicom capability license.Upload DICOM a licence neposkytuje DicomPoužijte licenci, která poskytuje Dicom
run odpovídá 400 That target format is not available for this file.Cíl není jedním z allowedTargets zdrojeNabídněte pouze allowedTargets z convert=open
run nebo download odpovídá 404 (Upload expired — please re-open the file. z run)30‑minutové okno uplynulo, nebo jiný server ve farmě nemá uploadOtevřete soubor znovu; ve farmě zaregistrujte AddDoconutDistributedWidgets
Widget selže, když je UI na jiném původuKoncové body nemají podporu CORSPodávejte UI ze stejného původu, nebo použijte reverse-proxy pro cesty Doconut
Téma se neaplikujeProměnné jsou nastaveny na předka nebo na prvek uvnitř mountu; vlastní pravidlo widgetu .dcw je nastavuje na mountCílem je samotný mount: #doconut-convert.dcw nebo #doconut-convert

Poznámky k frameworku

Ve srovnání s balíčky ASP.NET Core se tento balíček liší pouze v hostování; API, smlouva o koncových bodech, skript widgetu a licenční pravidla jsou stejné.

  • Registrace je v Application_Start, přes DoconutHost.Initialize, místo builder.Services.AddDoconut. Služby jako AddDoconutDistributedWidgets jdou do jeho druhého argumentu.
  • Koncové body jsou poskytovány pomocí DocImage.axd a skript pomocí DoconutResourceModule, oba registrovaní v Web.config, místo UseDoconut() a UseDoconutResources(). Widget potřebuje basePath: '/DocImage.axd'.
  • Selhání při spuštění se projevují jako prázdný 500 u každého požadavku, s důvodem v Windows event logu.
  • Nahrávání je ASP.NET načítá celé před tím, než je Doconut vidí, takže limity IIS musí být nad MaxUploadMb.
  • Web Forms stránky nesmí blokovat při konverzi; viz Ve Web Forms.
  • Pouze Windows, stejně jako zbytek balíčku .NET Framework.

Byla tato stránka užitečná?