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.
| Powierzchnia | Kiedy 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
Install-Package Doconut.NETFramework.ConverterAby przypiąć wtyczkę do wersji opisanej w tej dokumentacji:
Install-Package Doconut.NETFramework.Converter -Version 26.10.0Utrzymuj 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.
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:
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 licencji | Uruchomienie | Wynik konwersji |
|---|---|---|
Płatna licencja przeglądarki przyznająca Converter, w ramach swojego okna wersji | Uruchamia 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 wersji | Application_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.
// 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);// 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);Stream html = await converter.WordToHtmlAsync("report.docx", ct);// 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ę:
[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:
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>// 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:
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, IcoNie 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:
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:
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 przezDocImage.axdzWeb.config.- Skrypt i punkty końcowe są niezależne. Moduł zasobów udostępnia
doconutConverter.jsniezależnie od tego, czy widget jest włączony. BezAddConverterWidget()widget ładuje się, rysuje swoją strefę upuszczania i wygląda całkowicie poprawnie — a jego pierwsza akcja odpowiada404.
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:
<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
<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
| Opcja | Typ | Domyślnie | Uwagi |
|---|---|---|---|
basePath | string | /doconut | Adres URL punktu końcowego. Ustaw '/DocImage.axd' w tym pakiecie |
resPath | string | /doconut-res | Akceptowane dla spójności z innymi widgetami Doconut; widget konwertera nie buduje z tego żadnego URL |
maxUploadMb | number | 25 | Tylko wstępna weryfikacja po stronie klienta; serwer wymusza własny limit |
licenseUrl | string | null | null | Zamienia powiadomienie o znaku wodnym na ekranie wyniku w link |
labels | object | {} | Zastępuje dowolny podzbiór angielskich ciągów widgetu |
Wywołania zwrotne
| Wywołanie zwrotne | Wywoływane gdy | Ładunek |
|---|---|---|
onReady() | Widget wyświetlił ekran upuszczania | — |
onSourceLoaded({ token, pages, sourceExt, allowedTargets }) | ?convert=open zakończy się sukcesem | Token ź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ę sukcesem | Odpowiedź uruchomienia plus żądany target |
onDownload({ downloadName, downloadToken }) | Użytkownik kliknie Pobierz | Wywoł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:
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 tymEtykiety
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'.
| Klucz | Domyślnie po angielsku |
|---|---|
dropPrompt | Drag & drop a document here |
dropHint | PDF, Word, Excel, PowerPoint, images and more |
chooseFile | Choose file |
uploading | Uploading {name}… |
page / pages | 1 page / {n} pages |
noTargets | No conversion targets are available for this file. |
convertTo / convert | Convert to / Convert |
converting | Converting to {target}… |
readyToDownload | Ready to download |
download / convertAnother | Download / Convert another |
watermarkNotice | Output is watermarked — get a license to remove it. |
retry | Retry |
genericError | Something went wrong. Please try again. |
sizeLimit | That file is larger than the {mb} MB upload limit. Please choose a smaller file. |
serverError | The server could not process this request. Please try again. |
networkError | Could 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:
#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żka | Cel | Odpowiedź sukcesu |
|---|---|---|
POST /DocImage.axd?convert=open (multipart, jeden plik) | Prześlij i otwórz dokument źródłowy | 200 — { token, pages, sourceExt, allowedTargets } |
POST /DocImage.axd?token=<token>&convert=run&target=<ext> | Konwertuj przesłane źródło na target | 200 — { downloadToken, resultToken, resultPages, downloadName, watermarked } |
GET /DocImage.axd?convert=download&token=<downloadToken> | Strumieniuj przekonwertowany plik | 200 — 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żka | Status | Kiedy | Treść |
|---|---|---|---|
| dowolny | 404 | Widżet nie jest włączony (AddConverterWidget() nigdy nie został wywołany) | tylko status |
| dowolny | 405 | Nieprawidłowy czasownik (open/run wymagają POST, download wymaga GET) | tylko status |
open | 400 | Nie jest to przesyłanie multipart | Expected a multipart file upload. |
open | 400 | Brak pliku lub jest pusty | No file uploaded. |
open | 400 | Typ, którego nie można skonwertować | This file type cannot be converted. |
open | 403 | Typ pliku wymaga funkcji, której licencja nie przyznaje (plik DICOM bez Dicom) | Converting this file type requires the Dicom capability license. |
open | 413 | Przesyłanie przekracza MaxUploadMb (ale nie limity IIS) | File is too large. |
run | 400 | Zniekształcony token (nie jest GUID) | Invalid token. |
run | 400 | target, który nie parsuje do ConversionTarget | Unknown target format. |
run | 400 | Docelowy nie znajduje się w allowedTargets | That target format is not available for this file. |
run | 404 | Przesyłanie wygasło lub nigdy nie zostało otwarte | Upload expired — please re-open the file. |
open, run | 500 | Przetwarzanie nie powiodło się | Zsanityzowana wiadomość |
download | 400 / 404 | Zniekształcony, nieznany lub wygasły token pobierania | tylko status |
Pełny cykl z fetch:
// 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
- Zainstaluj wtyczkę obok pakietu podstawowego, w tej samej wersji:
Install-Package Doconut.NETFramework.Converter. - Dodaj plik licencji. Umieść
Doconut.Viewer.Converter.licw tym samym folderze coDoconut.Viewer.lic. - Ustaw limity przesyłania.
MaxUploadMbwAddConverterWidgetjest limitem narzuconym przez Doconut; utrzymajmaxRequestLengthimaxAllowedContentLengthwWeb.configpowyżej niego (zobacz Limity przesyłania), orazmaxUploadMbwidżetu równe temu. - Nigdy nie blokuj konwersji w Web Forms (zobacz W Web Forms).
- Zwolnij wyniki konwersji. Strumień
ConvertAsynczwracany 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:
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
Ttlpo zapisaniu; odczytanie go nie wydłuża tego okna. FarmKeymusi 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 rzucaArgumentExceptiongdyRootPathjest brakujący lubFarmKeyjest krótszy niż 32 bajty.- Wskaż
RootPathna 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
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
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
| Objaw | Przyczyna | Rozwią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 wersji | Zainstaluj 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 wtyczki | Dodaj 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 zarejestrowany | Dodaj AddPlugin<ConverterPlugin>() w DoconutHost.Initialize |
| Konwersja Web Forms nigdy nie zwraca | Strona blokuje się na ConvertAsync | Użyj Async="true" i RegisterAsyncTask |
| Konwersja strumienia informuje, że format nie jest obsługiwany | sourceExtension nie ma wiodącej kropki | Przekaż ".xlsx", nie "xlsx" |
ConvertAsync powoduje błąd Converting '.dcm' requires the Dicom capability license. | Źródło DICOM i licencja nie przyznaje Dicom | Użyj licencji, która przyznaje Dicom |
| Wyjście jest oznaczone znakiem wodnym | Licencja jest tymczasowa (Demo/NFR) | Użyj płatnej licencji, która przyznaje Converter |
Widżet ładuje się, ale jego żądania zwracają 404 | AddConverterWidget() 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żetu | maxRequestLength / maxAllowedContentLength są poniżej MaxUploadMb | Podnieś limity Web.config powyżej MaxUploadMb |
open odpowiada 403 Converting this file type requires the Dicom capability license. | Upload DICOM i licencja nie przyznaje Dicom | Uż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ła | Udostę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 uploadu | Otwórz plik ponownie; w farmie zarejestruj AddDoconutDistributedWidgets |
| Widżet nie działa, gdy UI znajduje się na innym pochodzeniu | Punkty końcowe nie obsługują CORS | Serwuj UI z tego samego pochodzenia, lub użyj reverse-proxy dla ścieżek Doconut |
| Motyw nie jest stosowany | Zmienne są ustawione na przodku lub na elemencie wewnątrz montażu; własna reguła .dcw widżetu ustawia je na montażu | Celuj 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, przezDoconutHost.Initialize, zamiastbuilder.Services.AddDoconut. Usługi takie jakAddDoconutDistributedWidgetstrafiają do drugiego argumentu. - Punkty końcowe są obsługiwane przez
DocImage.axdi skrypt przezDoconutResourceModule, oba zarejestrowane wWeb.config, zamiastUseDoconut()iUseDoconutResources(). Widżet wymagabasePath: '/DocImage.axd'. - Błędy uruchamiania pojawiają się jako pusty
500przy 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?