Dönüştürücü Eklentisi
Belgeleri 45 hedef formata dönüştürün
Converter eklentisi Doconut'u bir belge-dönüştürme hizmetine dönüştürür. DocumentConverter genel arabasının arkasındaki motoru ve — isteğe bağlı — DocImage.axd tarafından sunulan bir drop-in widget'ı sağlar, böylece belgeleri C#'tan, widget'tan veya kendinizin yazdığı bir ön uçtan dönüştürebilirsiniz.
| Yüzey | Ne zaman kullanılır |
|---|---|
DocumentConverter (C#) | Sunucuda, tarayıcı olmadan dönüştürürsünüz |
Yerleştirilebilir widget (doconutConverter.js) | Sayfanızda hazır bir yükleme, dönüştürme ve indirme ekranı istiyorsunuz |
HTTP endpoints on DocImage.axd (?convert=open|run|download) | Belgelendirilmiş bir sunucu sözleşmesine karşı kendi dönüşüm UI'nizi oluşturursunuz |
Paketi kurun
Install-Package Doconut.NETFramework.ConverterBu belgelerin açıkladığı sürüme eklentiyi sabitlemek için:
Install-Package Doconut.NETFramework.Converter -Version 26.10.0Doconut.NETFramework ile aynı sürümde Converter paketini tutun.
Eklentinin lisans dosyası Doconut.Viewer.Converter.lic, Doconut.Viewer.lic ile aynı klasöre konur; izleyici lisansı ile birlikte okunur.
Eklentiyi kaydedin
Her eklenti aynı şekilde kaydedilir: AddPlugin<TPlugin>(), DoconutHost.Initialize içinde, Application_Start'dan çağrılır.
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});Bu, C# arabiriminin ihtiyaç duyduğu her şeydir. Widget ve onun HTTP uç noktaları ayrı bir isteğe bağlı, AddConverterWidget() (bkz. Yerleştirilebilir widget).
Eklenti, Converter yeteneğini veren bir lisansa ihtiyaç duyar. Bir lisans olmadan, DoconutHost.Initialize, Application_Start'den bir istisna fırlatır:
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.System.Web içinde bu, her isteğin boş bir 500 ile yanıt verdiği anlamına gelir ve neden sadece Windows olay günlüğünde (kaynak ASP.NET) bulunur. Lisans yoksa, eski bir TRIAL dosyası, Converter içermeyen bir lisans ve sürüm penceresi dışındaki ücretli bir lisans için istisna fırlatır. Geçici Demo/NFR lisansları kabul edilir. Bkz. Lisans Kurulumu.
Lisanslama & filigran
| Lisans durumu | Başlangıç | Dönüştürme çıktısı |
|---|---|---|
Sürüm penceresi içinde Converter sağlayan ücretli görüntüleyici lisansı | Başlar | Temiz — watermarked: false |
| Aktif Geçici (Demo/NFR) lisans | Başlar | Dönüştürür, değerlendirme filigranı ile — watermarked: true |
| Süresi dolmuş Geçici (Demo/NFR) lisans | Başlar | Dönüştürür, değerlendirme filigranı ile — watermarked: true |
Lisans yok, eski bir TRIAL dosyası, Converter içermeyen bir lisans veya sürüm penceresi dışındaki ücretli bir lisans | Application_Start fırlatır; her istek boş bir 500 ile yanıt verir | — |
DocumentConverter arabirimi ve widget'ın ?convert=run işleyicisi aynı kuralı uygular. Bir entegrasyon, satın almadan önce değerlendirme lisansı üzerinde uçtan uca inşa edilebilir ve test edilebilir — sadece çıktı baytları değişir.
Bir DICOM kaynağı (.dcm, .ima) ayrıca Dicom yeteneğine ihtiyaç duyar. Olmadan, ConvertAsync bir LicenseException (Converting '.dcm' requires the Dicom capability license.) fırlatır ve widget'ın open'i 403 yanıt verir.
C#'dan Kullanım
Her dönüşüm, 0 konumunda konumlandırılmış bir seekable MemoryStream döndürür. DocumentConverter durum bilgisizdir: ihtiyacınız olduğu yerde DoconutHost.Services'den çözün ve serbestçe yeniden kullanın.
// DoconutHost.Services'tan DocumentConverter'ı çözün; yapıcı içsel olduğu için, asla `new` etmeyin.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);// sourceExtension baştaki noktayı içerir. password, belge korunmuyorsa null olur.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);Stream html = await converter.WordToHtmlAsync("report.docx", ct);// html: Word belgesine geri dönüştürülecek HTML'i tutan bir Stream, örneğin WordToHtmlAsync sonucunda elde edilen.
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);Yanlış yapılması kolay iki detay: akış aşırı yüklemesinde sourceExtension, baştaki nokta (".xlsx", "xlsx" değil) içermelidir, aksi takdirde çözülmez. Ve adı ne olursa olsun, WordToHtmlAsync Task<Stream> döndürür, Task<string> değil — HTML belge (Base64 olarak gömülü görüntüler) bir akış olarak gelir, diğer tüm sonuçlar gibi.
Çağıran, bir dönüşümün döndürdüğü MemoryStream'in sahibidir ve kopyaladıktan ya da döndürdükten sonra onu dispose etmelidir (MVC'nin File(stream, …) sizin için dispose eder). DocumentConverter'i kendiniz oluşturmayın veya dispose etmeyin — yapıcı içtedir.
MVC 5 denetleyicisinde
Eylemi asenkron yapın ve dönüşümü await:
[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");
}Web Forms'ta: dönüşümde asla engelleme
Bir Web Forms sayfası tek iş parçacıklı bir istek bağlamında çalışır. ConvertAsync tamamlandığında o bağlamda devam eder, bu yüzden senkron olarak bekleyen bir sayfa — .Result, .Wait(), .GetAwaiter().GetResult() — dönüşümün bitmesi için gereken iş parçacığını tutar. İstek asla geri dönmez. Tarayıcı dönmeye devam eder, IIS hiçbir şey kaydetmez ve sitenin geri kalanı çalışmaya devam eder, bu yüzden bir kilitlenme yerine yavaş bir dönüşüm gibi görünür.
Sayfayı Async="true" işaretleyin ve dönüşümü bir sayfa async görevi olarak çalıştırın:
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>// Web Forms: @Page yönergesi Async="true" gerekir, ve dönüşüm bir sayfa async görevi olarak çalışır.
// Bunun üzerinde bloklama yapmak (.Result, .Wait(), .GetAwaiter().GetResult()) isteği deadlock eder:
// hiçbir zaman dönmez ve hiçbir şey kaydedilmez.
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, HttpContext.Current değil: bir await'tan sonra ikincisi null olabilir.
Context.ApplicationInstance.CompleteRequest();
}
}));
}Async="true" olmadan @Page yönergesinde, RegisterAsyncTask sessizce yok sayılır. Bir await sonrası, sayfanın Context kullanın; HttpContext.Current orada null olabilir.
Hedef formatlar
ConversionTarget (namespace Doconut.Configs.Conversion) 45 üyeye sahiptir:
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, IcoHer kaynak her hedefe dönüştürülmez: her kaynağın format ailesi (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project, PSD, web document, DICOM) kendi izin verilen hedef setine sahiptir. Bir DICOM kaynağını (.dcm, .ima) dönüştürmek ayrıca Dicom yeteneğini veren bir lisans gerektirir; hedefleri Pdf, Png, Jpeg, Bmp, Tiff ve Gif'dır. Bu enum'ı UI'nizin hedef listesi olarak sabit kodlamayın: ?convert=open, yüklenen dosya için allowedTargets döndürür ve bu, bir seçim kutusunu yönlendirmelidir.
Yerleştirilebilir widget
Uç noktaları etkinleştirin
Widget'ın ?convert=open|run|download uç noktaları DocImage.axd tarafından sunulur ve varsayılan olarak kapalıdır. Eklenti kaydının yanına bunları etkinleştirin:
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, Doconut bunu görmeden önce tüm yüklemeyi okur: maxRequestLength (KB) ve
// maxAllowedContentLength (bytes) değerini Web.config içinde widget's MaxUploadMb'nin üzerine koyun.AddConverterWidget() argümansız olarak widget'ı varsayılanlarla etkinleştirir (MaxUploadMb = 25). Tek başına dönüşüm hakları vermez: AddPlugin<ConverterPlugin>() gerekir, aksi takdirde DoconutHost.Initialize hata verir:
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.Widget hatalı davrandığında kontrol edilmesi gereken iki şey:
basePath: '/DocImage.axd'. Widget'ın varsayılanı,/doconut, ASP.NET Core uç noktasıdır. Bu pakette, uç noktalarWeb.config'den gelenDocImage.axdişleyicisidir.- Betik ve uç noktalar bağımsızdır. Kaynak modülü, widget etkin olsun ya da olmasın
doconutConverter.jssunar.AddConverterWidget()olmadan, widget yüklenir, bırakma bölgesini çizer ve tamamen doğru görünür — ve ilk eylemi404yanıtını verir.
Yükleme limitleri
ASP.NET, DocImage.axd çalışmadan önce tüm istek gövdesini okur. MaxUploadMb üzerindeki ancak sunucu limitlerinin altında kalan bir yükleme, widget'ın kendi JSON 413'ını (File is too large.) alır. Sunucu limitlerinin üzerindeki bir yükleme önce IIS tarafından reddedilir ve widget'ın okuyamayacağı bir hata sayfası gösterilir. Her iki sunucu limitini de widget'ın sınırının üzerindeki Web.config içinde tutun:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>Gömün
<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) bir CSS seçicisi ya da bir öğe alır, bağlama bulunamazsa hata fırlatır ve bir tutamaç döndürür. Widget bir dosya yükler, sayfa 1'in önizlemesini gösterir, kullanıcının allowedTargets'den birini seçmesine izin verir, dönüştürür, mümkün olduğunda sonucu önizler ve indirme seçeneği sunar.
Seçenekler
| Seçenek | Tür | Varsayılan | Notlar |
|---|---|---|---|
basePath | string | /doconut | Uç nokta URL'si. Bu pakette '/DocImage.axd' ayarlayın |
resPath | string | /doconut-res | Diğer Doconut widget'larıyla tutarlılık sağlamak için kabul edildi; dönüştürücü widget bundan herhangi bir URL oluşturmaz |
maxUploadMb | number | 25 | Yalnızca istemci tarafı ön kontrol; sunucu kendi sınırını uygular |
licenseUrl | string | null | null | Sonuç ekranındaki filigran bildirimini bir bağlantıya dönüştürür |
labels | object | {} | Widget'ın İngilizce metinlerinin herhangi bir alt kümesini geçersiz kılar |
Geri çağrılar
| Geri çağrı | Ne zaman tetiklenir | Yük |
|---|---|---|
onReady() | Widget düşürme ekranını render etti | — |
onSourceLoaded({ token, pages, sourceExt, allowedTargets }) | ?convert=open başarılı olduğunda | Kaynak token, sayfa sayısı, kaynak uzantı (başında nokta olmadan), izin verilen hedefler |
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target }) | ?convert=run başarılı olduğunda | Çalıştırma yanıtı ve istenen target |
onDownload({ downloadName, downloadToken }) | Kullanıcı İndir'e tıkladığında | Tarayıcının kendi indirmesiyle birlikte tetiklenir |
onError({ phase, message }) | Bir açma veya çalıştırma isteği başarısız olduğunda | phase, 'open' ya da 'run'; message, temizlenmiş sunucu hatasıdır |
Hata fırlatan bir geri çağrı yakalanır ve kaydedilir; widget'ın akışını asla bozmaz.
İmperatif tutamaç
Doconut.convert() widget örneğini döndürür:
const conv = Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd' });
const file = document.querySelector('#picker').files[0]; // kendi <input type="file" id="picker"> öğenizden bir File
conv.reset(); // bırakma ekranına geri dön; onReady yeniden tetiklenmez
conv.loadFile(file); // akışı bir File ile başlatır; widget bırakma ekranında değilse hiçbir işlem yapmaz
conv.destroy(); // dinleyicileri kaldırır, mount'ı boşaltır; bu işlemden sonra instance kullanılamazEtiketler
Her dize bir İngilizce varsayılan değere sahiptir; labels herhangi bir alt kümeyi geçersiz kılar ve geri kalanlar İngilizce kalır. Çalışma zamanında değişen parçalar {placeholders} kullanır, örneğin uploading: 'Uploading {name}…' ve pages: '{n} pages'.
| Anahtar | İngilizce varsayılan |
|---|---|
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. |
Diğer anahtarlar, bırakma bölgesinin aria-label (dropAriaLabel), önizleme alt metinlerini (previewAlt, resultAlt), licenseUrl ile kullanılan filigran bildiriminin bağlantılı biçimini (watermarkNoticePrefix, watermarkNoticeLink, watermarkNoticeSuffix), okunamayan bir yanıtı (badResponse) ve aria-live duyurularını (annReady, annUploading, annLoaded, annLoadedNoTargets, annConverting, annDone, annError) kapsar.
Sunucudan gelen bir JSON hatası, sunucunun yazdığı şekilde gösterilir; serverError yalnızca başarısız bir yanıt JSON hatası içermediğinde, örneğin devre dışı bırakılmış bir widget'ın 404 gibi durumlarda kullanılır.
Tema
Widget, dcw sınıfını bağlama öğesine ekler ve renklerini, yarıçapını ve yazı tipini CSS özel özelliklerinden okur, böylece iç yapısına dokunmadan temalandırabilirsiniz:
#doconut-convert.dcw {
--dcw-accent: #6b46c1;
--dcw-radius: 12px;
--dcw-font: "Inter", system-ui, sans-serif;
}Varsayılanlar: --dcw-accent: #2b6cb0, --dcw-bg: #ffffff, --dcw-fg: #1a202c, --dcw-muted: #718096, --dcw-border: #cbd5e0, --dcw-radius: 8px ve --dcw-font için bir sistem UI yazı tipi.
Kendi ön ucunuzu oluşturun
Widget, DocImage.axd üzerindeki bu HTTP sözleşmesi için bir istemcidir. Rotalar, AddConverterWidget() çağrılana kadar 404 yanıt verir. Hatalar JSON gövdesi taşır, { "error": "..." }, tablo "status only" dediği yerler hariç. Bilinmeyen bir ?convert= değeri 400 yanıt verir.
| Rota | Amaç | Başarılı yanıt |
|---|---|---|
POST /DocImage.axd?convert=open (multipart, one file) | Bir kaynak belgeyi yükleyin ve açın | 200 — { token, pages, sourceExt, allowedTargets } |
POST /DocImage.axd?token=<token>&convert=run&target=<ext> | Yüklenen kaynağı target'ye dönüştürün | 200 — { downloadToken, resultToken, resultPages, downloadName, watermarked } |
GET /DocImage.axd?convert=download&token=<downloadToken> | Dönüştürülmüş dosyayı akış olarak gönder | 200 — dosya, Content-Disposition: attachment, Cache-Control: no-store |
sourceExt, open yanıtında başında nokta ("docx") yoktur — ConvertAsync'un sourceExtension parametresinin tersidir. allowedTargets, küçük harf hedef adlarını listeler ("pdf", "html", …); bunlardan birini target olarak geçirin, büyük/küçük harfe duyarsız eşleşir. open, çok parçalı gövdedeki ilk dosyayı kullanır.
resultToken, null'dır ve sonuç ön izlenemediğinde resultPages, 0'dır. downloadName, hedefin uzantısıyla kaynak dosya adıdır.
Ön izleme görüntüleri standart görüntüleyici resim rotasını, /DocImage.axd?token={token}&page=1&thumb=1&width={px}, open'den gelen token veya run'den gelen resultToken ile kullanır. Widget, width=240 ister.
Yüklenen kaynaklar son okunduktan 30 dakika boyunca saklanır; ardından run, 404 yanıt verir ve dosya tekrar açılmalıdır. Dönüşüm tamamlandığında downloadToken kendi 30 dakikalık penceresini alır. resultToken, sonucu ön izlemek için sıradan bir görüntüleyici token'ıdır; sonuç ön izlenebildiğinde, değeri downloadToken ile aynıdır.
| Rota | Durum | Ne zaman | Gövde |
|---|---|---|---|
| herhangi | 404 | Widget etkinleştirilmemiş (AddConverterWidget() hiç çağrılmadı) | status only |
| herhangi | 405 | Yanlış fiil (open/run, POST gerektirir, download, GET gerektirir) | status only |
open | 400 | Çok parçalı bir yükleme değil | Expected a multipart file upload. |
open | 400 | Dosya yok veya boş | No file uploaded. |
open | 400 | Dönüştürülemeyen bir tür | This file type cannot be converted. |
open | 403 | Dosya türü, lisansın vermediği bir yetenek gerektirir (Dicom olmadan bir DICOM dosyası) | Converting this file type requires the Dicom capability license. |
open | 413 | Yükleme, MaxUploadMb değerini aşıyor (ancak IIS limitlerini aşmıyor) | File is too large. |
run | 400 | Bozuk bir token (GUID değil) | Invalid token. |
run | 400 | Bir target, bir ConversionTarget'a ayrıştırılamıyor | Unknown target format. |
run | 400 | allowedTargets içinde olmayan bir hedef | That target format is not available for this file. |
run | 404 | Yükleme süresi doldu veya hiç açılmadı | Upload expired — please re-open the file. |
open, run | 500 | İşleme başarısız oldu | Temizlenmiş bir mesaj |
download | 400 / 404 | Bozuk, bilinmeyen veya süresi dolmuş bir indirme token'ı | status only |
fetch ile tam bir tur:
// file: dönüştürülecek Dosya, örneğin bir <input type="file"> öğesinden.
async function convertFile(file) {
const base = '/DocImage.axd';
// 1. open: dosyayı yükle
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: izin verildiğinde PDF'ye dönüştür, aksi takdirinde ilk izin verilen hedefe
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: tarayıcının takip edebileceği basit bir GET
window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}Uç noktalar same-origin'dır: bu sürüm CORS desteği içermez. UI'nizi ve widget betiğini Doconut ile aynı origin'den sunun, ya da işleyiciyi ve kaynak yollarını UI'nizin origin'i altında ters proxy yapın.
Üretimde
- Eklentiyi kurun çekirdek paketinin yanına, aynı sürümde:
Install-Package Doconut.NETFramework.Converter. - Lisans dosyasını ekleyin.
Doconut.Viewer.Converter.lic'yiDoconut.Viewer.licile aynı klasöre yerleştirin. - Yükleme sınırlarını ayarlayın.
MaxUploadMb,AddConverterWidgetiçinde Doconut'un uyguladığı sınırdır;maxRequestLengthvemaxAllowedContentLength,Web.configiçinde bu sınırın üzerinde tutun (bkz. Yükleme sınırları), ve widget'ınmaxUploadMb'ı ona eşit olsun. - Web Forms'ta bir dönüşümde asla bloklamayın (bkz. Web Forms'ta).
- Dönüşüm sonuçlarını serbest bırakın.
ConvertAsyncakışı havuzlanmıştır; serbest bırakmak, tamponlarını havuza geri verir.
Web çiftlikleri
Widget, her yüklemeyi ve sonucunu, open'ı hizmet veren sunucuda bellekte tutar. Yapışkan oturumlar olmadan bir yük dengeleyicinin arkasında, daha sonraki bir run, download veya önizleme isteği başka bir sunucuya ulaşabilir ve yüklemeyi bulamaz. Paylaşılan, şifreli widget deposunu DoconutHost.Initialize'nin ikinci argümanı aracılığıyla kaydedin:
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"; // her sunucunun okuyup yazabileceği bir klasör
store.FarmKey = farmKey; // en az 32 bayt, her sunucuda aynı
// store.Ttl = TimeSpan.FromMinutes(30); // bir yüklemenin ne kadar süre saklandığı (varsayılan)
}));- Tek bir sunucu hiçbir şeye ihtiyaç duymaz: bu çağrı olmadan bellek içi mağaza kullanılır.
- Yüklemeler ve sonuçlar paylaşılda dinlenirken şifrelenir (AES-256, encrypt-then-MAC) ve her dosya token'ına bağlanır, böylece bir token başka birinin dosyasını asla okuyamaz.
- Paylaşılda, bir yükleme veya sonuç, yazıldıktan sonra
Ttlsüreyle tutulur; okuma bu süreyi uzatmaz. FarmKeyen az 32 bayt olmalı ve her sunucuda aynı olmalıdır. Gizli bir depodan yükleyin; asla sabit kodlamayın. Kayıt,RootPatheksik olduğunda veyaFarmKey32 bayttan kısa olduğunda birArgumentExceptionfırlatır.RootPath'i dağıtılmış görüntüleyicinin kullandığı aynı paylaşılan konuma yönlendirin.
API referansı
Facade ve widget seçenekleri Doconut ad alanındadır; ConversionTarget, Doconut.Configs.Conversion içinde bulunur. ConverterPlugin, Doconut.Plugins.Converter içinde bulunur.
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);
}DoconutHost.Services'den çözümlenir; yapıcı dahili. sourceExtension, baştaki noktayı içerir. HtmlToWordAsync, outputFormat ConversionTarget.Doc olduğunda bir .doc dosyası yazar ve diğer tüm değerler için bir .docx dosyası yazar.
ConversionTarget
45 çıktı formatı Hedef formatları içinde listelenmiştir.
ConverterWidgetOptions
public sealed class ConverterWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
}DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null) aracılığıyla ayarlanır, bu da DoconutOptions döndürür, böylece çağrılar zincirlenebilir.
Sorun Giderme
| Semptom | Neden | Düzeltme |
|---|---|---|
Eklentiyi ekledikten sonra her istek boş bir 500 yanıtı verir; Windows olay günlüğü (kaynak ASP.NET) The Converter plugin is registered via AddPlugin but no active license grants Converter. gösterir | Lisans yok, bir TRIAL dosyası, Converter içermeyen bir lisans veya sürüm penceresinin dışında bir ücretli lisans | Converter sağlayan bir lisans kurun veya AddPlugin<ConverterPlugin>() kaldırın |
Her istek boş bir 500 yanıtı verir; olay günlüğü AddConverterWidget() was called but the Converter plugin is not registered. gösterir | Widget, eklentisi olmadan etkinleştirilmiş | options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() ekleyin |
DocumentConverter çözülürken No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>(). hatası atılır | ConverterPlugin kayıtlı değil | DoconutHost.Initialize içinde AddPlugin<ConverterPlugin>() ekleyin |
| Web Forms dönüşümü hiçbir zaman geri dönmez | Sayfa ConvertAsync üzerinde bloklanıyor | Async="true" ve RegisterAsyncTask kullanın |
| Akış dönüşümü formatın desteklenmediğini söylüyor | sourceExtension başında nokta yok | "xlsx" yerine ".xlsx" geçirin |
ConvertAsync Converting '.dcm' requires the Dicom capability license. hatası atıyor | Bir DICOM kaynağı ve lisans Dicom sağlamıyor | Dicom sağlayan bir lisans kullanın |
| Çıktı su işareti taşıyor | Lisans geçici (Demo/NFR) | Converter sağlayan bir ücretli lisans kullanın |
Widget yükleniyor ancak istekleri 404 döndürüyor | AddConverterWidget() çağrılmadı veya basePath '/DocImage.axd' değil | AddConverterWidget() çağırın; basePath: '/DocImage.axd' ayarlayın |
| Büyük bir yükleme, widget mesajı yerine bir IIS hata sayfası gösteriyor | maxRequestLength / maxAllowedContentLength MaxUploadMb altında | Web.config limitlerini MaxUploadMb üzerine yükseltin |
open 403 Converting this file type requires the Dicom capability license. yanıtı veriyor | Bir DICOM yüklemesi ve lisans Dicom sağlamıyor | Dicom sağlayan bir lisans kullanın |
run 400 That target format is not available for this file. yanıtı veriyor | Hedef, kaynağın allowedTargets'lerinden biri değil | convert=open'den sadece allowedTargets sunun |
run veya download 404 yanıtı verir (Upload expired — please re-open the file. run'den) | 30 dakikalık pencere geçti veya bir çiftlikteki başka bir sunucuda yükleme yok | Dosyayı tekrar açın; bir çiftlikte AddDoconutDistributedWidgets kaydedin |
| Widget, UI başka bir kökende olduğunda başarısız olur | Uç noktalar CORS desteğine sahip değil | UI'yi aynı kökenden sunun veya Doconut yollarını ters proxy yapın |
| Tema uygulanmıyor | Değişkenler bir üst öğede veya mount içindeki bir öğede ayarlanmış; widget'ın kendi .dcw kuralı onları mount üzerine ayarlar | Mount'u doğrudan hedefleyin: #doconut-convert.dcw veya #doconut-convert |
Çerçeve notları
ASP.NET Core paketleriyle karşılaştırıldığında, bu paket yalnızca barındırma açısından farklıdır; API, uç nokta sözleşmesi, widget betiği ve lisans kuralları aynıdır.
- Kayıt
Application_Startiçinde,DoconutHost.Initializearacılığıyla,builder.Services.AddDoconutyerine yapılır.AddDoconutDistributedWidgetsgibi hizmetler ikinci argümanına gider. - Uç noktalar
DocImage.axdtarafından ve betikDoconutResourceModuletarafından sunulur, ikisi deWeb.configiçinde kayıtlı,UseDoconut()veUseDoconutResources()yerine. WidgetbasePath: '/DocImage.axd'gerektirir. - Başlangıç hataları her istekte boş bir
500olarak ortaya çıkar, neden Windows olay günlüğünde bulunur. - Yüklemeler ASP.NET tarafından Doconut görmeden önce tamamen okunur, bu yüzden IIS limitleri
MaxUploadMb'nin üzerinde olmalıdır. - Web Forms sayfaları bir dönüşümde bloklanmamalıdır; bkz. Web Forms içinde.
- Yalnızca Windows, .NET Framework paketinin geri kalanları gibi.
Bu sayfa yardımcı oldu mu?