Wtyczka konwertera

Konwertuj dokumenty do 45 formatów docelowych

Wtyczka Converter przekształca Doconut w usługę konwersji dokumentów. Dostarcza silnik stojący za publiczną fasadą DocumentConverter oraz — opcjonalnie — gotowy widget udostępniany przez DocImage.axd, dzięki czemu możesz konwertować dokumenty z C#, z widgetu lub z własnego frontendu.

PowierzchniaKiedy używać
DocumentConverter (C#)Konwertujesz na serwerze, bez udziału przeglądarki
Drop-in widget (doconutConverter.js)Chcesz gotowy ekran przesyłania, konwersji i pobierania na swojej stronie
HTTP endpoints on DocImage.axd (?convert=open|run|download)Budujesz własny interfejs konwersji w oparciu o udokumentowany kontrakt serwera

Zainstaluj pakiet

powershell
Install-Package Doconut.NETFramework.Converter

Aby przypiąć wtyczkę do wersji opisanej w tej dokumentacji:

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

Utrzymuj pakiet Converter w tej samej wersji co Doconut.NETFramework.

Plik licencji wtyczki, Doconut.Viewer.Converter.lic, znajduje się w tym samym folderze co Doconut.Viewer.lic; jest odczytywany razem z licencją przeglądarki.

Zarejestruj wtyczkę

Każda wtyczka rejestruje się w ten sam sposób: AddPlugin<TPlugin>() w DoconutHost.Initialize, wywoływana z Application_Start.

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

To wszystko, czego potrzebuje fasada C#. Widget i jego endpointy HTTP są oddzielnym, opcjonalnym elementem, AddConverterWidget() (zobacz Widget do wstawiania).

Wtyczka wymaga licencji, która przyznaje możliwość Converter. Bez niej, DoconutHost.Initialize zgłasza wyjątek 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.

W System.Web oznacza to, że każde żądanie zwraca pusty 500, a przyczyna jest widoczna tylko w dzienniku zdarzeń Windows (źródło ASP.NET). Zgłasza wyjątek przy braku licencji, przy starszym pliku TRIAL, przy licencji bez Converter oraz przy płatnej licencji użytej poza jej okresem wersji. Tymczasowe licencje Demo/NFR są akceptowane. Zobacz Ustawienia licencji.

Licencjonowanie i znak wodny

Stan licencjiUruchomienieWynik konwersji
Płatna licencja przeglądarki przyznająca Converter, w ramach swojego okna wersjiUruchamia sięCzysty — watermarked: false
Aktywna tymczasowa licencja (Demo/NFR)Uruchamia sięKonwertuje, z znakiem wodnym oceny — watermarked: true
Wygasła tymczasowa licencja (Demo/NFR)Uruchamia sięKonwertuje, z znakiem wodnym oceny — watermarked: true
Brak licencji, starszy plik TRIAL, licencja bez Converter lub płatna licencja poza oknem wersjiApplication_Start zgłasza wyjątek; każde żądanie zwraca pusty 500—

Fasada DocumentConverter i obsługa ?convert=run widgetu stosują tę samą zasadę. Integrację można zbudować i przetestować od początku do końca na licencji ewaluacyjnej przed zakupem — zmieniają się tylko bajty wyjściowe.

Źródło DICOM (.dcm, .ima) również wymaga możliwości Dicom. Bez tego, ConvertAsync zgłasza LicenseException (Converting '.dcm' requires the Dicom capability license.), a obsługa open widgetu odpowiada 403.

Użycie z C#

Każda konwersja zwraca przeszukiwalny MemoryStream ustawiony na 0. DocumentConverter jest bezstanowy: uzyskaj go z DoconutHost.Services gdziekolwiek potrzebujesz i używaj wielokrotnie.

csharp
// Rozwiąż DocumentConverter z DoconutHost.Services; jego konstruktor jest wewnętrzny, więc nigdy nie `new` go.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);
csharp
// sourceExtension zawiera wiodącą kropkę. password jest null, chyba że dokument jest chroniony.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);
csharp
Stream html = await converter.WordToHtmlAsync("report.docx", ct);
csharp
// html: strumień zawierający HTML, który ma zostać przekształcony z powrotem w dokument Word, np. wynik WordToHtmlAsync.
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Dwa szczegóły, które łatwo pomylić: sourceExtension w przeciążeniu strumienia musi zawierać wiodącą kropkę (".xlsx", nie "xlsx"), w przeciwnym razie nie zostanie rozpoznany. I pomimo nazwy, WordToHtmlAsync zwraca Task<Stream>, a nie Task<string> — dokument HTML (obrazy osadzone jako Base64) przychodzi jako strumień, tak jak każdy inny wynik.

Wywołujący posiada MemoryStream zwracany przez konwersję i powinien go zwolnić po skopiowaniu lub zwróceniu (MVC's File(stream, …) zwalnia go za Ciebie). Nie twórz ani nie zwalniaj DocumentConverter samodzielnie — jego konstruktor jest wewnętrzny.

W kontrolerze MVC 5

Uczyń akcję asynchroniczną i await konwersję:

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");
}

W Web Forms: nigdy nie blokuj konwersji

Strona Web Forms działa w jednowątkowym kontekście żądania. ConvertAsync wznawia się w tym kontekście po zakończeniu, więc strona, która czeka na nią synchronicznie — .Result, .Wait(), .GetAwaiter().GetResult() — zajmuje wątek, którego konwersja potrzebuje do zakończenia. Żądanie nigdy nie wraca. Przeglądarka wciąż się kręci, IIS nie zapisuje nic, a reszta witryny działa, więc wygląda to jak wolna konwersja, a nie zakleszczenie.

Oznacz stronę Async="true" i uruchom konwersję jako asynchroniczne zadanie strony:

aspx
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>
csharp
// Web Forms: dyrektywa @Page wymaga Async="true", a konwersja działa jako asynchroniczne zadanie strony.
// Blokowanie na tym zamiast (.Result, .Wait(), .GetAwaiter().GetResult()) powoduje zakleszczenie żądania:
// nigdy nie zwraca, i nic nie jest logowane.
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, a nie HttpContext.Current: po await druga może być nullem.
            Context.ApplicationInstance.CompleteRequest();
        }
    }));
}

Bez Async="true" w dyrektywie @Page, RegisterAsyncTask jest cicho ignorowane. Po await użyj Context strony; HttpContext.Current może być null tam.

Formaty docelowe

ConversionTarget (przestrzeń nazw Doconut.Configs.Conversion) ma 45 elementów:

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

Nie każdy źródłowy format konwertuje na każdy docelowy: każda rodzina formatów źródłowych (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project, PSD, dokument internetowy, DICOM) ma własny zestaw dozwolonych celów. Konwersja źródła DICOM (.dcm, .ima) wymaga również licencji, która zapewnia możliwość Dicom; jej cele to Pdf, Png, Jpeg, Bmp, Tiff i Gif. Nie koduj na stałe tego wyliczenia jako listy docelowej w interfejsie użytkownika: ?convert=open zwraca allowedTargets dla przesłanego pliku i to powinno sterować selektorem.

Wbudowany widget

Włącz punkty końcowe

Punkty końcowe ?convert=open|run|download widgetu są obsługiwane przez DocImage.axd i są wyłączone domyślnie. Włącz je obok rejestracji wtyczki:

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 odczytuje cały upload zanim Doconut go zobaczy: zachowaj maxRequestLength (KB) oraz
// maxAllowedContentLength (bytes) w Web.config powyżej MaxUploadMb widgetu.

AddConverterWidget() bez argumentu włącza widget z domyślnymi ustawieniami (MaxUploadMb = 25). Nie przyznaje on samodzielnie praw do konwersji: potrzebuje AddPlugin<ConverterPlugin>(), w przeciwnym razie DoconutHost.Initialize zgłasza błąd:

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.

Dwie rzeczy do sprawdzenia, gdy widget zachowuje się nieprawidłowo:

  • basePath: '/DocImage.axd'. Domyślny punkt końcowy widgetu, /doconut, jest punktem końcowym ASP.NET Core. W tym pakiecie punkty końcowe są obsługiwane przez DocImage.axd z Web.config.
  • Skrypt i punkty końcowe są niezależne. Moduł zasobów udostępnia doconutConverter.js niezależnie od tego, czy widget jest włączony. Bez AddConverterWidget() widget ładuje się, rysuje swoją strefę upuszczania i wygląda całkowicie poprawnie — a jego pierwsza akcja odpowiada 404.

Limity przesyłania

ASP.NET odczytuje całe ciało żądania przed uruchomieniem DocImage.axd. Przesył powyżej MaxUploadMb, ale poniżej limitów hosta, otrzymuje własny JSON 413 widgetu (File is too large.). Przesył powyżej limitów hosta jest najpierw odrzucany przez IIS, z stroną błędu, której widget nie może odczytać. Utrzymaj oba limity hosta w Web.config powyżej limitu widgetu:

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

Osadź to

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) przyjmuje selektor CSS lub element, rzuca wyjątek, jeśli punkt montowania nie zostanie znaleziony, i zwraca uchwyt. Widget przesyła plik, wyświetla podgląd strony 1, pozwala użytkownikowi wybrać jeden z allowedTargets, konwertuje, podgląda wynik, gdy jest to możliwe, i oferuje pobranie.

Opcje

OpcjaTypDomyślnieUwagi
basePathstring/doconutAdres URL punktu końcowego. Ustaw '/DocImage.axd' w tym pakiecie
resPathstring/doconut-resAkceptowane dla spójności z innymi widgetami Doconut; widget konwertera nie buduje z tego żadnego URL
maxUploadMbnumber25Tylko wstępna weryfikacja po stronie klienta; serwer wymusza własny limit
licenseUrlstring | nullnullZamienia powiadomienie o znaku wodnym na ekranie wyniku w link
labelsobject{}Zastępuje dowolny podzbiór angielskich ciągów widgetu

Wywołania zwrotne

Wywołanie zwrotneWywoływane gdyŁadunek
onReady()Widget wyświetlił ekran upuszczania—
onSourceLoaded({ token, pages, sourceExt, allowedTargets })?convert=open zakończy się sukcesemToken źródła, liczba stron, rozszerzenie źródła (bez wiodącej kropki), dozwolone cele
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target })?convert=run zakończy się sukcesemOdpowiedź uruchomienia plus żądany target
onDownload({ downloadName, downloadToken })Użytkownik kliknie PobierzWywoływane równocześnie z własnym pobraniem przeglądarki
onError({ phase, message })Żądanie otwarcia lub uruchomienia nie powiedzie sięphase jest 'open' lub 'run'; message to oczyszczony błąd serwera

Wywołanie zwrotne, które rzuca wyjątek, jest przechwytywane i logowane; nigdy nie przerywa przepływu widgetu.

Imperatywny uchwyt

Doconut.convert() zwraca instancję widgetu:

javascript
const conv = Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd' });
const file = document.querySelector('#picker').files[0]; // Plik z własnego <input type="file" id="picker">
conv.reset();         // powrót do ekranu upuszczania; nie wywołuje ponownie onReady
conv.loadFile(file);  // rozpoczyna przepływ z File; no-op chyba że widget jest na ekranie upuszczania
conv.destroy();       // usuwa nasłuchiwacze, opróżnia mount; instancja jest nieużyteczna po tym

Etykiety

Każdy ciąg ma domyślnie angielską wersję; labels zastępuje dowolny podzbiór, a reszta pozostaje po angielsku. Fragmenty zmieniające się w czasie działania używają {placeholders}, takie jak uploading: 'Uploading {name}…' i pages: '{n} pages'.

KluczDomyślnie po angielsku
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.

Dalsze klucze obejmują aria-label strefy upuszczania (dropAriaLabel), teksty podglądu alt (previewAlt, resultAlt), powiązaną formę powiadomienia o znaku wodnym używaną z licenseUrl (watermarkNoticePrefix, watermarkNoticeLink, watermarkNoticeSuffix), nieczytelną odpowiedź (badResponse) oraz ogłoszenia aria-live (annReady, annUploading, annLoaded, annLoadedNoTargets, annConverting, annDone, annError).

Błąd JSON z serwera jest wyświetlany tak, jak serwer go zapisał; serverError jest używany tylko wtedy, gdy nieudana odpowiedź nie zawiera błędu JSON, na przykład 404 wyłączonego widgetu.

Tematyzacja

Widżet dodaje klasę dcw do elementu montującego i odczytuje jego kolory, promień oraz czcionkę z niestandardowych właściwości CSS, dzięki czemu możesz go tematyzować bez modyfikowania jego wnętrza:

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

Domyślne: --dcw-accent: #2b6cb0, --dcw-bg: #ffffff, --dcw-fg: #1a202c, --dcw-muted: #718096, --dcw-border: #cbd5e0, --dcw-radius: 8px oraz systemowa czcionka UI dla --dcw-font.

Zbuduj własny frontend

Widżet jest klientem tego kontraktu HTTP na DocImage.axd. Trasy zwracają 404 aż do wywołania AddConverterWidget(). Błędy zawierają ciało JSON, { "error": "..." }, z wyjątkiem przypadków, gdy tabela podaje „status only”. Nieznana wartość ?convert= zwraca 400.

ŚcieżkaCelOdpowiedź sukcesu
POST /DocImage.axd?convert=open (multipart, jeden plik)Prześlij i otwórz dokument źródłowy200 — { token, pages, sourceExt, allowedTargets }
POST /DocImage.axd?token=<token>&convert=run&target=<ext>Konwertuj przesłane źródło na target200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET /DocImage.axd?convert=download&token=<downloadToken>Strumieniuj przekonwertowany plik200 — plik, Content-Disposition: attachment, Cache-Control: no-store

sourceExt w odpowiedzi open nie ma wiodącej kropki ("docx") — jest to przeciwieństwo parametru sourceExtension w ConvertAsync. allowedTargets wymienia nazwy docelowe w małych literach ("pdf", "html", …); przekaż jedną z nich jako target, która jest dopasowywana bez uwzględniania wielkości liter. open używa pierwszego pliku w treści multipart.

resultToken jest null, a resultPages jest 0, gdy wynik nie może być podglądany. downloadName to nazwa pliku źródłowego z rozszerzeniem docelowym.

Obrazy podglądu używają standardowej ścieżki obrazu przeglądarki, /DocImage.axd?token={token}&page=1&thumb=1&width={px}, z token z open lub resultToken z run. Widżet żąda width=240.

Przesłane źródła są przechowywane przez 30 minut po ostatnim odczycie; po tym czasie run zwraca 404 i plik musi zostać ponownie otwarty. downloadToken otrzymuje własne 30‑minutowe okno po zakończeniu konwersji. resultToken jest zwykłym tokenem przeglądarki do podglądu wyniku; gdy wynik może być podglądany, ma tę samą wartość co downloadToken.

ŚcieżkaStatusKiedyTreść
dowolny404Widżet nie jest włączony (AddConverterWidget() nigdy nie został wywołany)tylko status
dowolny405Nieprawidłowy czasownik (open/run wymagają POST, download wymaga GET)tylko status
open400Nie jest to przesyłanie multipartExpected a multipart file upload.
open400Brak pliku lub jest pustyNo file uploaded.
open400Typ, którego nie można skonwertowaćThis file type cannot be converted.
open403Typ pliku wymaga funkcji, której licencja nie przyznaje (plik DICOM bez Dicom)Converting this file type requires the Dicom capability license.
open413Przesyłanie przekracza MaxUploadMb (ale nie limity IIS)File is too large.
run400Zniekształcony token (nie jest GUID)Invalid token.
run400target, który nie parsuje do ConversionTargetUnknown target format.
run400Docelowy nie znajduje się w allowedTargetsThat target format is not available for this file.
run404Przesyłanie wygasło lub nigdy nie zostało otwarteUpload expired — please re-open the file.
open, run500Przetwarzanie nie powiodło sięZsanityzowana wiadomość
download400 / 404Zniekształcony, nieznany lub wygasły token pobieraniatylko status

Pełny cykl z fetch:

javascript
// file: Plik do konwersji, na przykład z <input type="file">.
async function convertFile(file) {
  const base = '/DocImage.axd';

  // 1. open: prześlij plik
  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: konwertuj do PDF, gdy jest dozwolone, w przeciwnym razie do pierwszego dozwolonego celu
  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: zwykłe żądanie GET, które przeglądarka może wykonać
  window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}

Punkty końcowe są same-origin: ta wersja nie obsługuje CORS. Udostępnij swój interfejs UI oraz skrypt widżetu z tego samego pochodzenia co Doconut, lub użyj reverse-proxy dla obsługi i ścieżek zasobów pod pochodzeniem Twojego UI.

W produkcji

  1. Zainstaluj wtyczkę obok pakietu podstawowego, w tej samej wersji: Install-Package Doconut.NETFramework.Converter.
  2. Dodaj plik licencji. Umieść Doconut.Viewer.Converter.lic w tym samym folderze co Doconut.Viewer.lic.
  3. Ustaw limity przesyłania. MaxUploadMb w AddConverterWidget jest limitem narzuconym przez Doconut; utrzymaj maxRequestLength i maxAllowedContentLength w Web.config powyżej niego (zobacz Limity przesyłania), oraz maxUploadMb widżetu równe temu.
  4. Nigdy nie blokuj konwersji w Web Forms (zobacz W Web Forms).
  5. Zwolnij wyniki konwersji. Strumień ConvertAsync zwracany jest z puli; zwalnianie go zwraca jego bufory do puli.

Farmy serwerowe

Widżet przechowuje każde przesłanie i jego wynik w pamięci na serwerze, który obsłużył open. Za load balancerem bez sesji przyklejonych, późniejsze żądanie run, download lub podglądu może trafić na inny serwer i nie znaleźć przesłania. Zarejestruj współdzielony, zaszyfrowany magazyn widżetu przez drugi argument 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";   // folder, który każdy serwer może odczytywać i zapisywać
        store.FarmKey = farmKey;                   // co najmniej 32 bajtów, identyczne na każdym serwerze
        // store.Ttl = TimeSpan.FromMinutes(30);   // jak długo przesył jest przechowywany (domyślnie)
    }));
  • Jeden serwer nie potrzebuje niczego: bez tego wywołania używany jest magazyn w pamięci.
  • Przesyłki i wyniki są szyfrowane w spoczynku na udziale (AES-256, encrypt-then-MAC), a każdy plik jest powiązany ze swoim tokenem, więc jeden token nigdy nie może odczytać pliku innego.
  • Na udziale, przesyłka lub wynik jest przechowywany przez Ttl po zapisaniu; odczytanie go nie wydłuża tego okna.
  • FarmKey musi mieć co najmniej 32 bajty i być taki sam na każdym serwerze. Załaduj go z tajnego magazynu; nigdy nie koduj na stałe. Rejestracja rzuca ArgumentException gdy RootPath jest brakujący lub FarmKey jest krótszy niż 32 bajty.
  • Wskaż RootPath na tę samą współdzieloną lokalizację, której używa rozproszony podgląd.

Referencja API

Fasada i opcje widżetu znajdują się w przestrzeni nazw Doconut; ConversionTarget jest w Doconut.Configs.Conversion. ConverterPlugin jest w 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);
}

Rozwiązywany z DoconutHost.Services; konstruktor jest wewnętrzny. sourceExtension zawiera wiodącą kropkę. HtmlToWordAsync zapisuje plik .doc, gdy outputFormat jest ConversionTarget.Doc, oraz plik .docx dla każdej innej wartości.

ConversionTarget

45 formatów wyjściowych wymienionych w Formatach docelowych.

ConverterWidgetOptions

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

Ustawiane przez DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null), który zwraca DoconutOptions, aby wywołania można było łańcuchować.

Rozwiązywanie problemów

ObjawPrzyczynaRozwiązanie
Każde żądanie zwraca pusty 500 po dodaniu wtyczki; dziennik zdarzeń Windows (źródło ASP.NET) pokazuje The Converter plugin is registered via AddPlugin but no active license grants Converter.Brak licencji, plik TRIAL, licencja bez Converter lub płatna licencja poza oknem wersjiZainstaluj licencję, która przyznaje Converter, lub usuń AddPlugin<ConverterPlugin>()
Każde żądanie zwraca pusty 500; dziennik zdarzeń pokazuje AddConverterWidget() was called but the Converter plugin is not registered.Widżet jest włączony bez swojej wtyczkiDodaj options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>()
Rozwiązywanie DocumentConverter powoduje błąd No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().ConverterPlugin nie jest zarejestrowanyDodaj AddPlugin<ConverterPlugin>() w DoconutHost.Initialize
Konwersja Web Forms nigdy nie zwracaStrona blokuje się na ConvertAsyncUżyj Async="true" i RegisterAsyncTask
Konwersja strumienia informuje, że format nie jest obsługiwanysourceExtension nie ma wiodącej kropkiPrzekaż ".xlsx", nie "xlsx"
ConvertAsync powoduje błąd Converting '.dcm' requires the Dicom capability license.Źródło DICOM i licencja nie przyznaje DicomUżyj licencji, która przyznaje Dicom
Wyjście jest oznaczone znakiem wodnymLicencja jest tymczasowa (Demo/NFR)Użyj płatnej licencji, która przyznaje Converter
Widżet ładuje się, ale jego żądania zwracają 404AddConverterWidget() nie został wywołany, lub basePath nie jest '/DocImage.axd'Wywołaj AddConverterWidget(); ustaw basePath: '/DocImage.axd'
Duży upload wyświetla stronę błędu IIS zamiast komunikatu widżetumaxRequestLength / maxAllowedContentLength są poniżej MaxUploadMbPodnieś limity Web.config powyżej MaxUploadMb
open odpowiada 403 Converting this file type requires the Dicom capability license.Upload DICOM i licencja nie przyznaje DicomUżyj licencji, która przyznaje Dicom
run odpowiada 400 That target format is not available for this file.Cel nie jest jednym z allowedTargets źródłaUdostępnij tylko allowedTargets z convert=open
run lub download odpowiada 404 (Upload expired — please re-open the file. z run)Upłynęło 30 minut, lub inny serwer w farmie nie ma uploaduOtwórz plik ponownie; w farmie zarejestruj AddDoconutDistributedWidgets
Widżet nie działa, gdy UI znajduje się na innym pochodzeniuPunkty końcowe nie obsługują CORSSerwuj UI z tego samego pochodzenia, lub użyj reverse-proxy dla ścieżek Doconut
Motyw nie jest stosowanyZmienne są ustawione na przodku lub na elemencie wewnątrz montażu; własna reguła .dcw widżetu ustawia je na montażuCeluj w sam montaż: #doconut-convert.dcw lub #doconut-convert

Notatki dotyczące frameworka

W porównaniu z pakietami ASP.NET Core, ten pakiet różni się wyłącznie pod względem hostingu; API, kontrakt punktu końcowego, skrypt widżetu i zasady licencjonowania są takie same.

  • Rejestracja znajduje się w Application_Start, przez DoconutHost.Initialize, zamiast builder.Services.AddDoconut. Usługi takie jak AddDoconutDistributedWidgets trafiają do drugiego argumentu.
  • Punkty końcowe są obsługiwane przez DocImage.axd i skrypt przez DoconutResourceModule, oba zarejestrowane w Web.config, zamiast UseDoconut() i UseDoconutResources(). Widżet wymaga basePath: '/DocImage.axd'.
  • Błędy uruchamiania pojawiają się jako pusty 500 przy każdym żądaniu, z przyczyną w dzienniku zdarzeń Windows.
  • Uploady są w pełni odczytywane przez ASP.NET przed tym, jak Doconut je zobaczy, więc limity IIS muszą być powyżej MaxUploadMb.
  • Strony Web Forms nie powinny blokować się na konwersji; zobacz W Web Forms.
  • Tylko Windows, tak jak reszta pakietu .NET Framework.

Czy ta strona była pomocna?